Skip to main content

otel

OpenTelemetry instrumentation for agent-runtimes.

This module provides automatic tracing and metrics for agent-runtimes operations, following the Logfire instrumentation pattern (external monkey-patching).

The instrumentation is non-intrusive – it patches classes from outside without modifying the core agent-runtimes code.

Simple usage with Logfire (recommended): from agent_runtimes.otel import setup_otel, instrument_agent_runtimes

# Setup OTEL and instrument in one call
provider, tracer = setup_otel(service_name="my-app")

# Or setup and instrument separately
provider, tracer = setup_otel(service_name="my-app", instrument=False)
instrument_agent_runtimes(tracer_provider=provider)

Environment variables for Logfire: DATALAYER_LOGFIRE_TOKEN - Logfire write token (required) DATALAYER_LOGFIRE_PROJECT - Project name (default: starter-project) DATALAYER_LOGFIRE_URL - Logfire URL (default: https://logfire-us.pydantic.dev)

Usage with plain OpenTelemetry: from opentelemetry import trace from agent_runtimes.otel import instrument_agent_runtimes

tracer_provider = trace.get_tracer_provider()
instrument_agent_runtimes(tracer_provider=tracer_provider)

Instrumented operations: - Agent run() calls (prompt, response, latency, session context) - Agent stream() calls (event count, total token steps) - Transport handle_request() calls (protocol, request/response size) - Adapter-level tool calls captured via run() wrapping

setup_otel​

def setup_otel(service_name: str = "agent-runtimes",
               service_version: str = "1.0.0",
               *,
               token: str | None = None,
               project: str | None = None,
               url: str | None = None,
               user_uid: str | None = None,
               instrument: bool = True,
               enable_metrics: bool = True,
               capture_prompts: bool = True,
               capture_responses: bool = True) -> tuple[Any, Any]

Setup OpenTelemetry tracing and metrics for agent-runtimes with Logfire.

This is the recommended way to enable observability. It configures the TracerProvider, MeterProvider, and OTLP exporters pointing at Logfire, then optionally instruments agent-runtimes classes.

Arguments:

  • service_name - Name of the service for tracing (default: "agent-runtimes")
  • service_version - Version of the service (default: "1.0.0")
  • token - Logfire write token. Reads DATALAYER_LOGFIRE_TOKEN env var if omitted.
  • project - Logfire project name. Reads DATALAYER_LOGFIRE_PROJECT if omitted.
  • url - Logfire base URL. Reads DATALAYER_LOGFIRE_URL if omitted.
  • instrument - Whether to instrument agent-runtimes classes (default: True)
  • enable_metrics - Whether to enable metrics collection (default: True)
  • capture_prompts - Whether to capture prompt text as span attributes.
  • capture_responses - Whether to capture response content as span attributes.

Returns:

Tuple of (TracerProvider, Tracer) for creating custom spans.

Raises:

  • ImportError - If OpenTelemetry packages are not installed.
  • service_version0 - If no token is provided and DATALAYER_LOGFIRE_TOKEN is not set.

Example:

from agent_runtimes.otel import setup_otel

provider, tracer = setup_otel(service_name="my-agent-app")

with tracer.start_as_current_span("my-operation") as span: span.set_attribute("key", "value")

provider.force_flush()

get_tracer​

def get_tracer(name: str = "agent-runtimes") -> Any | None

Get a tracer from the configured provider.

Returns:

Tracer instance, or None if OTEL is not configured.

get_meter​

def get_meter(name: str = "agent-runtimes") -> Any | None

Get a meter from the configured provider.

Returns:

Meter instance, or None if metrics are not configured.

AgentRuntimesMetrics Objects​

class AgentRuntimesMetrics()

Container for agent-runtimes metric instruments.

instrument_agent_runtimes​

def instrument_agent_runtimes(logfire_instance: Any = None,
                              *,
                              tracer_provider: Any | None = None,
                              meter_provider: Any | None = None,
                              capture_prompts: bool = True,
                              capture_responses: bool = True) -> None

Instrument agent-runtimes for OpenTelemetry tracing and metrics.

This follows the Logfire pattern of external monkey-patching – the core agent-runtimes code is not modified; instrumentation happens from outside.

Arguments:

  • logfire_instance - Optional Logfire instance. If provided, uses its tracer provider.

  • tracer_provider - Optional OpenTelemetry TracerProvider. Falls back to the global provider if not given.

  • meter_provider - Optional OpenTelemetry MeterProvider. Falls back to the global provider if not given.

  • capture_prompts - Whether to capture prompt text as span attributes.

  • capture_responses - Whether to capture response content as span attributes.

    Example with Logfire: import logfire from agent_runtimes.otel import instrument_agent_runtimes

    logfire.configure() instrument_agent_runtimes(logfire)

    Example with plain OpenTelemetry: from opentelemetry.sdk.trace import TracerProvider from agent_runtimes.otel import instrument_agent_runtimes

    provider = TracerProvider() instrument_agent_runtimes(tracer_provider=provider)

uninstrument_agent_runtimes​

def uninstrument_agent_runtimes() -> None

Remove agent-runtimes instrumentation and restore original methods.

create_otel_middleware​

def create_otel_middleware(tracer: Any = None,
                           service_name: str = "agent-runtimes") -> Any

Create a Starlette/FastAPI middleware that traces every HTTP request.

Usage::

from fastapi import FastAPI from agent_runtimes.otel import create_otel_middleware

app = FastAPI() app.add_middleware(create_otel_middleware())

Arguments:

  • tracer - Optional tracer. Defaults to the global provider's tracer.
  • service_name - Service name label for spans.

Returns:

A Starlette BaseHTTPMiddleware class.