opentelementry-instrumentation-google-genai: add gen_ai.tool.definitions to experimental semconv (#4142)

* opentelementry-instrumentation-google-genai: add gen_ai.tool.definitions to experimental semconv

* Add _to_tool_definition

* Remove unused import

* Add GEN_AI_TOOL_DEFINITIONS to tests.

* Remove uneccesary space.

* address comments: add exclude_none to model_dump and tool type to error message

* address comment: add if/else statement on tool types and add tests for each tool

* dont serilize mcp client sessions in case of synchronous methods

* Refactor _to_tool_definition_common to be more clear

* remove uncessary 'function' key

* fix failing tests: make mcp import conditional

* Update changelog

* Update uv.lock

* address comment: remove undecessary typing.Type

* address comment: make mcp import conditional

Author: wikaaaaa

instrumentation-genai/opentelemetry-instrumentation-google-genai/CHANGELOG.md

@@ -8,6 +8,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## Unreleased
 - Fix bug in how tokens are counted when using the streaming `generateContent` method.  ([#4152](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/4152)).
 
+## Version 0.7b0 (2026-02-03)
+
+- Add `gen_ai.tool.definitions` attribute to `gen_ai.client.inference.operation.details` log event ([#4142](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/4142)).
+
 ## Version 0.6b0 (2026-01-27)
 
 - Enable the addition of custom attributes to the `generate_content {model.name}` span via the Context API. ([#3961](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/3961)).

instrumentation-genai/opentelemetry-instrumentation-google-genai/src/opentelemetry/instrumentation/google_genai/generate_content.py

@@ -20,6 +20,7 @@
 import logging
 import os
 import time
+import typing
 from typing import (
     Any,
     AsyncIterator,
@@ -42,6 +43,9 @@
     GenerateContentConfig,
     GenerateContentConfigOrDict,
     GenerateContentResponse,
+    Tool,
+    ToolListUnionDict,
+    ToolUnionDict,
 )
 
 from opentelemetry import context as context_api
@@ -82,8 +86,27 @@
 from .otel_wrapper import OTelWrapper
 from .tool_call_wrapper import wrapped as wrapped_tool
 
+_is_mcp_imported = False
+if typing.TYPE_CHECKING:
+    from mcp import ClientSession as McpClientSession
+    from mcp import Tool as McpTool
+
+    is_mcp_imported = True
+else:
+    try:
+        from mcp import ClientSession as McpClientSession
+        from mcp import Tool as McpTool
+
+        _is_mcp_imported = True
+    except ImportError:
+        McpClientSession = None
+        McpTool = None
+
 _logger = logging.getLogger(__name__)
 
+GEN_AI_TOOL_DEFINITIONS = getattr(
+    gen_ai_attributes, "GEN_AI_TOOL_DEFINITIONS", "gen_ai.tool.definitions"
+)
 
 # Constant used to make the absence of content more understandable.
 _CONTENT_ELIDED = "<elided>"
@@ -185,6 +208,68 @@ def _to_dict(value: object):
     return json.loads(json.dumps(value))
 
 
+def _tool_to_tool_definition(tool: ToolUnionDict) -> MessagePart:
+    if hasattr(tool, "model_dump"):
+        return tool.model_dump(exclude_none=True)
+
+    return str(tool)
+
+
+def _callable_tool_to_tool_definition(tool: Any) -> MessagePart:
+    doc = getattr(tool, "__doc__", "") or ""
+    return {
+        "name": getattr(tool, "__name__", type(tool).__name__),
+        "description": doc.strip(),
+    }
+
+
+def _mcp_tool_to_tool_definition(tool: McpTool) -> MessagePart:
+    if hasattr(tool, "model_dump"):
+        return tool.model_dump(exclude_none=True)
+
+    return {
+        "name": getattr(tool, "name", type(tool).__name__),
+        "description": getattr(tool, "description", "") or "",
+        "input_schema": getattr(tool, "input_schema", {}),
+    }
+
+
+def _to_tool_definition_common(tool: ToolUnionDict) -> MessagePart:
+    if isinstance(tool, dict):
+        return tool
+
+    if isinstance(tool, Tool):
+        return _tool_to_tool_definition(tool)
+
+    if callable(tool):
+        return _callable_tool_to_tool_definition(tool)
+
+    if _is_mcp_imported and isinstance(tool, McpTool):
+        return _mcp_tool_to_tool_definition(tool)
+
+    try:
+        return {"raw_definition": json.loads(json.dumps(tool))}
+    except Exception:  # pylint: disable=broad-exception-caught
+        return {
+            "error": f"failed to serialize tool definition, tool type={type(tool).__name__}"
+        }
+
+
+def _to_tool_definition(tool: ToolUnionDict) -> MessagePart:
+    if _is_mcp_imported and isinstance(tool, McpClientSession):
+        return None
+
+    return _to_tool_definition_common(tool)
+
+
+async def _to_tool_definition_async(tool: ToolUnionDict) -> MessagePart:
+    if _is_mcp_imported and isinstance(tool, McpClientSession):
+        result = await tool.list_tools()
+        return [t.model_dump(exclude_none=True) for t in result.tools]
+
+    return _to_tool_definition_common(tool)
+
+
 def _create_request_attributes(
     config: Optional[GenerateContentConfigOrDict],
     allow_list: AllowList,
@@ -285,10 +370,22 @@ def _config_to_system_instruction(
     return config.system_instruction
 
 
+def _config_to_tools(
+    config: Union[GenerateContentConfigOrDict, None],
+) -> Union[ToolListUnionDict, None]:
+    if not config:
+        return None
+
+    if isinstance(config, dict):
+        return GenerateContentConfig.model_validate(config).tools
+    return config.tools
+
+
 def _create_completion_details_attributes(
     input_messages: list[InputMessage],
     output_messages: list[OutputMessage],
     system_instructions: list[MessagePart],
+    tool_definitions: list[MessagePart],
     as_str: bool = False,
 ) -> dict[str, AttributeValue]:
     attributes: dict[str, AttributeValue] = {
@@ -306,6 +403,9 @@ def _create_completion_details_attributes(
             dataclasses.asdict(sys_instr) for sys_instr in system_instructions
         ]
 
+    if tool_definitions:
+        attributes[GEN_AI_TOOL_DEFINITIONS] = tool_definitions
+
     return attributes
 
 
@@ -324,6 +424,7 @@ def __init__(
         model: str,
         completion_hook: CompletionHook,
         generate_content_config_key_allowlist: Optional[AllowList] = None,
+        is_async: bool = False,
     ):
         self._start_time = time.time_ns()
         self._otel_wrapper = otel_wrapper
@@ -345,6 +446,7 @@ def __init__(
         self._generate_content_config_key_allowlist = (
             generate_content_config_key_allowlist or AllowList()
         )
+        self._is_async = is_async
 
     def wrapped_config(
         self, config: Optional[GenerateContentConfigOrDict]
@@ -461,6 +563,44 @@ def _maybe_update_error_type(self, response: GenerateContentResponse):
         block_reason = response.prompt_feedback.block_reason.name.upper()
         self._error_type = f"BLOCKED_{block_reason}"
 
+    def _maybe_get_tool_definitions(self, config):
+        if (
+            self.sem_conv_opt_in_mode
+            != _StabilityMode.GEN_AI_LATEST_EXPERIMENTAL
+        ):
+            return None
+
+        tool_definitions = []
+        if tools := _config_to_tools(config):
+            for tool in tools:
+                definition = _to_tool_definition(tool)
+                if definition is None:
+                    continue
+                if isinstance(definition, list):
+                    tool_definitions.extend(definition)
+                else:
+                    tool_definitions.append(definition)
+        return tool_definitions
+
+    async def _maybe_get_tool_definitions_async(self, config):
+        if (
+            self.sem_conv_opt_in_mode
+            != _StabilityMode.GEN_AI_LATEST_EXPERIMENTAL
+        ):
+            return None
+
+        tool_definitions = []
+        if tools := _config_to_tools(config):
+            for tool in tools:
+                definition = await _to_tool_definition_async(tool)
+                if definition is None:
+                    continue
+                if isinstance(definition, list):
+                    tool_definitions.extend(definition)
+                else:
+                    tool_definitions.append(definition)
+        return tool_definitions
+
     def _maybe_log_completion_details(
         self,
         extra_attributes: dict[str, AttributeValue],
@@ -469,6 +609,7 @@ def _maybe_log_completion_details(
         request: Union[ContentListUnion, ContentListUnionDict],
         candidates: list[Candidate],
         config: Optional[GenerateContentConfigOrDict] = None,
+        tool_definitions: list[MessagePart] = None,
     ):
         if (
             self.sem_conv_opt_in_mode
@@ -503,6 +644,7 @@ def _maybe_log_completion_details(
             input_messages,
             output_messages,
             system_instructions,
+            tool_definitions,
         )
         if self._content_recording_enabled in [
             ContentCapturingMode.EVENT_ONLY,
@@ -737,6 +879,7 @@ def instrumented_generate_content(
             model,
             completion_hook,
             generate_content_config_key_allowlist=generate_content_config_key_allowlist,
+            is_async=False,
         )
         request_attributes = _create_request_attributes(
             config,
@@ -774,13 +917,17 @@ def instrumented_generate_content(
             finally:
                 final_attributes = helper.create_final_attributes()
                 span.set_attributes(final_attributes)
+                maybe_tool_definitions = helper._maybe_get_tool_definitions(
+                    config
+                )
                 helper._maybe_log_completion_details(
                     extra_attributes,
                     request_attributes,
                     final_attributes,
                     contents,
                     candidates,
                     config,
+                    maybe_tool_definitions,
                 )
                 helper._record_token_usage_metric()
                 helper._record_duration_metric()
@@ -812,6 +959,7 @@ def instrumented_generate_content_stream(
             model,
             completion_hook,
             generate_content_config_key_allowlist=generate_content_config_key_allowlist,
+            is_async=False,
         )
         request_attributes = _create_request_attributes(
             config,
@@ -849,13 +997,17 @@ def instrumented_generate_content_stream(
             finally:
                 final_attributes = helper.create_final_attributes()
                 span.set_attributes(final_attributes)
+                maybe_tool_definitions = helper._maybe_get_tool_definitions(
+                    config
+                )
                 helper._maybe_log_completion_details(
                     extra_attributes,
                     request_attributes,
                     final_attributes,
                     contents,
                     candidates,
                     config,
+                    maybe_tool_definitions,
                 )
                 helper._record_token_usage_metric()
                 helper._record_duration_metric()
@@ -886,6 +1038,7 @@ async def instrumented_generate_content(
             model,
             completion_hook,
             generate_content_config_key_allowlist=generate_content_config_key_allowlist,
+            is_async=True,
         )
         request_attributes = _create_request_attributes(
             config,
@@ -923,13 +1076,17 @@ async def instrumented_generate_content(
             finally:
                 final_attributes = helper.create_final_attributes()
                 span.set_attributes(final_attributes)
+                maybe_tool_definitions = (
+                    await helper._maybe_get_tool_definitions_async(config)
+                )
                 helper._maybe_log_completion_details(
                     extra_attributes,
                     request_attributes,
                     final_attributes,
                     contents,
                     candidates,
                     config,
+                    maybe_tool_definitions,
                 )
                 helper._record_token_usage_metric()
                 helper._record_duration_metric()
@@ -961,6 +1118,7 @@ async def instrumented_generate_content_stream(
             model,
             completion_hook,
             generate_content_config_key_allowlist=generate_content_config_key_allowlist,
+            is_async=True,
         )
         request_attributes = _create_request_attributes(
             config,
@@ -991,13 +1149,17 @@ async def instrumented_generate_content_stream(
                 helper._record_token_usage_metric()
                 final_attributes = helper.create_final_attributes()
                 span.set_attributes(final_attributes)
+                maybe_tool_definitions = (
+                    await helper._maybe_get_tool_definitions_async(config)
+                )
                 helper._maybe_log_completion_details(
                     extra_attributes,
                     request_attributes,
                     final_attributes,
                     contents,
                     [],
                     config,
+                    maybe_tool_definitions,
                 )
                 helper._record_duration_metric()
                 with trace.use_span(span, end_on_exit=True):
@@ -1025,13 +1187,19 @@ async def _response_async_generator_wrapper():
                     finally:
                         final_attributes = helper.create_final_attributes()
                         span.set_attributes(final_attributes)
+                        maybe_tool_definitions = (
+                            await helper._maybe_get_tool_definitions_async(
+                                config
+                            )
+                        )
                         helper._maybe_log_completion_details(
                             extra_attributes,
                             request_attributes,
                             final_attributes,
                             contents,
                             candidates,
                             config,
+                            maybe_tool_definitions,
                         )
                         helper._record_token_usage_metric()
                         helper._record_duration_metric()