Skip to main content

OpenTelemetry Tracing (agentvisor.tracing)

API reference for the module backing Agent Tracing — read that guide first for the concepts (span forwarding, sampling, backend configuration). This page covers the module's public functions directly. Not to be confused with Runtime Tracing, gVisor's unrelated syscall-level tracing mechanism.

This module is optional: if opentelemetry-sdk isn't installed (pip install agentvisor[tracing]), every function below silently does nothing.

Usage​

Auto-instrumentation (including OpenLLMetry) works transparently once installed — no code changes needed. For manual spans:

import agentvisor

with agentvisor.trace("retrieve_documents", attributes={"query": q}) as span:
    docs = retriever.invoke(q)

API Reference​

Functions​

trace()​

@contextlib.contextmanager
def trace(
    name: str,
    attributes: dict[str, Any] | None = None,
) -> Generator[Any, None, None]

Context manager wrapping the standard OTEL tracer. Works whether or not tracing is active — when inactive (no opentelemetry-sdk, or setup_tracing() never armed because TRACEPARENT was absent), yields None and is a no-op rather than raising.

setup_tracing()​

def setup_tracing() -> None

Configures OTEL to forward spans through AgentVisor. Called automatically during SDK initialization — most agents never call this directly. No-ops unless the TRACEPARENT environment variable is present (set by the host when tracing is actually enabled) and opentelemetry-sdk is installed. Configures a ParentBased(ALWAYS_OFF) sampler, so only spans that are children of an already-sampled parent are recorded — the host controls the sampling decision, not the agent.

reset_tracing()​

def reset_tracing() -> None

Resets internal setup state. Testing only.

Classes​

AgentVisorSpanExporter​

class AgentVisorSpanExporter(SpanExporter):
    def export(self, spans: Sequence[ReadableSpan]) -> SpanExportResult: ...

The SpanExporter setup_tracing() wires into a BatchSpanProcessor. Serializes spans as OTLP protobuf and forwards them to the host via the AgentService gRPC channel, where they're re-exported to the host's own configured OTEL backend (Jaeger, an OTLP collector, etc.) alongside the host's own spans. Most agents never construct this directly — setup_tracing() does it automatically.

See Also​