feat(telemetry): capture tool execution errors in OpenTelemetry spans

Introduces ToolExecutionError and ToolErrorType (HTTP status codes) to standardize error reporting for tool failures. Updates trace_tool_call and function execution handlers to extract and record error.type semantics.

Author: Achuth17

tests/unittests/telemetry/test_spans.py

@@ -812,6 +812,359 @@ async def test_generate_content_span(
   assert choice_log.attributes == {GEN_AI_SYSTEM: 'test_system'}
 
 
+def _mock_callable_tool():
+  """Description of some tool."""
+  return 'result'
+
+
+def _mock_mcp_client_session() -> McpClientSession:
+  mock_session = mock.create_autospec(spec=McpClientSession, instance=True)
+
+  mock_tool_obj = McpTool(
+      name='mcp_tool',
+      description='Tool from session',
+      inputSchema={
+          'type': 'object',
+          'properties': {'query': {'type': 'string'}},
+      },
+  )
+  mock_result = mock.create_autospec(McpListToolsResult, instance=True)
+  mock_result.tools = [mock_tool_obj]
+
+  mock_session.list_tools = mock.AsyncMock(return_value=mock_result)
+
+  return mock_session
+
+
+def _mock_mcp_tool():
+  return McpTool(
+      name='mcp_tool',
+      description='A standalone mcp tool',
+      inputSchema={
+          'type': 'object',
+          'properties': {'id': {'type': 'integer'}},
+      },
+  )
+
+
+def _mock_tool_dict() -> types.ToolDict:
+  return types.ToolDict(
+      function_declarations=[
+          types.FunctionDeclarationDict(
+              name='mock_tool', description='Description of mock tool.'
+          ),
+      ],
+      google_maps=types.GoogleMaps(),
+  )
+
+
+@pytest.mark.asyncio
+@mock.patch('google.adk.telemetry.tracing.otel_logger')
+@mock.patch('google.adk.telemetry.tracing.tracer')
+@mock.patch(
+    'google.adk.telemetry.tracing._guess_gemini_system_name',
+    return_value='test_system',
+)
+@pytest.mark.parametrize(
+    'capture_content',
+    ['SPAN_AND_EVENT', 'EVENT_ONLY', 'SPAN_ONLY', 'NO_CONTENT'],
+)
+async def test_generate_content_span_with_experimental_semconv(
+    mock_guess_system_name,
+    mock_tracer,
+    mock_otel_logger,
+    monkeypatch,
+    capture_content,
+):
+  """Test native generate_content span creation with attributes and logs with experimental semconv enabled."""
+  # Arrange
+  monkeypatch.setenv(
+      'OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT',
+      str(capture_content).lower(),
+  )
+  monkeypatch.setenv(
+      'OTEL_SEMCONV_STABILITY_OPT_IN',
+      'gen_ai_latest_experimental',
+  )
+  monkeypatch.setattr(
+      'google.adk.telemetry.tracing._instrumented_with_opentelemetry_instrumentation_google_genai',
+      lambda: False,
+  )
+
+  agent = LlmAgent(name='test_agent', model='not-a-gemini-model')
+  invocation_context = await _create_invocation_context(agent)
+
+  system_instruction = types.Content(
+      parts=[types.Part.from_text(text='You are a helpful assistant.')],
+  )
+
+  user_content1 = types.Content(role='user', parts=[types.Part(text='Hello')])
+  user_content2 = types.Content(role='user', parts=[types.Part(text='World')])
+
+  model_content = types.Content(
+      role='model', parts=[types.Part(text='Response')]
+  )
+
+  tools = [
+      _mock_callable_tool,
+      _mock_tool_dict(),
+      _mock_mcp_client_session(),
+      _mock_mcp_tool(),
+  ]
+
+  llm_request = LlmRequest(
+      model='some-model',
+      contents=[user_content1, user_content2],
+      config=types.GenerateContentConfig(
+          system_instruction=system_instruction, tools=tools
+      ),
+  )
+  llm_response = LlmResponse(
+      content=model_content,
+      finish_reason=types.FinishReason.STOP,
+      usage_metadata=types.GenerateContentResponseUsageMetadata(
+          prompt_token_count=10,
+          candidates_token_count=20,
+      ),
+  )
+
+  model_response_event = mock.MagicMock()
+  model_response_event.id = 'event-123'
+
+  mock_span = (
+      mock_tracer.start_as_current_span.return_value.__enter__.return_value
+  )
+
+  # Act
+  async with use_inference_span(
+      llm_request,
+      invocation_context,
+      model_response_event,
+  ) as gc_span:
+    assert gc_span.span is mock_span
+
+    trace_inference_result(gc_span, llm_response)
+
+  # Expected attributes
+  expected_system_instructions = [
+      {
+          'content': 'You are a helpful assistant.',
+          'type': 'text',
+      },
+  ]
+  expected_input_messages = [
+      {
+          'role': 'user',
+          'parts': [
+              {'content': 'Hello', 'type': 'text'},
+          ],
+      },
+      {
+          'role': 'user',
+          'parts': [
+              {'content': 'World', 'type': 'text'},
+          ],
+      },
+  ]
+  expected_output_messages = [{
+      'role': 'assistant',
+      'parts': [
+          {'content': 'Response', 'type': 'text'},
+      ],
+      'finish_reason': 'stop',
+  }]
+  expected_tool_definitions = [
+      {
+          'name': '_mock_callable_tool',
+          'description': 'Description of some tool.',
+          'parameters': None,
+          'type': 'function',
+      },
+      {
+          'name': 'mock_tool',
+          'description': 'Description of mock tool.',
+          'parameters': None,
+          'type': 'function',
+      },
+      {
+          'name': 'google_maps',
+          'type': 'google_maps',
+      },
+      {
+          'name': 'mcp_tool',
+          'description': 'Tool from session',
+          'parameters': {
+              'type': 'object',
+              'properties': {'query': {'type': 'string'}},
+          },
+          'type': 'function',
+      },
+      {
+          'name': 'mcp_tool',
+          'description': 'A standalone mcp tool',
+          'parameters': {
+              'type': 'object',
+              'properties': {'id': {'type': 'integer'}},
+          },
+          'type': 'function',
+      },
+  ]
+  expected_tool_definitions_no_content = [
+      {
+          'name': '_mock_callable_tool',
+          'description': 'Description of some tool.',
+          'parameters': None,
+          'type': 'function',
+      },
+      {
+          'name': 'mock_tool',
+          'description': 'Description of mock tool.',
+          'parameters': None,
+          'type': 'function',
+      },
+      {
+          'name': 'google_maps',
+          'type': 'google_maps',
+      },
+      {
+          'name': 'mcp_tool',
+          'description': 'Tool from session',
+          'parameters': None,
+          'type': 'function',
+      },
+      {
+          'name': 'mcp_tool',
+          'description': 'A standalone mcp tool',
+          'parameters': None,
+          'type': 'function',
+      },
+  ]
+  expected_tool_definitions_json = (
+      '[{"name":"_mock_callable_tool","description":"Description of some'
+      ' tool.","parameters":null,"type":"function"},{"name":"mock_tool","description":"Description'
+      ' of mock'
+      ' tool.","parameters":null,"type":"function"},{"name":"google_maps","type":"google_maps"},{"name":"mcp_tool","description":"Tool'
+      ' from'
+      ' session","parameters":{"type":"object","properties":{"query":{"type":"string"}}},"type":"function"},{"name":"mcp_tool","description":"A'
+      ' standalone mcp'
+      ' tool","parameters":{"type":"object","properties":{"id":{"type":"integer"}}},"type":"function"}]'
+  )
+
+  expected_tool_definitions_no_content_json = (
+      '[{"name":"_mock_callable_tool","description":"Description of some'
+      ' tool.","parameters":null,"type":"function"},{"name":"mock_tool","description":"Description'
+      ' of mock'
+      ' tool.","parameters":null,"type":"function"},{"name":"google_maps","type":"google_maps"},{"name":"mcp_tool","description":"Tool'
+      ' from'
+      ' session","parameters":null,"type":"function"},{"name":"mcp_tool","description":"A'
+      ' standalone mcp tool","parameters":null,"type":"function"}]'
+  )
+  # Assert Span
+  mock_tracer.start_as_current_span.assert_called_once_with(
+      'generate_content some-model'
+  )
+
+  mock_span.set_attribute.assert_any_call(
+      GEN_AI_OPERATION_NAME, 'generate_content'
+  )
+  mock_span.set_attribute.assert_any_call(GEN_AI_REQUEST_MODEL, 'some-model')
+  mock_span.set_attribute.assert_any_call(
+      GEN_AI_RESPONSE_FINISH_REASONS, ['stop']
+  )
+  mock_span.set_attribute.assert_any_call(GEN_AI_USAGE_INPUT_TOKENS, 10)
+  mock_span.set_attribute.assert_any_call(GEN_AI_USAGE_OUTPUT_TOKENS, 20)
+
+  mock_span.set_attributes.assert_called_once_with({
+      GEN_AI_AGENT_NAME: invocation_context.agent.name,
+      GEN_AI_CONVERSATION_ID: invocation_context.session.id,
+      USER_ID: invocation_context.session.user_id,
+      'gcp.vertex.agent.event_id': 'event-123',
+      'gcp.vertex.agent.invocation_id': invocation_context.invocation_id,
+  })
+
+  if capture_content in ['SPAN_AND_EVENT', 'SPAN_ONLY']:
+    mock_span.set_attribute.assert_any_call(
+        GEN_AI_SYSTEM_INSTRUCTIONS,
+        '[{"content":"You are a helpful assistant.","type":"text"}]',
+    )
+    mock_span.set_attribute.assert_any_call(
+        GEN_AI_INPUT_MESSAGES,
+        '[{"role":"user","parts":[{"content":"Hello","type":"text"}]},{"role":"user","parts":[{"content":"World","type":"text"}]}]',
+    )
+    mock_span.set_attribute.assert_any_call(
+        GEN_AI_OUTPUT_MESSAGES,
+        '[{"role":"assistant","parts":[{"content":"Response","type":"text"}],"finish_reason":"stop"}]',
+    )
+    mock_span.set_attribute.assert_any_call(
+        GEN_AI_TOOL_DEFINITIONS, expected_tool_definitions_json
+    )
+  else:
+    all_attribute_calls = mock_span.set_attribute.call_args_list
+    assert GEN_AI_SYSTEM_INSTRUCTIONS not in all_attribute_calls
+    assert GEN_AI_INPUT_MESSAGES not in all_attribute_calls
+    assert GEN_AI_OUTPUT_MESSAGES not in all_attribute_calls
+    mock_span.set_attribute.assert_any_call(
+        GEN_AI_TOOL_DEFINITIONS, expected_tool_definitions_no_content_json
+    )
+
+  # Assert Logs
+  assert mock_otel_logger.emit.call_count == 1
+
+  log_records: list[LogRecord] = [
+      call.args[0] for call in mock_otel_logger.emit.call_args_list
+  ]
+
+  operation_details_log = next(
+      (
+          lr
+          for lr in log_records
+          if lr.event_name == 'gen_ai.client.inference.operation.details'
+      ),
+      None,
+  )
+
+  assert operation_details_log is not None
+  assert operation_details_log.attributes is not None
+
+  attributes = operation_details_log.attributes
+
+  if capture_content in ['SPAN_AND_EVENT', 'EVENT_ONLY']:
+    assert GEN_AI_SYSTEM_INSTRUCTIONS in attributes
+    assert (
+        attributes[GEN_AI_SYSTEM_INSTRUCTIONS] == expected_system_instructions
+    )
+    assert GEN_AI_INPUT_MESSAGES in attributes
+    assert attributes[GEN_AI_INPUT_MESSAGES] == expected_input_messages
+    assert GEN_AI_OUTPUT_MESSAGES in attributes
+    assert attributes[GEN_AI_OUTPUT_MESSAGES] == expected_output_messages
+    assert GEN_AI_TOOL_DEFINITIONS in attributes
+    assert attributes[GEN_AI_TOOL_DEFINITIONS] == expected_tool_definitions
+  else:
+    assert GEN_AI_SYSTEM_INSTRUCTIONS not in attributes
+    assert GEN_AI_INPUT_MESSAGES not in attributes
+    assert GEN_AI_OUTPUT_MESSAGES not in attributes
+    assert GEN_AI_TOOL_DEFINITIONS in attributes
+    assert (
+        attributes[GEN_AI_TOOL_DEFINITIONS]
+        == expected_tool_definitions_no_content
+    )
+
+  assert GEN_AI_USAGE_INPUT_TOKENS in attributes
+  assert attributes[GEN_AI_USAGE_INPUT_TOKENS] == 10
+  assert GEN_AI_USAGE_OUTPUT_TOKENS in attributes
+  assert attributes[GEN_AI_USAGE_OUTPUT_TOKENS] == 20
+  assert 'gcp.vertex.agent.event_id' in attributes
+  assert attributes['gcp.vertex.agent.event_id'] == 'event-123'
+  assert 'gcp.vertex.agent.invocation_id' in attributes
+  assert (
+      attributes['gcp.vertex.agent.invocation_id']
+      == invocation_context.invocation_id
+  )
+  assert GEN_AI_AGENT_NAME in attributes
+  assert attributes[GEN_AI_AGENT_NAME] == invocation_context.agent.name
+  assert GEN_AI_CONVERSATION_ID in attributes
+  assert attributes[GEN_AI_CONVERSATION_ID] == invocation_context.session.id
+
 def test_trace_tool_call_with_tool_execution_error(
     monkeypatch, mock_span_fixture, mock_tool_fixture
 ):
@@ -890,5 +1243,4 @@ def test_trace_tool_call_with_standard_error(
       error=test_error,
   )
 
-  assert mock.call('error.type', 'ValueError') in mock_span_fixture.set_attribute.call_args_list
-
+  assert mock.call('error.type', 'ValueError') in mock_span_fixture.set_attribute.call_args_list