{"slug": "openai-agents-sdk-observability-monitoring-with-opentelemetry", "title": "OpenAI Agents SDK Observability & Monitoring with OpenTelemetry", "summary": "SigNoz has released a guide for monitoring the OpenAI Agents SDK with OpenTelemetry, enabling developers to export agent traces to SigNoz Cloud as standard gen_ai.* telemetry. The instrumentation, available via the opentelemetry-instrumentation-openai-agents-v2 package, bridges the SDK's built-in tracing to OpenTelemetry, allowing end-to-end tracing of agent runs, token spend attribution, and correlation with other application components. The guide provides both no-code auto-instrumentation and a code-based approach for custom span routing.", "body_md": "The [OpenAI Agents SDK](https://github.com/openai/openai-agents-python) already traces itself. Every `Runner.run()`\n\nproduces a trace, and each agent invocation, model call, tool execution, handoff, and guardrail becomes a nested span. By default those spans go to OpenAI's own Traces dashboard.\n\nThis guide bridges that built-in tracing to OpenTelemetry so the same spans land in SigNoz as standard `gen_ai.*`\n\ntelemetry, sitting in the same trace as the web handler, database query, and downstream service around them.\n\n## What is OpenAI Agents SDK Observability?\n\nOpenAI Agents SDK observability is the practice of collecting traces from agent applications so you can see what each run did: which agents ran, which models they called, how many tokens they consumed, which tools they invoked, and where they failed.\n\nWith full OpenAI Agents SDK observability in SigNoz, you can trace a complete agent run end to end, attribute token spend to a model, watch tool call volume for loops that do not terminate, and correlate an agent failure with the rest of your application.\n\n## Prerequisites\n\n- A\n[SigNoz Cloud](https://signoz.io/teams/)account and an[ingestion key](https://signoz.io/docs/ingestion/signoz-cloud/keys/) - Python 3.9 or later\n- An OpenAI API key\n- An application built on the\n`openai-agents`\n\nSDK\n\n## Monitor OpenAI Agents SDK with OpenTelemetry\n\nThe instrumentation is a bridge rather than a monkey patch. It registers a `TracingProcessor`\n\non the Agents SDK's own trace provider and translates each SDK span into an OpenTelemetry span, which is then exported over OTLP.\n\nNo-code auto-instrumentation is recommended for quick setup with minimal code changes. It suits an existing agent application you would rather not modify.\n\n**Step 1:** Install the necessary packages in your Python environment.\n\n```\npip install \\\n  openai-agents \\\n  opentelemetry-distro \\\n  opentelemetry-exporter-otlp \\\n  opentelemetry-instrumentation-openai-agents-v2\n```\n\n`opentelemetry-distro`\n\nis what configures the tracer provider and exporter at startup. Without it `opentelemetry-instrument`\n\nloads the instrumentation but exports nothing.\n\n**Step 2:** Add automatic instrumentation.\n\n```\nopentelemetry-bootstrap --action=install\n```\n\n**Step 3:** Run an example. No OpenTelemetry code is required in your application.\n\n``` python\nimport asyncio\nfrom agents import Agent, Runner, function_tool\n \n \n@function_tool\ndef get_weather(city: str) -> str:\n    \"\"\"Return the current weather for a city.\"\"\"\n    return {\"tokyo\": \"18C, light rain\", \"paris\": \"24C, clear\"}.get(city.lower(), \"unknown\")\n \n \nagent = Agent(\n    name=\"weather-assistant\",\n    instructions=\"You are a concise weather assistant. Answer in one sentence.\",\n    model=\"gpt-4o-mini\",\n    tools=[get_weather],\n)\n \n \nasync def main():\n    result = await Runner.run(agent, \"What's the weather in Tokyo?\")\n    print(result.final_output)\n \n \nasyncio.run(main())\n```\n\n**Step 4:** Run your application with auto-instrumentation.\n\n```\nOTEL_RESOURCE_ATTRIBUTES=\"service.name=<service_name>\" \\\nOTEL_EXPORTER_OTLP_ENDPOINT=\"https://ingest.<region>.signoz.cloud:443\" \\\nOTEL_EXPORTER_OTLP_HEADERS=\"signoz-ingestion-key=<your-ingestion-key>\" \\\nOTEL_EXPORTER_OTLP_PROTOCOL=\"http/protobuf\" \\\nopentelemetry-instrument python main.py\n```\n\n**Verify these values:**\n\n`<service_name>`\n\n: The name your application appears under in SigNoz, for example`support-agents`\n\n.`<region>`\n\n: Your[SigNoz Cloud region](https://signoz.io/docs/ingestion/signoz-cloud/overview/#endpoint).`<your-ingestion-key>`\n\n: Your SigNoz[ingestion key](https://signoz.io/docs/ingestion/signoz-cloud/keys/).\n\nThe code path gives you control over both things the no-code path cannot set: where spans go, and whether the SDK's task and turn spans are emitted.\n\n**Step 1:** Install the necessary packages in your Python environment.\n\n```\npip install \\\n  openai-agents \\\n  opentelemetry-sdk \\\n  opentelemetry-exporter-otlp-proto-http \\\n  opentelemetry-instrumentation-openai-agents-v2\n```\n\n**Step 2:** Configure the exporter through environment variables.\n\n```\nexport OTEL_EXPORTER_OTLP_ENDPOINT=\"https://ingest.<region>.signoz.cloud:443\"\nexport OTEL_EXPORTER_OTLP_HEADERS=\"signoz-ingestion-key=<your-ingestion-key>\"\nexport OTEL_EXPORTER_OTLP_PROTOCOL=\"http/protobuf\"\nexport OPENAI_API_KEY=\"<your-openai-api-key>\"\n```\n\n**Verify these values:**\n\n`<region>`\n\n: Your[SigNoz Cloud region](https://signoz.io/docs/ingestion/signoz-cloud/overview/#endpoint).`<your-ingestion-key>`\n\n: Your SigNoz[ingestion key](https://signoz.io/docs/ingestion/signoz-cloud/keys/).`<your-openai-api-key>`\n\n: Your OpenAI API key from the[OpenAI dashboard](https://platform.openai.com/api-keys).\n\n**Step 3:** Wire up the instrumentation before your first agent run.\n\n``` python\nfrom opentelemetry import trace\nfrom opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter\nfrom opentelemetry.sdk.resources import Resource\nfrom opentelemetry.sdk.trace import TracerProvider\nfrom opentelemetry.sdk.trace.export import BatchSpanProcessor\nfrom opentelemetry.instrumentation.openai_agents import OpenAIAgentsInstrumentor\n \nfrom agents import set_trace_processors\n \nresource = Resource.create({\n    \"service.name\": \"<service_name>\",\n    \"deployment.environment\": \"production\",\n})\n \nprovider = TracerProvider(resource=resource)\nprovider.add_span_processor(BatchSpanProcessor(OTLPSpanExporter()))\ntrace.set_tracer_provider(provider)\n \n# Send traces to SigNoz only, not also to OpenAI's Traces dashboard.\nset_trace_processors([])\n \nOpenAIAgentsInstrumentor().instrument(tracer_provider=provider)\n```\n\n**Step 4:** Run your agent.\n\n``` python\nimport asyncio\nfrom agents import Agent, RunConfig, Runner, function_tool\n \n \n@function_tool\ndef get_weather(city: str) -> str:\n    \"\"\"Return the current weather for a city.\"\"\"\n    return {\"tokyo\": \"18C, light rain\", \"paris\": \"24C, clear\"}.get(city.lower(), \"unknown\")\n \n \nagent = Agent(\n    name=\"weather-assistant\",\n    instructions=\"You are a concise weather assistant. Answer in one sentence.\",\n    model=\"gpt-4o-mini\",\n    tools=[get_weather],\n)\n \nrun_config = RunConfig(tracing={\"include_task_and_turn_spans\": False})\n \n \nasync def main():\n    result = await Runner.run(agent, \"What's the weather in Tokyo?\", run_config=run_config)\n    print(result.final_output)\n \n    provider.force_flush()\n    provider.shutdown()\n \n \nasyncio.run(main())\n```\n\nEach run emits spans carrying `gen_ai.operation.name`\n\n, `gen_ai.request.model`\n\n, `gen_ai.usage.input_tokens`\n\n, and `gen_ai.usage.output_tokens`\n\n. Allow a few seconds for them to appear in SigNoz.\n\n## View OpenAI Agents SDK Traces in SigNoz\n\nOpen the [Traces explorer](https://signoz.io/docs/userguide/traces/) and filter on your `service.name`\n\n. Agent runs appear as `Agent workflow`\n\nroot spans, with `invoke_agent`\n\n, `chat`\n\n, and `execute_tool`\n\nspans nested beneath them.\n\nClick a root span to open the full run. The waterfall shows the agent turn, the model calls inside it, and each tool execution, with the `gen_ai.*`\n\nattributes on the right.\n\nThe span tree an agent run produces looks like this:\n\n```\nAgent workflow                 (Server, root)   one per Runner.run()\n└─ invoke_agent <agent>        (Client)         carries the real agent name\n   ├─ chat <model>             (Client)         carries the token counts\n   ├─ execute_tool <tool>      (Internal)\n   ├─ agent_handoff            (Internal)\n   └─ guardrail_check          (Internal)\n```\n\nTwo placement details are worth knowing before you write your own queries. Token counts appear only on `chat`\n\nspans. The real agent name appears only on `invoke_agent`\n\nspans, because `gen_ai.agent.name`\n\nis the literal default string `OpenAI Agent`\n\non chat, tool, handoff, and guardrail spans.\n\n## OpenAI Agents SDK Observability Dashboard\n\nSigNoz ships a prebuilt dashboard for the OpenAI Agents SDK covering agent runs, token usage by model, latency percentiles, tool activity, handoffs, guardrails, and errors. See the [OpenAI Agents SDK dashboard](https://signoz.io/docs/dashboards/dashboard-templates/openai-agents-sdk-dashboard/) for the panel reference and the import link.\n\n## Capturing prompts and completions\n\nPrompt and completion content is not recorded by default. To opt in:\n\n```\nexport OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=\"true\"\n```\n\nContent then lands on `gen_ai.input.messages`\n\n, `gen_ai.output.messages`\n\n, and `gen_ai.system_instructions`\n\n. Prompts frequently contain user data, so enable this deliberately and check what your retention policy implies first.\n\n## Troubleshooting OpenAI Agents SDK Observability\n\n### No spans reach SigNoz\n\nConfirm `provider.force_flush()`\n\nruns before the process exits. Check that `set_trace_processors([])`\n\nand `.instrument()`\n\nboth run before the first `Runner.run()`\n\n. Confirm `OTEL_EXPORTER_OTLP_PROTOCOL`\n\nis `http/protobuf`\n\n, which matches the HTTP exporter installed in Step 1.\n\n### Running with opentelemetry-instrument produces nothing\n\nAlmost always a missing `opentelemetry-distro`\n\n. Without it, `opentelemetry-instrument`\n\nstill loads the instrumentation and the bridge appears on the SDK's processor list, but no tracer provider or exporter is ever configured, so nothing leaves the process. Confirm the package is installed as shown in Step 1 of the No Code tab.\n\nTo check quickly, print `type(opentelemetry.trace.get_tracer_provider())`\n\nat the top of your application. A `ProxyTracerProvider`\n\nmeans nothing was configured, while a `TracerProvider`\n\nmeans the distro is doing its job.\n\n### Spans named unknown appear throughout the trace\n\nThe SDK's task and turn span types are not yet mapped by the instrumentation and fall through to the literal name `unknown`\n\n. Suppress them with `include_task_and_turn_spans: False`\n\non your `RunConfig`\n\n, as shown in the Code tab. They cannot be suppressed on the no-code path, because that setting has to be passed in code.\n\n### Traces still appear in OpenAI's dashboard\n\nThe `set_trace_processors([])`\n\ncall is missing, or it runs after `.instrument()`\n\nrather than before it.\n\n### No metrics appear\n\nThis instrumentation emits traces only and declares no metric support, so there is no `gen_ai.client.token.usage`\n\nhistogram. Aggregate the span attributes instead, which is what the dashboard template does.\n\n### Overriding of current TracerProvider is not allowed\n\nA global tracer provider was already set, usually by a second module running the same setup. Configure the provider exactly once at startup.\n\n## Setup OpenTelemetry Collector (Optional)\n\nThe [OpenTelemetry Collector](https://opentelemetry.io/docs/collector/) is a vendor-neutral proxy that receives, processes, and exports telemetry. Sending through a Collector lets you batch and retry centrally, strip or enrich attributes before they leave your network, and fan out to more than one backend without changing application code.\n\nTo use one, point `OTEL_EXPORTER_OTLP_ENDPOINT`\n\nat your Collector instead of at SigNoz, and configure the Collector's OTLP exporter to forward to SigNoz. See [Install OpenTelemetry Collector](https://signoz.io/docs/opentelemetry-collection-agents/get-started/) for setup.\n\n## Related integrations\n\nInstrument the other agent frameworks your team builds on, using the same OpenTelemetry pipeline:\n\n[Claude Agent SDK monitoring with OpenTelemetry](https://signoz.io/docs/claude-agent-monitoring/)- Anthropic's agent framework, tracing agent workflows, latency, and errors[LangChain observability with OpenTelemetry](https://signoz.io/docs/langchain-observability/)- trace chains, agent steps, and retrieval alongside model calls[CrewAI observability with OpenTelemetry](https://signoz.io/docs/crewai-observability/)- multi-agent crews, task delegation, and tool activity[AutoGen observability with OpenTelemetry](https://signoz.io/docs/autogen-observability/)- conversational multi-agent runs and per-agent token usage[Google ADK observability with OpenTelemetry](https://signoz.io/docs/google-adk-observability/)- another SDK that emits`gen_ai.*`\n\nspans natively[Pydantic AI observability with OpenTelemetry](https://signoz.io/docs/pydantic-ai-observability/)- typed agents with built-in OpenTelemetry support\n\nCalling the OpenAI API directly rather than building agents on the SDK? See [OpenAI monitoring](https://signoz.io/docs/openai-monitoring/).\n\nBrowse [all LLM observability integrations](https://signoz.io/docs/llm-observability/) to instrument the rest of your stack.", "url": "https://wpnews.pro/news/openai-agents-sdk-observability-monitoring-with-opentelemetry", "canonical_source": "https://signoz.io/docs/openai-agents-sdk-observability", "published_at": "2026-08-25 00:00:00+00:00", "updated_at": "2026-08-26 08:13:03.200950+00:00", "lang": "en", "topics": ["ai-tools", "developer-tools", "mlops"], "entities": ["OpenAI Agents SDK", "SigNoz", "OpenTelemetry", "SigNoz Cloud", "opentelemetry-instrumentation-openai-agents-v2"], "alternates": {"html": "https://wpnews.pro/news/openai-agents-sdk-observability-monitoring-with-opentelemetry", "markdown": "https://wpnews.pro/news/openai-agents-sdk-observability-monitoring-with-opentelemetry.md", "text": "https://wpnews.pro/news/openai-agents-sdk-observability-monitoring-with-opentelemetry.txt", "jsonld": "https://wpnews.pro/news/openai-agents-sdk-observability-monitoring-with-opentelemetry.jsonld"}}