OpenTelemetry OpenAI Agents Instrumentation

0.58.0 · active · verified Sat Apr 11

This library provides official OpenTelemetry instrumentation for the `openai-agents` SDK, converting the rich trace data emitted by the Agents runtime into the GenAI semantic conventions, enriching spans with request/response payload metadata, and recording duration/token usage metrics. It is currently at version `0.58.0` and maintains an active development pace with frequent updates, often related to compliance with evolving OpenTelemetry Generative AI semantic conventions.

Warnings

breaking The OpenTelemetry Generative AI semantic conventions are under active development and may change. Frequent updates in minor versions (e.g., 0.53.x to 0.58.x) often include migrations and adjustments to these conventions, which can alter span attributes or names.
Fix: Monitor release notes for changes related to GenAI semantic conventions. Consider setting `OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental` environment variable to opt into the latest experimental conventions, or ensure your telemetry backend is flexible with attribute names.
gotcha By default, this instrumentation captures message content (prompts, completions, tool arguments) within span attributes, which can include sensitive user data. This behavior might conflict with privacy requirements or increase trace size significantly.
Fix: To disable content capture, set the environment variable `TRACELOOP_TRACE_CONTENT=false` or `OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=no_content` (or equivalent `OTEL_INSTRUMENTATION_OPENAI_AGENTS_CAPTURE_CONTENT` with `ContentCaptureMode.NO_CONTENT`). Other modes like `span_only`, `event_only`, `span_and_event` are available for granular control.
gotcha This package (`opentelemetry-instrumentation-openai-agents`) specifically instruments the `openai-agents` SDK. There are other separate instrumentations for the general `openai` client (e.g., `opentelemetry-instrumentation-openai` or `opentelemetry-instrumentation-openai-v2`). Using the wrong instrumentation for your OpenAI integration will result in no telemetry.
Fix: Ensure you are using the correct instrumentation package for the specific OpenAI library or SDK you are interacting with. For `openai-agents` workflows, use this package. For direct `openai` client calls, use `opentelemetry-instrumentation-openai-v2` (the official OpenTelemetry project package) or `opentelemetry-instrumentation-openai` (Traceloop/OpenLLMetry community package) as appropriate.

Install

pip install opentelemetry-instrumentation-openai-agents openai-agents opentelemetry-sdk Install library and core dependencies

Imports

OpenAIAgentsInstrumentor
```
from opentelemetry.instrumentation.openai_agents import OpenAIAgentsInstrumentor
```
This is the main class to initialize the OpenAI Agents instrumentation.

Quickstart

This quickstart demonstrates how to set up the OpenTelemetry Python SDK with an OTLP exporter and then enable instrumentation for OpenAI Agents. After running this code, traces generated by the agent's operations will be sent to the configured OpenTelemetry collector. Make sure an OpenTelemetry collector is running and accessible.

import os
from agents import Agent, Runner, function_tool
from opentelemetry import trace
from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import OTLPSpanExporter
from opentelemetry.instrumentation.openai_agents import OpenAIAgentsInstrumentor
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor

def configure_otel() -> None:
    # Configure an OpenTelemetry TracerProvider
    provider = TracerProvider()
    processor = BatchSpanProcessor(OTLPSpanExporter())
    provider.add_span_processor(processor)
    trace.set_tracer_provider(provider)

    # Instrument OpenAI Agents
    OpenAIAgentsInstrumentor().instrument(tracer_provider=provider)

@function_tool
def get_weather(city: str) -> str:
    """Provides the weather for a given city."""
    return f"The forecast for {city} is sunny with pleasant temperatures."

if __name__ == "__main__":
    # Ensure OTLP collector is running, e.g., with Docker:
    # docker run -d -p 4317:4317 -p 4318:4318 otel/opentelemetry-collector-contrib

    # Configure OpenTelemetry
    configure_otel()

    # Example OpenAI Agent usage
    assistant = Agent(
        name="Travel Concierge",
        instructions="You are a concise travel concierge.",
        tools=[get_weather],
    )

    print("Running agent...")
    # Provide dummy API key if required by 'openai-agents', though it might be configured via env vars.
    # For real use, ensure OpenAI API key is set via environment variable, e.g., OPENAI_API_KEY
    os.environ['OPENAI_API_KEY'] = os.environ.get('OPENAI_API_KEY', 'sk-dummy-key-for-example')

    result = Runner.run_sync(assistant, "I'm visiting Barcelona this weekend. How should I pack?")
    print(f"Agent final output: {result.final_output}")
    print("Traces should now be visible in your configured OpenTelemetry backend.")

view raw JSON →