Align OpenAI agents samples with OTLP exporter

nagkumar91 · nagkumar91 · commit 2c283a6438f5 · 2025-10-13T14:09:11.000-07:00
diff --git a/instrumentation-genai/opentelemetry-instrumentation-openai-agents-v2/examples/content-capture/.env.example b/instrumentation-genai/opentelemetry-instrumentation-openai-agents-v2/examples/content-capture/.env.example
@@ -0,0 +1,8 @@
+# Copy to .env and add values before running the sample.
+# Required for OpenAI client (only used if you swap in a real OpenAI call)
+OPENAI_API_KEY=
+
+# Optional overrides for span attributes / exporters
+OTEL_SERVICE_NAME=openai-agents-content-capture-demo
+OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
+OTEL_EXPORTER_OTLP_PROTOCOL=grpc
diff --git a/instrumentation-genai/opentelemetry-instrumentation-openai-agents-v2/examples/content-capture/README.md b/instrumentation-genai/opentelemetry-instrumentation-openai-agents-v2/examples/content-capture/README.md
@@ -12,10 +12,12 @@ recorded on spans and span events.
 1. Activate the repository virtual environment:
 
    ```bash
-   source ../../../../.venv/bin/activate
+   source ../../.venv/bin/activate
    ```
 
-2. Ensure `openai-agents` is installed in the environment (it is included in
+2. Copy `.env.example` to `.env` and provide any overrides you need (for example,
+   setting `OTEL_EXPORTER_OTLP_ENDPOINT`).
+3. Ensure `openai-agents` is installed in the environment (it is included in
    the shared development venv for this repository).
 
 ## Run the demo
@@ -26,7 +28,7 @@ python main.py
 
 The script will:
 
-- Configure the OpenTelemetry SDK with a console span exporter.
+- Configure the OpenTelemetry SDK with an OTLP exporter so spans reach your collector.
 - Instrument the OpenAI Agents tracing hooks with content capture enabled.
 - Simulate an agent invocation that performs a generation and a tool call.
 - Print the resulting spans, attributes, and events (including JSON-encoded
@@ -35,7 +37,6 @@ The script will:
 ## Customisation tips
 
 - Set `OTEL_SERVICE_NAME` before running to override the default service name.
-- Swap the `ConsoleSpanExporter` in `demo.py` for an OTLP exporter if you want
-  to ship spans to a collector.
+- Adjust the OTLP exporter configuration (endpoint, protocol) through `.env`.
 - Modify the prompts, tool payloads, or add additional spans in `run_workflow`
   to explore different content capture scenarios.
diff --git a/instrumentation-genai/opentelemetry-instrumentation-openai-agents-v2/examples/content-capture/main.py b/instrumentation-genai/opentelemetry-instrumentation-openai-agents-v2/examples/content-capture/main.py
@@ -15,20 +15,23 @@
 from typing import Any
 
 from agents.tracing import agent_span, function_span, generation_span, trace
+from dotenv import load_dotenv
 
+from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import (
+    OTLPSpanExporter,
+)
 from opentelemetry.instrumentation.openai_agents import (
     OpenAIAgentsInstrumentor,
 )
 from opentelemetry.sdk.resources import Resource
 from opentelemetry.sdk.trace import TracerProvider
-from opentelemetry.sdk.trace.export import (
-    ConsoleSpanExporter,
-    SimpleSpanProcessor,
-)
+from opentelemetry.sdk.trace.export import BatchSpanProcessor
+
+load_dotenv()  # take environment variables from .env.
 
 
 def configure_tracing() -> None:
-    """Configure a tracer provider that writes spans to stdout."""
+    """Configure a tracer provider that exports spans via OTLP."""
     resource = Resource.create(
         {
             "service.name": os.environ.get(
@@ -37,7 +40,7 @@ def configure_tracing() -> None:
         }
     )
     provider = TracerProvider(resource=resource)
-    provider.add_span_processor(SimpleSpanProcessor(ConsoleSpanExporter()))
+    provider.add_span_processor(BatchSpanProcessor(OTLPSpanExporter()))
 
     # Instrument with explicit content capture mode to ensure prompts/responses are recorded.
     OpenAIAgentsInstrumentor().instrument(
@@ -72,7 +75,7 @@ def run_workflow() -> None:
     }
 
     with trace("travel-booking-workflow"):
-        with agent_span(operation="invoke", name="travel_planner") as agent:
+        with agent_span(name="travel_planner") as agent:
             dump(
                 "Agent span started",
                 {"span_id": agent.span_id, "trace_id": agent.trace_id},
@@ -105,7 +108,9 @@ def run_workflow() -> None:
             ):
                 pass
 
-    print("\nWorkflow complete – spans exported to console above.")
+    print(
+        "\nWorkflow complete – spans exported to the configured OTLP endpoint."
+    )
 
 
 def main() -> None:
diff --git a/instrumentation-genai/opentelemetry-instrumentation-openai-agents-v2/examples/manual/.env.example b/instrumentation-genai/opentelemetry-instrumentation-openai-agents-v2/examples/manual/.env.example
@@ -1,11 +1,5 @@
-# Update this with your real OpenAI API key
-OPENAI_API_KEY=sk-YOUR_API_KEY
-
-# Uncomment and adjust if you use a non-default OTLP collector endpoint
-# OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
-# OTEL_EXPORTER_OTLP_PROTOCOL=grpc
-
-OTEL_SERVICE_NAME=opentelemetry-python-openai-agents-manual
-
-# Optionally override the agent name reported on spans
-# OTEL_GENAI_AGENT_NAME=Travel Concierge
+# Copy to .env and add real values before running main.py
+OPENAI_API_KEY=
+OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
+OTEL_EXPORTER_OTLP_PROTOCOL=grpc
+OTEL_SERVICE_NAME=openai-agents-manual-demo
diff --git a/instrumentation-genai/opentelemetry-instrumentation-openai-agents-v2/examples/manual/README.rst b/instrumentation-genai/opentelemetry-instrumentation-openai-agents-v2/examples/manual/README.rst
@@ -22,7 +22,7 @@ Setup
        python3 -m venv .venv
        source .venv/bin/activate
        pip install "python-dotenv[cli]"
-       pip install -r requirements.txt
+       uv pip install -r requirements.txt --prerelease=allow
 
 Run
 ---
@@ -34,6 +34,8 @@ are applied:
 
     dotenv run -- python main.py
 
+Ensure ``OPENAI_API_KEY`` is present in your environment (or ``.env`` file); the OpenAI client raises ``OpenAIError`` if the key is missing.
+
 The script automatically loads environment variables from ``.env`` so running
 ``python main.py`` directly also works if the shell already has the required
 values exported.
diff --git a/instrumentation-genai/opentelemetry-instrumentation-openai-agents-v2/examples/manual/requirements.txt b/instrumentation-genai/opentelemetry-instrumentation-openai-agents-v2/examples/manual/requirements.txt
@@ -1,6 +1,7 @@
 openai-agents~=0.3.3
 python-dotenv~=1.0
 
-opentelemetry-sdk~=1.36.0
-opentelemetry-exporter-otlp-proto-grpc~=1.36.0
-opentelemetry-instrumentation-openai-agents-v2~=0.1.0.dev
+opentelemetry-sdk @ git+https://github.com/open-telemetry/opentelemetry-python@main#subdirectory=opentelemetry-sdk
+opentelemetry-semantic-conventions @ git+https://github.com/open-telemetry/opentelemetry-python@main#subdirectory=opentelemetry-semantic-conventions
+opentelemetry-exporter-otlp-proto-grpc @ git+https://github.com/open-telemetry/opentelemetry-python@main#subdirectory=exporter/opentelemetry-exporter-otlp-proto-grpc
+-e ../..
diff --git a/instrumentation-genai/opentelemetry-instrumentation-openai-agents-v2/examples/zero-code/.env.example b/instrumentation-genai/opentelemetry-instrumentation-openai-agents-v2/examples/zero-code/.env.example
@@ -1,14 +1,7 @@
-# Update this with your real OpenAI API key
-OPENAI_API_KEY=sk-YOUR_API_KEY
-
-# Uncomment and adjust if you use a non-default OTLP collector endpoint
-# OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
-# OTEL_EXPORTER_OTLP_PROTOCOL=grpc
-
+# Copy to .env and add real values before running main.py
+OPENAI_API_KEY=
+OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
+OTEL_EXPORTER_OTLP_PROTOCOL=grpc
 OTEL_SERVICE_NAME=opentelemetry-python-openai-agents-zero-code
-
-# Enable auto-instrumentation for logs if desired
 OTEL_PYTHON_LOGGING_AUTO_INSTRUMENTATION_ENABLED=true
-
-# Optionally override the agent name reported on spans
 # OTEL_GENAI_AGENT_NAME=Travel Concierge
diff --git a/instrumentation-genai/opentelemetry-instrumentation-openai-agents-v2/examples/zero-code/README.rst b/instrumentation-genai/opentelemetry-instrumentation-openai-agents-v2/examples/zero-code/README.rst
@@ -22,7 +22,7 @@ Setup
        python3 -m venv .venv
        source .venv/bin/activate
        pip install "python-dotenv[cli]"
-       pip install -r requirements.txt
+       uv pip install -r requirements.txt --prerelease=allow
 
 Run
 ---
@@ -34,6 +34,8 @@ instrumentation is activated automatically:
 
     dotenv run -- opentelemetry-instrument python main.py
 
+Ensure ``OPENAI_API_KEY`` is set in your shell or `.env`; the OpenAI client raises ``OpenAIError`` if the key is missing.
+
 Because ``main.py`` invokes ``load_dotenv``, running ``python main.py`` directly
 also works when the required environment variables are already exported.
 
diff --git a/instrumentation-genai/opentelemetry-instrumentation-openai-agents-v2/examples/zero-code/requirements.txt b/instrumentation-genai/opentelemetry-instrumentation-openai-agents-v2/examples/zero-code/requirements.txt
@@ -1,7 +1,7 @@
 openai-agents~=0.3.3
 python-dotenv~=1.0
 
-opentelemetry-sdk~=1.36.0
-opentelemetry-exporter-otlp-proto-grpc~=1.36.0
-opentelemetry-distro~=0.57b0
-opentelemetry-instrumentation-openai-agents-v2~=0.1.0.dev
+opentelemetry-sdk @ git+https://github.com/open-telemetry/opentelemetry-python@main#subdirectory=opentelemetry-sdk
+opentelemetry-semantic-conventions @ git+https://github.com/open-telemetry/opentelemetry-python@main#subdirectory=opentelemetry-semantic-conventions
+opentelemetry-exporter-otlp-proto-grpc @ git+https://github.com/open-telemetry/opentelemetry-python@main#subdirectory=exporter/opentelemetry-exporter-otlp-proto-grpc
+-e ../..
diff --git a/instrumentation-genai/opentelemetry-instrumentation-openai-agents-v2/src/opentelemetry/instrumentation/openai_agents/constants.py b/instrumentation-genai/opentelemetry-instrumentation-openai-agents-v2/src/opentelemetry/instrumentation/openai_agents/constants.py
@@ -110,7 +110,6 @@ class GenAIEvaluationAttributes:
 GEN_AI_RESPONSE_FINISH_REASONS = "gen_ai.response.finish_reasons"
 GEN_AI_USAGE_INPUT_TOKENS = "gen_ai.usage.input_tokens"
 GEN_AI_USAGE_OUTPUT_TOKENS = "gen_ai.usage.output_tokens"
-GEN_AI_USAGE_TOTAL_TOKENS = "gen_ai.usage.total_tokens"
 GEN_AI_CONVERSATION_ID = "gen_ai.conversation.id"
 GEN_AI_AGENT_ID = "gen_ai.agent.id"
 GEN_AI_AGENT_NAME = "gen_ai.agent.name"
diff --git a/instrumentation-genai/opentelemetry-instrumentation-openai-agents-v2/src/opentelemetry/instrumentation/openai_agents/events.py b/instrumentation-genai/opentelemetry-instrumentation-openai-agents-v2/src/opentelemetry/instrumentation/openai_agents/events.py
@@ -29,7 +29,6 @@
     "gen_ai.response.model",
     "gen_ai.usage.input_tokens",
     "gen_ai.usage.output_tokens",
-    "gen_ai.usage.total_tokens",
     "gen_ai.output.type",
     "gen_ai.system_instructions",
     "gen_ai.input.messages",
diff --git a/instrumentation-genai/opentelemetry-instrumentation-openai-agents-v2/src/opentelemetry/instrumentation/openai_agents/genai_semantic_processor.py b/instrumentation-genai/opentelemetry-instrumentation-openai-agents-v2/src/opentelemetry/instrumentation/openai_agents/genai_semantic_processor.py
@@ -116,7 +116,6 @@ def gen_ai_json_dumps(value: Any) -> str:
     GEN_AI_TOOL_TYPE,
     GEN_AI_USAGE_INPUT_TOKENS,
     GEN_AI_USAGE_OUTPUT_TOKENS,
-    GEN_AI_USAGE_TOTAL_TOKENS,
     GenAIOperationName,
     GenAIOutputType,
 )
@@ -1053,17 +1052,93 @@ def _infer_output_type(self, span_data: Any) -> str:
         if isinstance(output, Sequence) and output:
             first = output[0]
             if isinstance(first, dict):
-                # Check for image/speech indicators
-                if first.get("type") == "image":
-                    return GenAIOutputType.IMAGE
-                if first.get("type") == "audio":
-                    return GenAIOutputType.SPEECH
-                # Check if it's structured JSON
-                if "type" in first or len(first) > 1:
+                item_type = first.get("type")
+                if isinstance(item_type, str):
+                    normalized = item_type.strip().lower()
+                    if normalized in {"image", "image_url"}:
+                        return GenAIOutputType.IMAGE
+                    if normalized in {"audio", "speech", "audio_url"}:
+                        return GenAIOutputType.SPEECH
+                    if normalized in {
+                        "json",
+                        "json_object",
+                        "jsonschema",
+                        "function_call",
+                        "tool_call",
+                        "tool_result",
+                    }:
+                        return GenAIOutputType.JSON
+                    if normalized in {
+                        "text",
+                        "output_text",
+                        "message",
+                        "assistant",
+                    }:
+                        return GenAIOutputType.TEXT
+
+                # Conversation style payloads
+                if "role" in first:
+                    parts = first.get("parts")
+                    if isinstance(parts, Sequence) and parts:
+                        # If all parts are textual (or missing explicit type), treat as text
+                        textual = True
+                        for part in parts:
+                            if isinstance(part, dict):
+                                part_type = str(part.get("type", "")).lower()
+                                if part_type in {"image", "image_url"}:
+                                    return GenAIOutputType.IMAGE
+                                if part_type in {
+                                    "audio",
+                                    "speech",
+                                    "audio_url",
+                                }:
+                                    return GenAIOutputType.SPEECH
+                                if part_type and part_type not in {
+                                    "text",
+                                    "output_text",
+                                    "assistant",
+                                }:
+                                    textual = False
+                            elif not isinstance(part, str):
+                                textual = False
+                        if textual:
+                            return GenAIOutputType.TEXT
+                    content_value = first.get("content")
+                    if isinstance(content_value, str):
+                        return GenAIOutputType.TEXT
+
+                # Detect structured data without explicit type
+                json_like_keys = {
+                    "schema",
+                    "properties",
+                    "arguments",
+                    "result",
+                    "data",
+                    "json",
+                    "output_json",
+                }
+                if json_like_keys.intersection(first.keys()):
                     return GenAIOutputType.JSON
 
         return GenAIOutputType.TEXT
 
+    @staticmethod
+    def _sanitize_usage_payload(usage: Any) -> None:
+        """Remove non-spec usage fields (e.g., total tokens) in-place."""
+        if not usage:
+            return
+        if isinstance(usage, dict):
+            usage.pop("total_tokens", None)
+            return
+        if hasattr(usage, "total_tokens"):
+            try:
+                setattr(usage, "total_tokens", None)
+            except Exception:  # pragma: no cover - defensive
+                try:
+                    delattr(usage, "total_tokens")
+                except Exception:  # pragma: no cover - defensive
+                    pass
+
     def _get_span_kind(self, span_data: Any) -> SpanKind:
         """Determine appropriate span kind based on span data type."""
         if _is_instance_of(span_data, FunctionSpanData):
@@ -1410,6 +1485,7 @@ def _get_attributes_from_generation_span_data(
         # Usage information
         if span_data.usage:
             usage = span_data.usage
+            self._sanitize_usage_payload(usage)
             if "prompt_tokens" in usage or "input_tokens" in usage:
                 tokens = usage.get("prompt_tokens") or usage.get(
                     "input_tokens"
@@ -1422,8 +1498,6 @@ def _get_attributes_from_generation_span_data(
                 )
                 if tokens is not None:
                     yield GEN_AI_USAGE_OUTPUT_TOKENS, tokens
-            if "total_tokens" in usage:
-                yield GEN_AI_USAGE_TOTAL_TOKENS, usage["total_tokens"]
 
         # Model configuration
         if span_data.model_config:
@@ -1692,6 +1766,7 @@ def _get_attributes_from_response_span_data(
                 and span_data.response.usage
             ):
                 usage = span_data.response.usage
+                self._sanitize_usage_payload(usage)
                 input_tokens = getattr(usage, "input_tokens", None)
                 if input_tokens is None:
                     input_tokens = getattr(usage, "prompt_tokens", None)
@@ -1703,11 +1778,6 @@ def _get_attributes_from_response_span_data(
                     output_tokens = getattr(usage, "completion_tokens", None)
                 if output_tokens is not None:
                     yield GEN_AI_USAGE_OUTPUT_TOKENS, output_tokens
-                if (
-                    hasattr(usage, "total_tokens")
-                    and usage.total_tokens is not None
-                ):
-                    yield GEN_AI_USAGE_TOTAL_TOKENS, usage.total_tokens
 
         # Input/output messages
         if (
