GitHub

otlp_resource

API reference for otlp_resource.

The OTLP resource attached to every exported log, metric and span (Effect's OtlpResource), and the conversion of values into OTLP attribute values.

The payload types are the OTLP/JSON shapes, as plain dicts with the wire's camelCase keys, so OtlpSerialization writes them as they are.

Classes

Functions

instrumentation_scope

instrumentation_scope() -> _Scope

The instrumentation scope of the exported spans and logs: pyfect and its version (Effect's effect).

Returns _Scope

def instrumentation_scope() -> _Scope:
    """The instrumentation scope of the exported spans and logs: pyfect
    and its version (Effect's ``effect``)."""
    return {"name": "pyfect", "version": VERSION}

make

make(*, service_name=None, service_version=None, attributes=None) -> Resource

A resource with the telemetry.sdk.* defaults, then attributes, then the service name and version (an empty one adds nothing), later ones winning.

ParameterTypeDescription
service_namestr | None = None
service_versionstr | None = None
attributesMapping[str, object] | None = None

Returns Resource

def make(
    *,
    service_name: str | None = None,
    service_version: str | None = None,
    attributes: Mapping[str, object] | None = None,
) -> Resource:
    """A resource with the ``telemetry.sdk.*`` defaults, then
    ``attributes``, then the service name and version (an empty one adds
    nothing), later ones winning."""
    merged: dict[str, object] = {
        "telemetry.sdk.name": "pyfect",
        "telemetry.sdk.language": "python",
        "telemetry.sdk.version": VERSION,
        **(attributes or {}),
    }
    if service_name:
        merged["service.name"] = service_name
    if service_version:
        merged["service.version"] = service_version
    return {
        "attributes": entries_to_attributes(in_object_order(merged).items()),
        "droppedAttributesCount": 0,
    }

from_config

from_config(*, service_name=None, service_version=None, attributes=None) -> Effect[Resource]

A resource from the options and the OpenTelemetry configuration.

The service name is the first of service_name, the service.name attribute, OTEL_SERVICE_NAME and service.name in OTEL_RESOURCE_ATTRIBUTES; the version likewise, with OTEL_SERVICE_VERSION. attributes win over OTEL_RESOURCE_ATTRIBUTES. Missing or invalid configuration (no service name at all) is a defect.

ParameterTypeDescription
service_namestr | None = None
service_versionstr | None = None
attributesMapping[str, object] | None = None

Returns Effect[Resource]

def from_config(
    *,
    service_name: str | None = None,
    service_version: str | None = None,
    attributes: Mapping[str, object] | None = None,
) -> Effect[Resource]:
    """A resource from the options and the OpenTelemetry configuration.

    The service name is the first of ``service_name``, the
    ``service.name`` attribute, ``OTEL_SERVICE_NAME`` and ``service.name``
    in ``OTEL_RESOURCE_ATTRIBUTES``; the version likewise, with
    ``OTEL_SERVICE_VERSION``. ``attributes`` win over
    ``OTEL_RESOURCE_ATTRIBUTES``. Missing or invalid configuration (no
    service name at all) is a defect."""

    @gen
    def build():
        env: dict[str, str] | None = yield from resource_attributes().with_default(None)
        explicit = attributes or {}

        name: object = service_name
        if name is None:
            name = explicit.get("service.name")
        if name is None:
            name = _first((yield from config.string("OTEL_SERVICE_NAME").option()))
        if name is None and env is not None:
            name = env.get("service.name")
        if name is None:
            name = yield from config.string("OTEL_SERVICE_NAME")

        version: object = service_version
        if version is None:
            version = explicit.get("service.version")
        if version is None:
            version = _first((yield from config.string("OTEL_SERVICE_VERSION").option()))
        if version is None and env is not None:
            version = env.get("service.version")

        merged: dict[str, object] = {**(env or {}), **explicit}
        merged.pop("service.name", None)
        merged.pop("service.version", None)
        return make(
            service_name=name,  # pyright: ignore[reportArgumentType]
            service_version=version,  # pyright: ignore[reportArgumentType]
            attributes=merged,
        )

    return build.or_die()

from_options

from_options(options) -> Effect[Resource]

from_config with the options an exporter was given.

ParameterTypeDescription
optionsResourceOptions | None

Returns Effect[Resource]

def from_options(options: ResourceOptions | None) -> Effect[Resource]:
    """``from_config`` with the options an exporter was given."""
    given = options or {}
    return from_config(
        service_name=given.get("service_name"),
        service_version=given.get("service_version"),
        attributes=given.get("attributes"),
    )

service_name_unsafe

service_name_unsafe(resource) -> str

The resource's service.name; raises ValueError when it has no non-empty string one.

ParameterTypeDescription
resourceResource

Returns str

def service_name_unsafe(resource: Resource) -> str:
    """The resource's ``service.name``; raises ``ValueError`` when it has no
    non-empty string one."""
    for attribute in resource["attributes"]:
        if attribute["key"] == "service.name":
            name = attribute["value"].get("stringValue")
            if name:
                return name
            break
    raise ValueError("Resource does not contain a service name")

entries_to_attributes

entries_to_attributes(entries) -> list[KeyValue]

Each (key, value) as an OTLP attribute.

ParameterTypeDescription
entriesIterable[tuple[str, object]]

Returns list[KeyValue]

def entries_to_attributes(entries: Iterable[tuple[str, object]]) -> list[KeyValue]:
    """Each ``(key, value)`` as an OTLP attribute."""
    return [{"key": key, "value": unknown_to_attribute_value(value)} for key, value in entries]

unknown_to_attribute_value

unknown_to_attribute_value(value) -> AnyValue

value as an OTLP AnyValue: lists and tuples item by item, strings and booleans as they are, an int in the int64 range as intValue (past it as stringValue, as Effect writes a bigint), a whole float in that range as intValue (a JavaScript number is an integer when whole), other floats as doubleValue, and anything else as text (Effect's format). A list that holds itself is its text too (Effect's recursion overflows the stack, losing the batch).

ParameterTypeDescription
valueobject

Returns AnyValue

def unknown_to_attribute_value(value: object) -> AnyValue:
    """``value`` as an OTLP ``AnyValue``: lists and tuples item by item,
    strings and booleans as they are, an ``int`` in the int64 range as
    ``intValue`` (past it as ``stringValue``, as Effect writes a
    ``bigint``), a whole ``float`` in that range as ``intValue`` (a
    JavaScript number is an integer when whole), other floats as
    ``doubleValue``, and anything else as text (Effect's ``format``). A list that holds
    itself is its text too (Effect's recursion overflows the stack, losing the batch)."""
    return _attribute_value(value, frozenset())