Python: Fix Python OTel usage detail attributes (#6493)

* fix python otel usage detail attributes

Map cached/read/reasoning usage detail fields to standard OTel GenAI attributes while preserving provider-specific legacy keys.

Add focused coverage for direct response spans, aggregated agent spans, and provider usage parsing.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* address usage detail review feedback

Omit missing OpenAI Responses usage detail counts while preserving zero-valued counts.

Record zero-valued token usage in OTel histograms and add regression coverage.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

---------

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

python/packages/openai/tests/openai/test_openai_chat_client.py

@@ -3301,6 +3301,7 @@ def test_usage_details_with_cached_tokens() -> None:
     assert details is not None
     assert details["input_token_count"] == 200
     assert details["openai.cached_input_tokens"] == 25
+    assert details["cache_read_input_token_count"] == 25
 
 
 def test_usage_details_with_reasoning_tokens() -> None:
@@ -3319,6 +3320,49 @@ def test_usage_details_with_reasoning_tokens() -> None:
     assert details is not None
     assert details["output_token_count"] == 80
     assert details["openai.reasoning_tokens"] == 30
+    assert details["reasoning_output_token_count"] == 30
+
+
+def test_usage_details_with_zero_cached_and_reasoning_tokens() -> None:
+    """Test _parse_usage_from_openai preserves zero-valued mapped usage details."""
+    client = OpenAIChatClient(model="test-model", api_key="test-key")
+
+    mock_usage = MagicMock()
+    mock_usage.input_tokens = 150
+    mock_usage.output_tokens = 80
+    mock_usage.total_tokens = 230
+    mock_usage.input_tokens_details = MagicMock()
+    mock_usage.input_tokens_details.cached_tokens = 0
+    mock_usage.output_tokens_details = MagicMock()
+    mock_usage.output_tokens_details.reasoning_tokens = 0
+
+    details = client._parse_usage_from_openai(mock_usage)  # type: ignore
+    assert details is not None
+    assert details["openai.cached_input_tokens"] == 0
+    assert details["cache_read_input_token_count"] == 0
+    assert details["openai.reasoning_tokens"] == 0
+    assert details["reasoning_output_token_count"] == 0
+
+
+def test_usage_details_omits_missing_cached_and_reasoning_tokens() -> None:
+    """Test _parse_usage_from_openai omits missing mapped usage details."""
+    client = OpenAIChatClient(model="test-model", api_key="test-key")
+
+    mock_usage = MagicMock()
+    mock_usage.input_tokens = 150
+    mock_usage.output_tokens = 80
+    mock_usage.total_tokens = 230
+    mock_usage.input_tokens_details = MagicMock()
+    mock_usage.input_tokens_details.cached_tokens = None
+    mock_usage.output_tokens_details = MagicMock()
+    mock_usage.output_tokens_details.reasoning_tokens = None
+
+    details = client._parse_usage_from_openai(mock_usage)  # type: ignore
+    assert details is not None
+    assert "openai.cached_input_tokens" not in details
+    assert "cache_read_input_token_count" not in details
+    assert "openai.reasoning_tokens" not in details
+    assert "reasoning_output_token_count" not in details
 
 
 def test_get_metadata_from_response() -> None:

python/packages/openai/tests/openai/test_openai_chat_completion_client.py

@@ -1099,6 +1099,31 @@ def test_usage_content_in_streaming_response(
     assert usage_content.usage_details["total_token_count"] == 150
 
 
+def test_parse_usage_includes_standard_and_legacy_mapped_token_details() -> None:
+    """Test _parse_usage_from_openai emits standard and legacy mapped token details."""
+    client = OpenAIChatCompletionClient(model="test-model", api_key="test-key")
+
+    mock_usage = MagicMock()
+    mock_usage.prompt_tokens = 100
+    mock_usage.completion_tokens = 50
+    mock_usage.total_tokens = 150
+    mock_usage.completion_tokens_details = MagicMock()
+    mock_usage.completion_tokens_details.accepted_prediction_tokens = None
+    mock_usage.completion_tokens_details.audio_tokens = None
+    mock_usage.completion_tokens_details.reasoning_tokens = 0
+    mock_usage.completion_tokens_details.rejected_prediction_tokens = None
+    mock_usage.prompt_tokens_details = MagicMock()
+    mock_usage.prompt_tokens_details.audio_tokens = None
+    mock_usage.prompt_tokens_details.cached_tokens = 0
+
+    details = client._parse_usage_from_openai(mock_usage)  # type: ignore[arg-type]
+
+    assert details["completion/reasoning_tokens"] == 0
+    assert details["reasoning_output_token_count"] == 0
+    assert details["prompt/cached_tokens"] == 0
+    assert details["cache_read_input_token_count"] == 0
+
+
 def test_streaming_chunk_with_usage_and_text(
     openai_unit_test_env: dict[str, str],
 ) -> None: