Module adcp.observability

Optional OpenTelemetry tracing for AdCP client calls.

The module imports :mod:opentelemetry-api lazily. Without the optional dependency every helper is a no-op; with the API but no SDK/provider installed, OpenTelemetry's own non-recording provider keeps the same no-op behavior.

Only W3C Trace Context is propagated. Baggage is intentionally excluded from the cross-agent boundary because application baggage can contain sensitive or high-cardinality values.

Functions

def get_tracer() ‑> typing.Any | None

Expand source code

def get_tracer() -> Any | None:
    """Return the AdCP tracer, or ``None`` without OpenTelemetry installed."""

    bindings = _load_bindings()
    if bindings is None:
        return None
    return bindings.trace.get_tracer(_INSTRUMENTATION_NAME)

Return the AdCP tracer, or None without OpenTelemetry installed.

def inject_trace_headers(carrier: MutableMapping[str, str] | None = None) ‑> dict[str, str]

Expand source code

def inject_trace_headers(
    carrier: MutableMapping[str, str] | None = None,
) -> dict[str, str]:
    """Inject the active W3C trace context into a string header mapping.

    The returned dictionary contains the full resulting carrier.  Existing
    ``traceparent`` and ``tracestate`` values are replaced only when an active,
    valid OpenTelemetry span produces new values.  W3C baggage is never
    propagated by this helper.
    """

    result = {name: value for name, value in (carrier or {}).items() if name.lower() != "baggage"}
    bindings = _load_bindings()
    if bindings is None:
        return result

    injected: dict[str, str] = {}
    bindings.trace_context_propagator().inject(injected)
    if not injected:
        return result
    for existing_name in tuple(result):
        if existing_name.lower() in {"traceparent", "tracestate"}:
            result.pop(existing_name)
    for name in ("traceparent", "tracestate"):
        value = injected.get(name)
        if value is not None:
            result[name] = value
    return result

Inject the active W3C trace context into a string header mapping.

The returned dictionary contains the full resulting carrier. Existing traceparent and tracestate values are replaced only when an active, valid OpenTelemetry span produces new values. W3C baggage is never propagated by this helper.

def is_tracing_available() ‑> bool

Expand source code

def is_tracing_available() -> bool:
    """Return whether the optional OpenTelemetry API is installed.

    Availability does not imply that spans are exported.  Applications remain
    responsible for installing/configuring an OpenTelemetry SDK and exporter.
    """

    return _load_bindings() is not None

Return whether the optional OpenTelemetry API is installed.

Availability does not imply that spans are exported. Applications remain responsible for installing/configuring an OpenTelemetry SDK and exporter.