Skip to content

Same agent Smaller bill. The tools and infrastructure to get more work from your AI. Fewer tokens. Less compute. Lower cost.

fix(openai): measured-zero reasoning vs unknown + derived completed tokens (#1537 chat-completions path) (#1543)

Roy Tongf806ffb71287
diff --git a/sdk/python/src/openlit/instrumentation/openai/async_openai.py b/sdk/python/src/openlit/instrumentation/openai/async_openai.py
index 05278225..0c2841c3 100644
--- a/sdk/python/src/openlit/instrumentation/openai/async_openai.py
+++ b/sdk/python/src/openlit/instrumentation/openai/async_openai.py
@@ -308,7 +308,9 @@ def async_responses(
self._finish_reason = ""
self._input_tokens = 0
self._output_tokens = 0
- self._reasoning_tokens = 0
+ # Do not default _reasoning_tokens. Absence means no usage was
+ # received yet; a literal 0 is a measured zero and would be emitted
+ # as reported=true if the stream ends without response.completed.
self._operation_type = "responses"
self._service_tier = "default"
self._tools = None
diff --git a/sdk/python/src/openlit/instrumentation/openai/openai.py b/sdk/python/src/openlit/instrumentation/openai/openai.py
index 02932b9a..de5d4e6b 100644
--- a/sdk/python/src/openlit/instrumentation/openai/openai.py
+++ b/sdk/python/src/openlit/instrumentation/openai/openai.py
@@ -310,7 +310,9 @@ def responses(
self._finish_reason = ""
self._input_tokens = 0
self._output_tokens = 0
- self._reasoning_tokens = 0
+ # Do not default _reasoning_tokens. Absence means no usage was
+ # received yet; a literal 0 is a measured zero and would be emitted
+ # as reported=true if the stream ends without response.completed.
self._operation_type = "responses"
self._service_tier = "default"
self._tools = None
diff --git a/sdk/python/src/openlit/instrumentation/openai/utils.py b/sdk/python/src/openlit/instrumentation/openai/utils.py
index 33edc0ea..ff0a7029 100644
--- a/sdk/python/src/openlit/instrumentation/openai/utils.py
+++ b/sdk/python/src/openlit/instrumentation/openai/utils.py
@@ -105,16 +105,67 @@ def extract_reasoning_content(payload):
def extract_reasoning_tokens(usage, details_key):
- """Return reasoning tokens (a subset of output tokens) from a usage dict.
+ """Return reasoning tokens (a subset of output tokens) from a usage dict,
+ or None when the provider did not report the details object.
Works for both chat completions (``completion_tokens_details``) and the
- responses API (``output_tokens_details``) and falls back to 0 whenever the
- details object is missing or not a dict.
+ responses API (``output_tokens_details``). A missing or non-dict details
+ object means "unknown" and stays distinguishable from an explicit
+ ``reasoning_tokens: 0`` measurement (None vs 0): a reported 0 is a
+ measurement, an absent object is an unknown, and the two must not collapse
+ into the same value.
"""
- details = (usage or {}).get(details_key) or {}
+ details = (usage or {}).get(details_key)
if not isinstance(details, dict):
- details = {}
- return details.get("reasoning_tokens", 0) or 0
+ return None
+ value = details.get("reasoning_tokens")
+ if not isinstance(value, (int, float)) or isinstance(value, bool):
+ return None
+ return value
+
+
+def set_reasoning_subset_attributes(span, output_tokens, reasoning_tokens):
+ """Emit reasoning-token attributes under the subset invariant.
+
+ ``gen_ai.usage.reasoning.output_tokens`` is a facet of the output total,
+ never an addend. Three states stay distinguishable:
+
+ * provider reported a value (including an explicit 0): the facet is
+ emitted, ``...output_tokens.reported`` is true, and the derived
+ completed figure is available;
+ * provider sent no details object: no facet value, marker false
+ (unknown, not a guessed 0);
+ * no usage at all (stream without include_usage): nothing emitted.
+
+ The completed figure is output minus reasoning and lives under the
+ ``gen_ai.usage.derived.*`` namespace so it can never be mistaken for a
+ provider-reported number.
+ """
+ if reasoning_tokens is None:
+ span.set_attribute(
+ SemanticConvention.GEN_AI_USAGE_REASONING_OUTPUT_TOKENS_REPORTED,
+ False,
+ )
+ return
+ span.set_attribute(
+ SemanticConvention.GEN_AI_USAGE_REASONING_OUTPUT_TOKENS_REPORTED,
+ True,
+ )
+ span.set_attribute(
+ SemanticConvention.GEN_AI_USAGE_REASONING_OUTPUT_TOKENS,
+ reasoning_tokens,
+ )
+ # OpenLIT legacy alias (pre-OTel naming), kept for backward compat; only
+ # nonzero values so legacy consumers see no behavior change.
+ if reasoning_tokens > 0:
+ span.set_attribute(
+ SemanticConvention.GEN_AI_USAGE_REASONING_TOKENS,
+ reasoning_tokens,
+ )
+ span.set_attribute(
+ SemanticConvention.GEN_AI_USAGE_DERIVED_COMPLETED_OUTPUT_TOKENS,
+ max(output_tokens - reasoning_tokens, 0),
+ )
def format_content(messages):
@@ -1076,16 +1127,11 @@ def common_response_logic(
# Reasoning tokens. OTel: gen_ai.usage.reasoning.output_tokens is a subset
# of gen_ai.usage.output_tokens (already set above), so it is recorded as a
- # separate attribute and never added on top of the output total.
- if hasattr(scope, "_reasoning_tokens") and scope._reasoning_tokens > 0:
- scope._span.set_attribute(
- SemanticConvention.GEN_AI_USAGE_REASONING_OUTPUT_TOKENS,
- scope._reasoning_tokens,
- )
- # OpenLIT legacy alias (pre-OTel naming), kept for backward compat.
- scope._span.set_attribute(
- SemanticConvention.GEN_AI_USAGE_REASONING_TOKENS,
- scope._reasoning_tokens,
+ # separate attribute and never added on top of the output total. Missing
+ # details surface as unknown (marker false), never as a guessed 0.
+ if hasattr(scope, "_reasoning_tokens"):
+ set_reasoning_subset_attributes(
+ scope._span, output_tokens, scope._reasoning_tokens
)
# OTel cached token attributes (set even when 0)
@@ -1591,16 +1637,11 @@ def common_chat_logic(
# Reasoning tokens (OTel: gen_ai.usage.reasoning.output_tokens is a subset
# of gen_ai.usage.output_tokens above, so it is recorded separately and
- # never added on top of the output total / token-usage metric).
- if hasattr(scope, "_reasoning_tokens") and scope._reasoning_tokens > 0:
- scope._span.set_attribute(
- SemanticConvention.GEN_AI_USAGE_REASONING_OUTPUT_TOKENS,
- scope._reasoning_tokens,
- )
- # OpenLIT legacy alias (pre-OTel naming), kept for backward compat.
- scope._span.set_attribute(
- SemanticConvention.GEN_AI_USAGE_REASONING_TOKENS,
- scope._reasoning_tokens,
+ # never added on top of the output total / token-usage metric). Missing
+ # details surface as unknown (marker false), never as a guessed 0.
+ if hasattr(scope, "_reasoning_tokens"):
+ set_reasoning_subset_attributes(
+ scope._span, output_tokens, scope._reasoning_tokens
)
# OTel cached token attributes (set even when 0)
diff --git a/sdk/python/src/openlit/semcov/__init__.py b/sdk/python/src/openlit/semcov/__init__.py
index 03459d84..170c0f14 100644
--- a/sdk/python/src/openlit/semcov/__init__.py
+++ b/sdk/python/src/openlit/semcov/__init__.py
@@ -571,6 +571,12 @@ class SemanticConvention:
GEN_AI_USAGE_COMPLETION_TOKENS_DETAILS_REASONING = (
"gen_ai.usage.completion_tokens_details.reasoning_tokens"
)
+ GEN_AI_USAGE_REASONING_OUTPUT_TOKENS_REPORTED = (
+ "gen_ai.usage.reasoning.output_tokens.reported"
+ )
+ GEN_AI_USAGE_DERIVED_COMPLETED_OUTPUT_TOKENS = (
+ "gen_ai.usage.derived.completed_output_tokens"
+ )
# OTel GenAI semconv (experimental): reasoning output tokens are a subset of
# gen_ai.usage.output_tokens and MUST NOT be added on top of it.
GEN_AI_USAGE_REASONING_OUTPUT_TOKENS = "gen_ai.usage.reasoning.output_tokens"
diff --git a/sdk/python/tests/test_openai_reasoning_subset_fixture.py b/sdk/python/tests/test_openai_reasoning_subset_fixture.py
new file mode 100644
index 00000000..245d35d3
--- /dev/null
+++ b/sdk/python/tests/test_openai_reasoning_subset_fixture.py
@@ -0,0 +1,333 @@
+"""Fixture tests for the reasoning-subset invariant (Issue #1537).
+
+Locks the invariant into a regression fixture for the OpenAI chat-completions
+path, in the exact shape proposed in #1537:
+
+ usage = {output_tokens: 1000, reasoning_tokens: 700}
+ -> recorded output = 1000 (provider total, unchanged)
+ -> reasoning emitted as a facet (700), never added on top
+ -> no downstream aggregate can reach 1700
+ -> a derived "completed tokens" figure equals output - reasoning and is
+ namespaced gen_ai.usage.derived.* so it reads as derived
+ -> a provider that stops sending *_tokens_details surfaces as unknown
+ (reported marker false, no facet value), never as a guessed 0
+ -> an explicit reasoning_tokens: 0 is a measurement: facet 0, marker true
+"""
+
+import time
+from types import SimpleNamespace
+from unittest.mock import MagicMock
+
+from opentelemetry.sdk.trace import TracerProvider
+from opentelemetry.sdk.trace.export import SimpleSpanProcessor
+from opentelemetry.sdk.trace.export.in_memory_span_exporter import (
+ InMemorySpanExporter,
+)
+
+from openlit._config import OpenlitConfig
+from openlit.instrumentation.openai.utils import (
+ process_chat_chunk,
+ process_chat_response,
+ process_response_chunk,
+ process_streaming_chat_response,
+ process_streaming_response_response,
+)
+from openlit.semcov import SemanticConvention
+
+
+def _tracer_and_exporter():
+ OpenlitConfig.reset_to_defaults()
+ exporter = InMemorySpanExporter()
+ tracer_provider = TracerProvider()
+ tracer_provider.add_span_processor(SimpleSpanProcessor(exporter))
+ return tracer_provider.get_tracer("test-openai-reasoning-fixture"), exporter
+
+
+def _metrics_dict():
+ return {
+ "genai_client_usage_tokens": MagicMock(),
+ "genai_client_operation_duration": MagicMock(),
+ "genai_client_time_to_first_chunk": MagicMock(),
+ "genai_client_time_per_output_chunk": MagicMock(),
+ "genai_server_tbt": MagicMock(),
+ "genai_server_ttft": MagicMock(),
+ "genai_server_request_duration": MagicMock(),
+ "genai_cost": MagicMock(),
+ }
+
+
+def _stream_scope(span):
+ return SimpleNamespace(
+ _span=span,
+ _llmresponse="",
+ _response_id="",
+ _response_model="",
+ _finish_reason="",
+ _system_fingerprint="",
+ _service_tier="auto",
+ _tools=None,
+ _kwargs={
+ "model": "o3-mini",
+ "messages": [{"role": "user", "content": "think step by step"}],
+ },
+ _start_time=time.time(),
+ _end_time=None,
+ _timestamps=[],
+ _ttft=0,
+ _tbt=0,
+ _server_address="api.openai.com",
+ _server_port=443,
+ )
+
+
+def _run_chat_response(exporter, tracer, metrics, usage):
+ response = {
+ "id": "chatcmpl_fixture",
+ "model": "o3-mini",
+ "choices": [
+ {
+ "message": {"role": "assistant", "content": "The answer is 42."},
+ "finish_reason": "stop",
+ }
+ ],
+ "usage": usage,
+ }
+ with tracer.start_as_current_span("chat fixture") as span:
+ process_chat_response(
+ response,
+ request_model="o3-mini",
+ pricing_info={},
+ server_port=443,
+ server_address="api.openai.com",
+ environment="test-env",
+ application_name="test-app",
+ metrics=metrics,
+ start_time=time.time(),
+ span=span,
+ capture_message_content=False,
+ disable_metrics=False,
+ version="test-version",
+ model="o3-mini",
+ messages=[{"role": "user", "content": "hi"}],
+ )
+ return exporter.get_finished_spans()[0].attributes
+
+
+def test_fixture_recorded_values_never_reach_the_sum():
+ """output 1000 / reasoning 700: facet 700, derived 300, no 1700 anywhere."""
+ tracer, exporter = _tracer_and_exporter()
+ metrics = _metrics_dict()
+ attrs = _run_chat_response(
+ tracer=tracer,
+ exporter=exporter,
+ metrics=metrics,
+ usage={
+ "prompt_tokens": 500,
+ "completion_tokens": 1000,
+ "completion_tokens_details": {
+ "reasoning_tokens": 700,
+ "text_tokens": 300,
+ },
+ },
+ )
+ assert attrs[SemanticConvention.GEN_AI_USAGE_OUTPUT_TOKENS] == 1000
+ assert attrs[SemanticConvention.GEN_AI_USAGE_REASONING_OUTPUT_TOKENS] == 700
+ assert (
+ attrs[SemanticConvention.GEN_AI_USAGE_REASONING_OUTPUT_TOKENS_REPORTED]
+ is True
+ )
+ assert (
+ attrs[SemanticConvention.GEN_AI_USAGE_DERIVED_COMPLETED_OUTPUT_TOKENS]
+ == 300
+ )
+ # No single recorded value may equal the forbidden aggregate.
+ forbidden = 1700
+ assert all(value != forbidden for value in attrs.values())
+ for call in metrics["genai_client_usage_tokens"].record.call_args_list:
+ assert call.args[0] != forbidden
+
+
+def test_fixture_missing_details_is_unknown_not_zero():
+ """No completion_tokens_details: reported false, no facet value."""
+ tracer, exporter = _tracer_and_exporter()
+ metrics = _metrics_dict()
+ attrs = _run_chat_response(
+ tracer=tracer,
+ exporter=exporter,
+ metrics=metrics,
+ usage={"prompt_tokens": 500, "completion_tokens": 1000},
+ )
+ assert attrs[SemanticConvention.GEN_AI_USAGE_OUTPUT_TOKENS] == 1000
+ assert SemanticConvention.GEN_AI_USAGE_REASONING_OUTPUT_TOKENS not in attrs
+ assert (
+ attrs[SemanticConvention.GEN_AI_USAGE_REASONING_OUTPUT_TOKENS_REPORTED]
+ is False
+ )
+ assert SemanticConvention.GEN_AI_USAGE_DERIVED_COMPLETED_OUTPUT_TOKENS not in attrs
+
+
+def test_fixture_explicit_zero_is_a_measurement():
+ """reasoning_tokens: 0 is measured zero, distinct from unknown."""
+ tracer, exporter = _tracer_and_exporter()
+ metrics = _metrics_dict()
+ attrs = _run_chat_response(
+ tracer=tracer,
+ exporter=exporter,
+ metrics=metrics,
+ usage={
+ "prompt_tokens": 500,
+ "completion_tokens": 1000,
+ "completion_tokens_details": {"reasoning_tokens": 0},
+ },
+ )
+ assert attrs[SemanticConvention.GEN_AI_USAGE_OUTPUT_TOKENS] == 1000
+ assert attrs[SemanticConvention.GEN_AI_USAGE_REASONING_OUTPUT_TOKENS] == 0
+ assert (
+ attrs[SemanticConvention.GEN_AI_USAGE_REASONING_OUTPUT_TOKENS_REPORTED]
+ is True
+ )
+ assert (
+ attrs[SemanticConvention.GEN_AI_USAGE_DERIVED_COMPLETED_OUTPUT_TOKENS]
+ == 1000
+ )
+
+
+def test_fixture_streaming_chat_path():
+ """The same fixture through the streaming chat path (include_usage)."""
+ tracer, exporter = _tracer_and_exporter()
+ metrics = _metrics_dict()
+ span = tracer.start_span("chat fixture stream")
+ scope = _stream_scope(span)
+
+ process_chat_chunk(
+ scope,
+ {
+ "id": "chatcmpl_fixture_stream",
+ "model": "o3-mini",
+ "choices": [{"delta": {"content": "The answer is 42."}}],
+ },
+ )
+ process_chat_chunk(
+ scope,
+ {
+ "choices": [],
+ "usage": {
+ "prompt_tokens": 500,
+ "completion_tokens": 1000,
+ "completion_tokens_details": {
+ "reasoning_tokens": 700,
+ "text_tokens": 300,
+ },
+ },
+ },
+ )
+ with span:
+ process_streaming_chat_response(
+ scope,
+ pricing_info={},
+ environment="test-env",
+ application_name="test-app",
+ metrics=metrics,
+ capture_message_content=False,
+ disable_metrics=False,
+ version="test-version",
+ )
+
+ attrs = exporter.get_finished_spans()[0].attributes
+ assert attrs[SemanticConvention.GEN_AI_USAGE_OUTPUT_TOKENS] == 1000
+ assert attrs[SemanticConvention.GEN_AI_USAGE_REASONING_OUTPUT_TOKENS] == 700
+ assert (
+ attrs[SemanticConvention.GEN_AI_USAGE_DERIVED_COMPLETED_OUTPUT_TOKENS]
+ == 300
+ )
+ assert all(value != 1700 for value in attrs.values())
+
+
+def _responses_stream_scope(span):
+ """Matches production Responses wrappers: no _reasoning_tokens until usage."""
+ return SimpleNamespace(
+ _span=span,
+ _llmresponse="",
+ _response_id="",
+ _response_model="",
+ _finish_reason="",
+ _input_tokens=0,
+ _output_tokens=0,
+ _operation_type="responses",
+ _service_tier="default",
+ _tools=None,
+ _response_tools=None,
+ _kwargs={
+ "model": "o3-mini",
+ "input": "think step by step",
+ },
+ _start_time=time.time(),
+ _end_time=None,
+ _timestamps=[],
+ _ttft=0,
+ _tbt=0,
+ _server_address="api.openai.com",
+ _server_port=443,
+ )
+
+
+def test_fixture_streaming_chat_without_usage_emits_nothing():
+ """No include_usage chunk: third state, no reasoning attributes at all."""
+ tracer, exporter = _tracer_and_exporter()
+ metrics = _metrics_dict()
+ span = tracer.start_span("chat fixture stream no usage")
+ scope = _stream_scope(span)
+
+ process_chat_chunk(
+ scope,
+ {
+ "id": "chatcmpl_fixture_stream_no_usage",
+ "model": "o3-mini",
+ "choices": [{"delta": {"content": "The answer is 42."}}],
+ },
+ )
+ with span:
+ process_streaming_chat_response(
+ scope,
+ pricing_info={},
+ environment="test-env",
+ application_name="test-app",
+ metrics=metrics,
+ capture_message_content=False,
+ disable_metrics=False,
+ version="test-version",
+ )
+
+ attrs = exporter.get_finished_spans()[0].attributes
+ assert SemanticConvention.GEN_AI_USAGE_REASONING_OUTPUT_TOKENS not in attrs
+ assert SemanticConvention.GEN_AI_USAGE_REASONING_OUTPUT_TOKENS_REPORTED not in attrs
+ assert SemanticConvention.GEN_AI_USAGE_DERIVED_COMPLETED_OUTPUT_TOKENS not in attrs
+
+
+def test_fixture_streaming_responses_without_completed_emits_nothing():
+ """Responses stream with no usage payload must not look like measured zero."""
+ tracer, exporter = _tracer_and_exporter()
+ metrics = _metrics_dict()
+ span = tracer.start_span("responses fixture stream no completed")
+ scope = _responses_stream_scope(span)
+
+ process_response_chunk(
+ scope,
+ {"type": "response.output_text.delta", "delta": "The answer is 42."},
+ )
+ with span:
+ process_streaming_response_response(
+ scope,
+ pricing_info={},
+ environment="test-env",
+ application_name="test-app",
+ metrics=metrics,
+ capture_message_content=False,
+ disable_metrics=False,
+ version="test-version",
+ )
+
+ attrs = exporter.get_finished_spans()[0].attributes
+ assert SemanticConvention.GEN_AI_USAGE_REASONING_OUTPUT_TOKENS not in attrs
+ assert SemanticConvention.GEN_AI_USAGE_REASONING_OUTPUT_TOKENS_REPORTED not in attrs
+ assert SemanticConvention.GEN_AI_USAGE_DERIVED_COMPLETED_OUTPUT_TOKENS not in attrs
diff --git a/sdk/python/tests/test_openai_reasoning_tokens.py b/sdk/python/tests/test_openai_reasoning_tokens.py
index 8c3e2f58..c171f122 100644
--- a/sdk/python/tests/test_openai_reasoning_tokens.py
+++ b/sdk/python/tests/test_openai_reasoning_tokens.py
@@ -30,8 +30,10 @@ from openlit._config import OpenlitConfig
from openlit.instrumentation.openai.utils import (
process_chat_chunk,
process_chat_response,
+ process_response_chunk,
process_response_response,
process_streaming_chat_response,
+ process_streaming_response_response,
)
from openlit.semcov import SemanticConvention
@@ -98,6 +100,7 @@ def _assert_no_double_counting(attrs, metrics, output_tokens=1000, reasoning_tok
def _stream_scope(span):
+ """Chat streaming scope. Matches production: no _reasoning_tokens until usage."""
return SimpleNamespace(
_span=span,
_llmresponse="",
@@ -121,6 +124,41 @@ def _stream_scope(span):
)
+def _responses_stream_scope(span):
+ """Responses streaming scope. Matches production: no _reasoning_tokens until usage."""
+ return SimpleNamespace(
+ _span=span,
+ _llmresponse="",
+ _response_id="",
+ _response_model="",
+ _finish_reason="",
+ _input_tokens=0,
+ _output_tokens=0,
+ _operation_type="responses",
+ _service_tier="default",
+ _tools=None,
+ _response_tools=None,
+ _kwargs={
+ "model": "o3-mini",
+ "input": "think step by step",
+ },
+ _start_time=time.time(),
+ _end_time=None,
+ _timestamps=[],
+ _ttft=0,
+ _tbt=0,
+ _server_address="api.openai.com",
+ _server_port=443,
+ )
+
+
+def _assert_no_reasoning_usage_attrs(attrs):
+ assert SemanticConvention.GEN_AI_USAGE_REASONING_OUTPUT_TOKENS not in attrs
+ assert SemanticConvention.GEN_AI_USAGE_REASONING_OUTPUT_TOKENS_REPORTED not in attrs
+ assert SemanticConvention.GEN_AI_USAGE_DERIVED_COMPLETED_OUTPUT_TOKENS not in attrs
+ assert SemanticConvention.GEN_AI_USAGE_REASONING_TOKENS not in attrs
+
+
def test_chat_completions_reasoning_tokens_are_subset_of_output():
"""o1/o3-style chat completion: reasoning stays a subset of output tokens."""
tracer, exporter = _tracer_and_exporter()
@@ -253,8 +291,113 @@ def test_responses_api_reasoning_tokens_are_subset_of_output():
_assert_no_double_counting(exporter.get_finished_spans()[0].attributes, metrics)
-def test_no_reasoning_tokens_omits_reasoning_attribute():
- """No completion_tokens_details: reasoning attribute absent, output intact."""
+def test_streaming_chat_without_usage_emits_no_reasoning_attrs():
+ """Chat stream without include_usage: no reasoning attributes at all."""
+ tracer, exporter = _tracer_and_exporter()
+ metrics = _metrics_dict()
+ span = tracer.start_span("chat no usage")
+ scope = _stream_scope(span)
+
+ process_chat_chunk(
+ scope,
+ {
+ "id": "chatcmpl_no_usage",
+ "model": "o3-mini",
+ "choices": [{"delta": {"content": "The answer is 42."}}],
+ },
+ )
+
+ with span:
+ process_streaming_chat_response(
+ scope,
+ pricing_info={},
+ environment="test-env",
+ application_name="test-app",
+ metrics=metrics,
+ capture_message_content=False,
+ disable_metrics=False,
+ version="test-version",
+ )
+
+ _assert_no_reasoning_usage_attrs(exporter.get_finished_spans()[0].attributes)
+
+
+def test_streaming_responses_without_completed_emits_no_reasoning_attrs():
+ """Responses stream with no response.completed: skip reasoning attrs entirely.
+
+ Production wrappers must not default _reasoning_tokens to 0; a literal 0 is
+ a measured zero and would emit reported=true plus a derived completed figure.
+ """
+ tracer, exporter = _tracer_and_exporter()
+ metrics = _metrics_dict()
+ span = tracer.start_span("responses no completed")
+ scope = _responses_stream_scope(span)
+
+ process_response_chunk(
+ scope,
+ {"type": "response.output_text.delta", "delta": "The answer is 42."},
+ )
+
+ with span:
+ process_streaming_response_response(
+ scope,
+ pricing_info={},
+ environment="test-env",
+ application_name="test-app",
+ metrics=metrics,
+ capture_message_content=False,
+ disable_metrics=False,
+ version="test-version",
+ )
+
+ _assert_no_reasoning_usage_attrs(exporter.get_finished_spans()[0].attributes)
+
+
+def test_streaming_responses_with_usage_keeps_subset():
+ """Responses stream with response.completed usage: reasoning stays a subset."""
+ tracer, exporter = _tracer_and_exporter()
+ metrics = _metrics_dict()
+ span = tracer.start_span("responses stream o3-mini")
+ scope = _responses_stream_scope(span)
+
+ process_response_chunk(
+ scope,
+ {"type": "response.output_text.delta", "delta": "The answer is 42."},
+ )
+ process_response_chunk(
+ scope,
+ {
+ "type": "response.completed",
+ "response": {
+ "id": "resp_stream_o1",
+ "model": "o3-mini",
+ "status": "completed",
+ "usage": {
+ "input_tokens": 500,
+ "output_tokens": 1000,
+ "output_tokens_details": {"reasoning_tokens": 700},
+ },
+ },
+ },
+ )
+
+ with span:
+ process_streaming_response_response(
+ scope,
+ pricing_info={},
+ environment="test-env",
+ application_name="test-app",
+ metrics=metrics,
+ capture_message_content=False,
+ disable_metrics=False,
+ version="test-version",
+ )
+
+ _assert_no_double_counting(exporter.get_finished_spans()[0].attributes, metrics)
+
+
+def test_no_reasoning_tokens_marks_reasoning_unknown():
+ """No completion_tokens_details: facet value absent, reported marker false."""
tracer, exporter = _tracer_and_exporter()
metrics = _metrics_dict()
response = {
@@ -291,6 +434,11 @@ def test_no_reasoning_tokens_omits_reasoning_attribute():
attrs = exporter.get_finished_spans()[0].attributes
assert attrs[SemanticConvention.GEN_AI_USAGE_OUTPUT_TOKENS] == 1000
assert SemanticConvention.GEN_AI_USAGE_REASONING_OUTPUT_TOKENS not in attrs
+ assert (
+ attrs[SemanticConvention.GEN_AI_USAGE_REASONING_OUTPUT_TOKENS_REPORTED]
+ is False
+ )
+ assert SemanticConvention.GEN_AI_USAGE_DERIVED_COMPLETED_OUTPUT_TOKENS not in attrs
output_records = _output_token_usage_records(metrics)
assert output_records
@@ -298,8 +446,8 @@ def test_no_reasoning_tokens_omits_reasoning_attribute():
assert value == 1000
-def test_zero_reasoning_tokens_omits_reasoning_attribute():
- """reasoning_tokens present but 0: no reasoning attrs, output intact."""
+def test_zero_reasoning_tokens_is_a_measurement():
+ """reasoning_tokens explicitly 0: a measurement (facet 0), not unknown."""
tracer, exporter = _tracer_and_exporter()
metrics = _metrics_dict()
response = {
@@ -339,7 +487,18 @@ def test_zero_reasoning_tokens_omits_reasoning_attribute():
attrs = exporter.get_finished_spans()[0].attributes
assert attrs[SemanticConvention.GEN_AI_USAGE_OUTPUT_TOKENS] == 1000
- assert SemanticConvention.GEN_AI_USAGE_REASONING_OUTPUT_TOKENS not in attrs
+ # An explicit 0 is a measurement: facet emitted as 0, marker true, and the
+ # derived completed figure equals the full output. The legacy alias stays
+ # absent so pre-OTel consumers are unaffected.
+ assert attrs[SemanticConvention.GEN_AI_USAGE_REASONING_OUTPUT_TOKENS] == 0
+ assert (
+ attrs[SemanticConvention.GEN_AI_USAGE_REASONING_OUTPUT_TOKENS_REPORTED]
+ is True
+ )
+ assert (
+ attrs[SemanticConvention.GEN_AI_USAGE_DERIVED_COMPLETED_OUTPUT_TOKENS]
+ == 1000
+ )
assert SemanticConvention.GEN_AI_USAGE_REASONING_TOKENS not in attrs
for value, _attrs in _output_token_usage_records(metrics):
@@ -366,7 +525,7 @@ def _non_dict_details_chat_response():
def test_non_dict_completion_tokens_details_does_not_crash():
- """Defensive casting: non-dict details fall back to {}, no exception."""
+ """Defensive casting: non-dict details are unknown, not a guessed 0."""
tracer, exporter = _tracer_and_exporter()
metrics = _metrics_dict()
@@ -392,10 +551,14 @@ def test_non_dict_completion_tokens_details_does_not_crash():
attrs = exporter.get_finished_spans()[0].attributes
assert attrs[SemanticConvention.GEN_AI_USAGE_OUTPUT_TOKENS] == 1000
assert SemanticConvention.GEN_AI_USAGE_REASONING_OUTPUT_TOKENS not in attrs
+ assert (
+ attrs[SemanticConvention.GEN_AI_USAGE_REASONING_OUTPUT_TOKENS_REPORTED]
+ is False
+ )
def test_non_dict_output_tokens_details_does_not_crash():
- """Responses API: non-dict output_tokens_details falls back to {}."""
+ """Responses API: non-dict output_tokens_details is unknown, not a guessed 0."""
tracer, exporter = _tracer_and_exporter()
metrics = _metrics_dict()
response = {
@@ -438,3 +601,7 @@ def test_non_dict_output_tokens_details_does_not_crash():
attrs = exporter.get_finished_spans()[0].attributes
assert attrs[SemanticConvention.GEN_AI_USAGE_OUTPUT_TOKENS] == 1000
assert SemanticConvention.GEN_AI_USAGE_REASONING_OUTPUT_TOKENS not in attrs
+ assert (
+ attrs[SemanticConvention.GEN_AI_USAGE_REASONING_OUTPUT_TOKENS_REPORTED]
+ is False
+ )