fix(openai): instrument responses.parse() for structured-output tracing (#4198)

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: galzilber

packages/opentelemetry-instrumentation-openai/opentelemetry/instrumentation/openai/v1/__init__.py

@@ -312,6 +312,11 @@ def _instrument(self, **kwargs):
             "Responses.retrieve",
             responses_get_or_create_wrapper(tracer),
         )
+        self._try_wrap(
+            "openai.resources.responses",
+            "Responses.parse",
+            responses_get_or_create_wrapper(tracer),
+        )
         self._try_wrap(
             "openai.resources.responses",
             "Responses.cancel",
@@ -327,6 +332,11 @@ def _instrument(self, **kwargs):
             "AsyncResponses.retrieve",
             async_responses_get_or_create_wrapper(tracer),
         )
+        self._try_wrap(
+            "openai.resources.responses",
+            "AsyncResponses.parse",
+            async_responses_get_or_create_wrapper(tracer),
+        )
         self._try_wrap(
             "openai.resources.responses",
             "AsyncResponses.cancel",
@@ -364,9 +374,11 @@ def _uninstrument(self, **kwargs):
             unwrap("openai.resources.beta.threads.messages", "Messages.list")
             unwrap("openai.resources.responses", "Responses.create")
             unwrap("openai.resources.responses", "Responses.retrieve")
+            unwrap("openai.resources.responses", "Responses.parse")
             unwrap("openai.resources.responses", "Responses.cancel")
             unwrap("openai.resources.responses", "AsyncResponses.create")
             unwrap("openai.resources.responses", "AsyncResponses.retrieve")
+            unwrap("openai.resources.responses", "AsyncResponses.parse")
             unwrap("openai.resources.responses", "AsyncResponses.cancel")
             unwrap("openai.resources.beta.realtime.realtime", "Realtime.connect")
             unwrap("openai.resources.beta.realtime.realtime", "AsyncRealtime.connect")

packages/opentelemetry-instrumentation-openai/tests/traces/cassettes/test_responses/test_responses_parse.yaml

@@ -0,0 +1,114 @@
+interactions:
+- request:
+    body: '{"input":"Extract: Alice is 30 years old.","model":"gpt-4.1-nano","text":{"format":{"type":"json_schema","strict":true,"name":"Person","schema":{"properties":{"name":{"title":"Name","type":"string"},"age":{"title":"Age","type":"integer"}},"required":["name","age"],"title":"Person","type":"object","additionalProperties":false}}}}'
+    headers:
+      Accept:
+      - application/json
+      Accept-Encoding:
+      - gzip, deflate
+      Connection:
+      - keep-alive
+      Content-Length:
+      - '330'
+      Content-Type:
+      - application/json
+      Host:
+      - api.openai.com
+      User-Agent:
+      - OpenAI/Python 1.99.7
+      X-Stainless-Arch:
+      - arm64
+      X-Stainless-Async:
+      - 'false'
+      X-Stainless-Lang:
+      - python
+      X-Stainless-OS:
+      - MacOS
+      X-Stainless-Package-Version:
+      - 1.99.7
+      X-Stainless-Runtime:
+      - CPython
+      X-Stainless-Runtime-Version:
+      - 3.10.20
+      x-stainless-read-timeout:
+      - '600'
+      x-stainless-retry-count:
+      - '0'
+    method: POST
+    uri: https://api.openai.com/v1/responses
+  response:
+    body:
+      string: !!binary |
+        H4sIAAAAAAAA/31Vy3KjMBC8+ytSnO0t4eCAc8sPbOUeb1GyGIgSIbF6uOJK+d93JAwIYu8NpjWt
+        efSMvlcPDwmvkueHRIPpSrKtH4unakfTPctytifkiaZFdqxgT4EU6Z5QhrYiLdKMbVN2zJK1p1DH
+        D2B2oFHSQG9nGqiFqqQeS/N8v8/ztNgGzFhqnfE+TLWdADzXOx0p+2y0ctLHVVNhoDdzIbhs0PaN
+        v2jo6Bm096/gBEJ1+IPApb94oFxcnQUUtFbeUzohgqHW8NeBZOeyA0mFPSNIfpGAcTmQlRVYyoWJ
+        Pbk0VjtmOSYd21v6VSpnO2dLqz7hJ2iVEiWjYk7XqgqEz6np7Cb7lW4klWqzJdvdhmSb9Fpuf0pT
+        f2fs21+HlrdQn75KY39b09xtLxBS1KG9BaHZDgijj0/5Ltv39wUWe+4g8IAxtIEJuNfHADIlLcgp
+        qDiwGe1QK/iyo3c4QKVUlg71ffszA4VqOq2ON5BAhLzfh0TSFg7J8yF5EZzh1/qQYAJoeSSXZPS5
+        XL9GmkQrEUKjxnBMErNYDQfDIRSgxv6BmPcS5dALtsNZQE3BDU0hdOLKmXIYlzI0aWwlJtV2FinZ
+        O5SfcL6LafDl7YWAWixbaJU+9yrB2TNKzkYmtCMUZqDz01DXSi9sxrUt1cO941gZWoM9Y7D+0prD
+        bIgM6BMWuLR8GMuaOtG3E1WiNMTVsdB2XsQumNNrYa7RXcPFuFo6/Udy+cDMSoMVaOkktgoM07xb
+        zEWAvAa83yto9IzE21M8R6L0BcbIMAszs08ssc3HxG0vlN8eXi/Aa8C4JXwnIvAyl3nzP+aX5i4x
+        x442/epbSnl2R+JXHNdQzWZxSOpHLON/NFZTPIsyxnPcvwQRQquK+5ZQ8RoXNiz21SLMUKbwkHid
+        rCIsOYE+KsPDGOESqrhrp3XfD+C7QvmFiXVWJSMwbQf87cpoZ5DR2MUa1E6yYbsmFTf0KIa3yZm4
+        UVj82YLf5euf9ujVGGUchreaHMks1eW7kZJbwC3eceTvUVvcpWICn/KxhM7Mp7lF9oraMBuX1eUf
+        rsQ+qioIAAA=
+    headers:
+      Access-Control-Expose-Headers:
+      - CF-Ray
+      CF-Cache-Status:
+      - DYNAMIC
+      CF-Ray:
+      - a02dd1c7bb56ae7c-TLV
+      Connection:
+      - keep-alive
+      Content-Encoding:
+      - gzip
+      Content-Type:
+      - application/json
+      Date:
+      - Thu, 28 May 2026 14:06:24 GMT
+      Server:
+      - cloudflare
+      Strict-Transport-Security:
+      - max-age=31536000; includeSubDomains; preload
+      Transfer-Encoding:
+      - chunked
+      X-Content-Type-Options:
+      - nosniff
+      access-control-expose-headers:
+      - X-Request-ID
+      - CF-Ray
+      alt-svc:
+      - h3=":443"; ma=86400
+      openai-organization:
+      - traceloop
+      openai-processing-ms:
+      - '1846'
+      openai-project:
+      - proj_tzz1TbPPOXaf6j9tEkVUBIAa
+      openai-version:
+      - '2020-10-01'
+      set-cookie:
+      - __cf_bm=ze2YJE7X1Sq.Cjr_Fk8dIg2ja.e5CkcNyga3DsAhsMU-1779977181.391377-1.0.1.1-7s8F8JKzp7dG15jArIJ6k9j3_ywIDbNprDFJQvgcCRU9WheM_rXhmpDeNnoz6T.KQnW2GOG1reXTFCyyhXu6mn5dAoYoFt1iWdd4BC07o0Zs6FfYJDg59_gDxJW5Xhmc;
+        HttpOnly; SameSite=None; Secure; Path=/; Domain=api.openai.com; Expires=Thu,
+        28 May 2026 14:36:24 GMT
+      x-ratelimit-limit-requests:
+      - '30000'
+      x-ratelimit-limit-tokens:
+      - '150000000'
+      x-ratelimit-remaining-requests:
+      - '29999'
+      x-ratelimit-remaining-tokens:
+      - '149999925'
+      x-ratelimit-reset-requests:
+      - 2ms
+      x-ratelimit-reset-tokens:
+      - 0s
+      x-request-id:
+      - req_7b54d269740449c1a63e79934079420a
+    status:
+      code: 200
+      message: OK
+version: 1

packages/opentelemetry-instrumentation-openai/tests/traces/cassettes/test_responses/test_responses_parse_async.yaml

@@ -0,0 +1,114 @@
+interactions:
+- request:
+    body: '{"input":"Extract: Bob is 42 years old.","model":"gpt-4.1-nano","text":{"format":{"type":"json_schema","strict":true,"name":"Person","schema":{"properties":{"name":{"title":"Name","type":"string"},"age":{"title":"Age","type":"integer"}},"required":["name","age"],"title":"Person","type":"object","additionalProperties":false}}}}'
+    headers:
+      Accept:
+      - application/json
+      Accept-Encoding:
+      - gzip, deflate
+      Connection:
+      - keep-alive
+      Content-Length:
+      - '328'
+      Content-Type:
+      - application/json
+      Host:
+      - api.openai.com
+      User-Agent:
+      - AsyncOpenAI/Python 1.99.7
+      X-Stainless-Arch:
+      - arm64
+      X-Stainless-Async:
+      - async:asyncio
+      X-Stainless-Lang:
+      - python
+      X-Stainless-OS:
+      - MacOS
+      X-Stainless-Package-Version:
+      - 1.99.7
+      X-Stainless-Runtime:
+      - CPython
+      X-Stainless-Runtime-Version:
+      - 3.10.20
+      x-stainless-read-timeout:
+      - '600'
+      x-stainless-retry-count:
+      - '0'
+    method: POST
+    uri: https://api.openai.com/v1/responses
+  response:
+    body:
+      string: !!binary |
+        H4sIAAAAAAAA/31VTXObMBC9+1dkdLY74OBgcmt/QCf3uMMssBAlQqKS8MST8X/vShgQjt0b2sc+
+        7cfb1dfq4YHxij0/MI2my6Nt/bit4h2WdZbEO4iiJ4j3SYERwFO5j7MyKyB5zDJIk7IosAa2dhSq
+        eMfSjjRKGhzspUawWOXgsDhNsyxNic9jxoLtjfMpVdsJpP8GpwLKj0arXrq4ahAGBzMXgsuGbF90
+        JEMHJ9TOv8IjCtXRgYDzcPFIeXX1zqOotXKeshfCG2qNf3uU5SnvUIKwJwKjH5HHuBzJ8gotcGFC
+        Ty6N1X1pOSUd2lv4zFVvu97mVn3gd9AqJfISxJKuVRUKl1PT2U3yI95IkGqzjba7TZRs4oRNf2lw
+        d4a+w3VkefX1Gao09bc1zf32xtU+S4b2Zk9JscviYp89psXe3+dZ7KlDz4PGQIMzcK+PHiyVtCjn
+        oMLAFrRjrfDTTt7+B5BSWRjr+/pnAQrVdFoVNxBPRLxfByahxQN7PrBfqjiw9YFR+HROtmc2eZwv
+        XxMJ00r4wMAYTilSDqvxR/8TyU9T91AsO0liGOTa0SSQovCGogg6ctWbfByW3LdoaiSl1HaWKMs3
+        zD/wdBfT6Io7yICUmLfYKn0aNEKTZ5RcDIxvhi/LSOdmoa6VvrKZvm1Bj/dOQ2WgRnuiYN2lNcfF
+        CBnUR07pWj4OZQ29GJpJGlEaw+pYbDsn4d6b40thLtFdwqW4WpjPgVjeKbPcUAVamKVWoSk1766m
+        wkNOAc7vBTV5BtIdKJ4DSboCU2SUhVnYZ5bQ5mLidhDKbwevr8BLwLQjXCcC8LwUefM/5p/NXWJO
+        HW2GxXct5cUdzC04rrFaTOKY1LdYpnMwVHM8V2UMp3h4BwIEqoq7loB4CQvr1/rqKkxfJv+MOJ2s
+        AowdURfKcD9GtIIq3rfzsh8G8E2R/PzE9laxCZh3Ax27PNgY0WTsQg3qXpbjbmUVN1CI8WXqTdgo
+        Kv5ive/S9Xd78GZMMvbDW82O0SLV61cjjm4Bt3inkb9HbWmTihl8SqcS9mY5zS2xV2D9bJxX539H
+        CWiCKAgAAA==
+    headers:
+      Access-Control-Expose-Headers:
+      - CF-Ray
+      CF-Cache-Status:
+      - DYNAMIC
+      CF-Ray:
+      - a02dd1db6b6e36f8-TLV
+      Connection:
+      - keep-alive
+      Content-Encoding:
+      - gzip
+      Content-Type:
+      - application/json
+      Date:
+      - Thu, 28 May 2026 14:06:26 GMT
+      Server:
+      - cloudflare
+      Strict-Transport-Security:
+      - max-age=31536000; includeSubDomains; preload
+      Transfer-Encoding:
+      - chunked
+      X-Content-Type-Options:
+      - nosniff
+      access-control-expose-headers:
+      - X-Request-ID
+      - CF-Ray
+      alt-svc:
+      - h3=":443"; ma=86400
+      openai-organization:
+      - traceloop
+      openai-processing-ms:
+      - '1424'
+      openai-project:
+      - proj_tzz1TbPPOXaf6j9tEkVUBIAa
+      openai-version:
+      - '2020-10-01'
+      set-cookie:
+      - __cf_bm=QnIHGVWXeYNMsGeR1BuZ28Ux60SAzc5t6Qpj0evXPI4-1779977184.5411139-1.0.1.1-3SZdXI.2.O6Cq6gDmmpmU5ZqHn.8Sb6eRJiQdFRJDz4wd9e_DiDNSJpY7t2aQ0pZhuOn9oh001bCMQYvpyAOKbMhYOLiNm8qF1bkr02208KkHG.SGIesp6H0yfh9..Va;
+        HttpOnly; SameSite=None; Secure; Path=/; Domain=api.openai.com; Expires=Thu,
+        28 May 2026 14:36:26 GMT
+      x-ratelimit-limit-requests:
+      - '30000'
+      x-ratelimit-limit-tokens:
+      - '150000000'
+      x-ratelimit-remaining-requests:
+      - '29999'
+      x-ratelimit-remaining-tokens:
+      - '149999925'
+      x-ratelimit-reset-requests:
+      - 2ms
+      x-ratelimit-reset-tokens:
+      - 0s
+      x-request-id:
+      - req_77a806b441db4b71803efb3c2fd7c284
+    status:
+      code: 200
+      message: OK
+version: 1

packages/opentelemetry-instrumentation-openai/tests/traces/test_responses.py

@@ -1,5 +1,6 @@
 import json
 import pytest
+from pydantic import BaseModel
 
 from openai import AsyncOpenAI, OpenAI
 from opentelemetry.instrumentation.openai.utils import is_reasoning_supported
@@ -11,6 +12,11 @@
 from .utils import get_input_messages, get_output_messages
 
 
+class Person(BaseModel):
+    name: str
+    age: int
+
+
 @pytest.mark.vcr
 def test_responses(
     instrument_legacy, span_exporter: InMemorySpanExporter, openai_client: OpenAI
@@ -406,6 +412,77 @@ async def test_responses_streaming_async_with_context_manager(
     assert output_messages[0]["parts"][0]["content"] == full_text
 
 
+@pytest.mark.vcr
+def test_responses_parse(
+    instrument_legacy, span_exporter: InMemorySpanExporter, openai_client: OpenAI
+):
+    """Structured-output via responses.parse() must produce an LLM span with usage
+    and capture the prompt + structured response on the span."""
+    input_text = "Extract: Alice is 30 years old."
+    response = openai_client.responses.parse(
+        model="gpt-4.1-nano",
+        input=input_text,
+        text_format=Person,
+    )
+    spans = span_exporter.get_finished_spans()
+    assert len(spans) == 1, f"expected one openai.response span, got {len(spans)}"
+    span = spans[0]
+    assert span.name == "openai.response"
+    assert span.attributes["gen_ai.provider.name"] == "openai"
+    assert span.attributes["gen_ai.request.model"] == "gpt-4.1-nano"
+    assert span.attributes["gen_ai.usage.input_tokens"] > 0
+    assert span.attributes["gen_ai.usage.output_tokens"] > 0
+
+    input_messages = get_input_messages(span)
+    assert input_messages[0]["role"] == "user"
+    assert input_messages[0]["parts"][0]["content"] == input_text
+
+    output_messages = get_output_messages(span)
+    assert output_messages[0]["role"] == "assistant"
+    output_text = output_messages[0]["parts"][0]["content"]
+    parsed = Person.model_validate_json(output_text)
+    assert parsed == response.output_parsed
+    assert parsed.name == "Alice"
+    assert parsed.age == 30
+
+
+@pytest.mark.vcr
+@pytest.mark.asyncio
+async def test_responses_parse_async(
+    instrument_legacy,
+    span_exporter: InMemorySpanExporter,
+    async_openai_client: AsyncOpenAI,
+):
+    """Async structured-output via responses.parse() must produce an LLM span with usage
+    and capture the prompt + structured response on the span."""
+    input_text = "Extract: Bob is 42 years old."
+    response = await async_openai_client.responses.parse(
+        model="gpt-4.1-nano",
+        input=input_text,
+        text_format=Person,
+    )
+    spans = span_exporter.get_finished_spans()
+    assert len(spans) == 1, f"expected one openai.response span, got {len(spans)}"
+    span = spans[0]
+    assert span.name == "openai.response"
+    assert span.attributes["gen_ai.provider.name"] == "openai"
+    assert span.attributes["gen_ai.request.model"] == "gpt-4.1-nano"
+    assert span.attributes["gen_ai.usage.input_tokens"] > 0
+    assert span.attributes["gen_ai.usage.output_tokens"] > 0
+
+    input_messages = get_input_messages(span)
+    assert input_messages[0]["role"] == "user"
+    assert input_messages[0]["parts"][0]["content"] == input_text
+
+    output_messages = get_output_messages(span)
+    assert output_messages[0]["role"] == "assistant"
+    output_text = output_messages[0]["parts"][0]["content"]
+    parsed = Person.model_validate_json(output_text)
+    assert parsed == response.output_parsed
+    assert parsed.name == "Bob"
+    assert parsed.age == 42
+
+
 def test_get_tools_from_kwargs_with_none():
     """Test that get_tools_from_kwargs handles None tools value correctly.