Implement OpenAI Responses API instrumentation and examples

instrumentation-genai/opentelemetry-instrumentation-openai-v2/CHANGELOG.md

@@ -7,6 +7,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## Unreleased
 
+- Add support for OpenAI Responses API instrumentation
+  ([#4166](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/4166))
 - Fix `StreamWrapper` missing `.headers` and other attributes when using `with_raw_response` streaming
   ([#4113](https://github.com/open-telemetry/opentelemetry-python-contrib/issues/4113))
 - Add opt-in support for latest experimental semantic conventions (v1.37.0). Set

instrumentation-genai/opentelemetry-instrumentation-openai-v2/README.rst

@@ -82,6 +82,23 @@ Make sure to configure OpenTelemetry tracing, logging, and events to capture all
         input="Generate vector embeddings for this text"
     )
 
+    # Responses API example
+    response = client.responses.create(
+        model="gpt-4o-mini",
+        input="Write a short poem on OpenTelemetry.",
+    )
+
+    # Responses streaming example
+    with client.responses.stream(
+        model="gpt-4o-mini",
+        input="Write a short poem on OpenTelemetry.",
+        background=True,
+    ) as stream:
+        for event in stream:
+            if event.type == "response.completed":
+                response = event.response
+                break
+
 Enabling message content
 *************************
 
@@ -130,4 +147,3 @@ References
 * `OpenTelemetry OpenAI Instrumentation <https://opentelemetry-python-contrib.readthedocs.io/en/latest/instrumentation-genai/openai.html>`_
 * `OpenTelemetry Project <https://opentelemetry.io/>`_
 * `OpenTelemetry Python Examples <https://github.com/open-telemetry/opentelemetry-python/tree/main/docs/examples>`_
-

instrumentation-genai/opentelemetry-instrumentation-openai-v2/src/opentelemetry/instrumentation/openai_v2/__init__.py

@@ -52,6 +52,7 @@
 from opentelemetry.metrics import get_meter
 from opentelemetry.semconv.schemas import Schemas
 from opentelemetry.trace import get_tracer
+from opentelemetry.util.genai.handler import TelemetryHandler
 from opentelemetry.util.genai.handler import (
     TelemetryHandler,
 )
@@ -70,6 +71,7 @@
     chat_completions_create_v_old,
     embeddings_create,
 )
+from .patch_responses import responses_create
 
 
 class OpenAIInstrumentor(BaseInstrumentor):
@@ -106,6 +108,7 @@ def _instrument(self, **kwargs):
         )
 
         instruments = Instruments(self._meter)
+        capture_content = is_content_enabled()
 
         content_mode = (
             get_content_capturing_mode()
@@ -159,10 +162,41 @@ def _instrument(self, **kwargs):
             ),
         )
 
+        # Responses API is only available in openai>=1.66.0
+        # https://github.com/openai/openai-python/blob/main/CHANGELOG.md#1660-2025-03-11
+        try:
+            if TelemetryHandler is None:
+                raise ModuleNotFoundError(
+                    "opentelemetry.util.genai.handler is unavailable"
+                )
+
+            handler = TelemetryHandler(
+                tracer_provider=tracer_provider,
+                meter_provider=meter_provider,
+                logger_provider=logger_provider,
+            )
+
+            wrap_function_wrapper(
+                module="openai.resources.responses.responses",
+                name="Responses.create",
+                wrapper=responses_create(handler, capture_content),
+            )
+        except (AttributeError, ModuleNotFoundError):
+            # Responses API or TelemetryHandler not available
+            pass
+
     def _uninstrument(self, **kwargs):
         import openai  # pylint: disable=import-outside-toplevel  # noqa: PLC0415
 
         unwrap(openai.resources.chat.completions.Completions, "create")
         unwrap(openai.resources.chat.completions.AsyncCompletions, "create")
         unwrap(openai.resources.embeddings.Embeddings, "create")
         unwrap(openai.resources.embeddings.AsyncEmbeddings, "create")
+
+        # Responses API is only available in openai>=1.66.0
+        # https://github.com/openai/openai-python/blob/main/CHANGELOG.md#1660-2025-03-11
+        try:
+            unwrap(openai.resources.responses.responses.Responses, "create")
+        except (AttributeError, ModuleNotFoundError):
+            # Responses API not available in this version of openai
+            pass

instrumentation-genai/opentelemetry-instrumentation-openai-v2/src/opentelemetry/instrumentation/openai_v2/patch.py

@@ -12,6 +12,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+# pylint: disable=too-many-lines
 
 import json
 from timeit import default_timer
@@ -376,6 +377,9 @@ def _get_embeddings_span_name(span_attributes):
     return f"{span_attributes[GenAIAttributes.GEN_AI_OPERATION_NAME]} {span_attributes[GenAIAttributes.GEN_AI_REQUEST_MODEL]}"
 
 
+def _set_response_attributes(
+    span, result, logger: Logger, capture_content: bool
+):
 def _record_metrics(
     instruments: Instruments,
     duration: float,
@@ -476,7 +480,7 @@ def _set_response_attributes(span, result):
     if getattr(result, "service_tier", None):
         set_span_attribute(
             span,
-            GenAIAttributes.GEN_AI_OPENAI_RESPONSE_SERVICE_TIER,
+            OpenAIAttributes.OPENAI_RESPONSE_SERVICE_TIER,
             result.service_tier,
         )
 
@@ -628,7 +632,91 @@ def __init__(
         self._started = False
         self.capture_content = capture_content
         self._setup()
+        self.logger = logger
+        self.setup()
+
+    def setup(self):
+        if not self._span_started:
+            self._span_started = True
+
+    def cleanup(self):
+        if self._span_started:
+            if self.span.is_recording():
+                if self.response_model:
+                    set_span_attribute(
+                        self.span,
+                        GenAIAttributes.GEN_AI_RESPONSE_MODEL,
+                        self.response_model,
+                    )
+
+                if self.response_id:
+                    set_span_attribute(
+                        self.span,
+                        GenAIAttributes.GEN_AI_RESPONSE_ID,
+                        self.response_id,
+                    )
+
+                set_span_attribute(
+                    self.span,
+                    GenAIAttributes.GEN_AI_USAGE_INPUT_TOKENS,
+                    self.prompt_tokens,
+                )
+                set_span_attribute(
+                    self.span,
+                    GenAIAttributes.GEN_AI_USAGE_OUTPUT_TOKENS,
+                    self.completion_tokens,
+                )
 
+                set_span_attribute(
+                    self.span,
+                    OpenAIAttributes.OPENAI_RESPONSE_SERVICE_TIER,
+                    self.service_tier,
+                )
+
+                set_span_attribute(
+                    self.span,
+                    GenAIAttributes.GEN_AI_RESPONSE_FINISH_REASONS,
+                    self.finish_reasons,
+                )
+
+            for idx, choice in enumerate(self.choice_buffers):
+                message = {"role": "assistant"}
+                if self.capture_content and choice.text_content:
+                    message["content"] = "".join(choice.text_content)
+                if choice.tool_calls_buffers:
+                    tool_calls = []
+                    for tool_call in choice.tool_calls_buffers:
+                        function = {"name": tool_call.function_name}
+                        if self.capture_content:
+                            function["arguments"] = "".join(
+                                tool_call.arguments
+                            )
+                        tool_call_dict = {
+                            "id": tool_call.tool_call_id,
+                            "type": "function",
+                            "function": function,
+                        }
+                        tool_calls.append(tool_call_dict)
+                    message["tool_calls"] = tool_calls
+
+                body = {
+                    "index": idx,
+                    "finish_reason": choice.finish_reason or "error",
+                    "message": message,
+                }
+
+                event_attributes = {
+                    GenAIAttributes.GEN_AI_SYSTEM: GenAIAttributes.GenAiSystemValues.OPENAI.value
+                }
+                context = set_span_in_context(self.span, get_current())
+                self.logger.emit(
+                    LogRecord(
+                        event_name="gen_ai.choice",
+                        attributes=event_attributes,
+                        body=body,
+                        context=context,
+                    )
+                )
     def _setup(self):
         if not self._started:
             self._started = True

instrumentation-genai/opentelemetry-instrumentation-openai-v2/src/opentelemetry/instrumentation/openai_v2/patch_responses.py

@@ -0,0 +1,123 @@
+# Copyright The OpenTelemetry Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from typing import TYPE_CHECKING
+
+from opentelemetry.semconv._incubating.attributes import (
+    gen_ai_attributes as GenAIAttributes,
+)
+from opentelemetry.util.genai.types import Error, LLMInvocation
+
+from .response_extractors import (
+    GEN_AI_USAGE_CACHE_CREATION_INPUT_TOKENS,
+    GEN_AI_USAGE_CACHE_READ_INPUT_TOKENS,
+    OPENAI,
+    _extract_input_messages,
+    _extract_output_type,
+    _extract_system_instruction,
+    _set_invocation_response_attributes,
+)
+from .response_wrappers import ResponseStreamWrapper
+from .utils import get_llm_request_attributes, is_streaming
+
+if TYPE_CHECKING:
+    from opentelemetry.util.genai.handler import TelemetryHandler
+
+__all__ = [
+    "responses_create",
+    "_set_invocation_response_attributes",
+    "GEN_AI_USAGE_CACHE_READ_INPUT_TOKENS",
+    "GEN_AI_USAGE_CACHE_CREATION_INPUT_TOKENS",
+]
+
+# ---------------------------------------------------------------------------
+# Patch functions
+# ---------------------------------------------------------------------------
+
+
+def responses_create(
+    handler: "TelemetryHandler",
+    capture_content: bool,
+):
+    """Wrap the `create` method of the `Responses` class to trace it."""
+    # https://github.com/openai/openai-python/blob/dc68b90655912886bd7a6c7787f96005452ebfc9/src/openai/resources/responses/responses.py#L828
+
+    def traced_method(wrapped, instance, args, kwargs):
+        if Error is None or LLMInvocation is None:
+            raise ModuleNotFoundError(
+                "opentelemetry.util.genai.types is unavailable"
+            )
+
+        operation_name = GenAIAttributes.GenAiOperationNameValues.CHAT.value
+        span_attributes = get_llm_request_attributes(
+            kwargs,
+            instance,
+            operation_name,
+        )
+        output_type = _extract_output_type(kwargs)
+        if output_type:
+            span_attributes[GenAIAttributes.GEN_AI_OUTPUT_TYPE] = output_type
+        request_model_attribute = span_attributes.get(
+            GenAIAttributes.GEN_AI_REQUEST_MODEL
+        )
+        request_model = (
+            request_model_attribute
+            if isinstance(request_model_attribute, str)
+            else None
+        )
+        streaming = is_streaming(kwargs)
+
+        invocation = handler.start_llm(
+            LLMInvocation(
+                request_model=request_model,
+                operation_name=operation_name,
+                provider=OPENAI,
+                input_messages=_extract_input_messages(kwargs)
+                if capture_content
+                else [],
+                system_instruction=_extract_system_instruction(kwargs)
+                if capture_content
+                else [],
+                attributes=span_attributes.copy(),
+            )
+        )
+
+        try:
+            result = wrapped(*args, **kwargs)
+            if hasattr(result, "parse"):
+                parsed_result = result.parse()
+            else:
+                parsed_result = result
+
+            if streaming:
+                return ResponseStreamWrapper(
+                    parsed_result,
+                    handler,
+                    invocation,
+                    capture_content,
+                )
+
+            _set_invocation_response_attributes(
+                invocation, parsed_result, capture_content
+            )
+            handler.stop_llm(invocation)
+            return result
+
+        except Exception as error:
+            handler.fail_llm(
+                invocation, Error(message=str(error), type=type(error))
+            )
+            raise
+
+    return traced_method