feat: add span handler for toolcall

Author: keith-decker

util/opentelemetry-util-genai/src/opentelemetry/util/genai/handler.py

@@ -17,21 +17,17 @@
 
 This module exposes the `TelemetryHandler` class, which manages the lifecycle of
 GenAI (Generative AI) invocations and emits telemetry data (spans and related attributes).
-It supports starting, stopping, and failing LLM invocations.
+It supports starting, stopping, and failing LLM invocations and tool call executions.
 
 Classes:
     - TelemetryHandler: Manages GenAI invocation lifecycles and emits telemetry.
 
 Functions:
     - get_telemetry_handler: Returns a singleton `TelemetryHandler` instance.
 
-Usage:
+Usage - LLM Invocations:
     handler = get_telemetry_handler()
 
-    # Create an invocation object with your request data
-    # The span and context_token attributes are set by the TelemetryHandler, and
-    # managed by the TelemetryHandler during the lifecycle of the span.
-
     # Use the context manager to manage the lifecycle of an LLM invocation.
     with handler.llm(invocation) as invocation:
         # Populate outputs and any additional attributes
@@ -45,17 +41,24 @@
         provider="my-provider",
         attributes={"custom": "attr"},
     )
-
-    # Start the invocation (opens a span)
     handler.start_llm(invocation)
-
-    # Populate outputs and any additional attributes, then stop (closes the span)
     invocation.output_messages = [...]
-    invocation.attributes.update({"more": "attrs"})
     handler.stop_llm(invocation)
 
-    # Or, in case of error
-    handler.fail_llm(invocation, Error(type="...", message="..."))
+Usage - Tool Call Executions:
+    handler = get_telemetry_handler()
+
+    # Use the context manager to manage the lifecycle of a tool call.
+    tool = ToolCall(name="get_weather", arguments={"location": "Paris"}, id="call_123")
+    with handler.tool_call(tool) as tc:
+        # Execute tool logic
+        tc.tool_result = {"temp": 20, "condition": "sunny"}
+
+    # Or, manage the lifecycle manually
+    tool = ToolCall(name="get_weather", arguments={"location": "Paris"})
+    handler.start_tool_call(tool)
+    tool.tool_result = {"temp": 20}
+    handler.stop_tool_call(tool)
 """
 
 from __future__ import annotations
@@ -78,13 +81,17 @@
     get_tracer,
     set_span_in_context,
 )
+from opentelemetry.trace.status import Status, StatusCode
 from opentelemetry.util.genai.metrics import InvocationMetricsRecorder
 from opentelemetry.util.genai.span_utils import (
     _apply_error_attributes,
     _apply_llm_finish_attributes,
+    _apply_tool_call_attributes,
+    _finish_tool_call_span,
+    _get_tool_call_span_name,
     _maybe_emit_llm_event,
 )
-from opentelemetry.util.genai.types import Error, LLMInvocation
+from opentelemetry.util.genai.types import Error, LLMInvocation, ToolCall
 from opentelemetry.util.genai.version import __version__
 
 
@@ -187,6 +194,138 @@ def fail_llm(  # pylint: disable=no-self-use
         span.end()
         return invocation
 
+    def start_tool_call(
+        self,
+        tool_call: ToolCall,
+    ) -> ToolCall:
+        """Start a tool call execution and create a span.
+
+        Creates an execute_tool span per span.gen_ai.execute_tool.internal spec:
+        - Span kind: INTERNAL
+        - Span name: "execute_tool {tool_name}"
+        - Required attribute: gen_ai.operation.name = "execute_tool"
+
+        Args:
+            tool_call: ToolCall instance to track
+
+        Returns:
+            The same ToolCall with span and context_token set
+        """
+        # Create span with INTERNAL kind per spec
+        span = self._tracer.start_span(
+            name=_get_tool_call_span_name(tool_call),
+            kind=SpanKind.INTERNAL,
+        )
+
+        # Apply initial attributes (but not result yet)
+        # capture_content=False for start, only structure attributes
+        _apply_tool_call_attributes(span, tool_call, capture_content=False)
+
+        # Record monotonic start time for duration calculation
+        tool_call.monotonic_start_s = timeit.default_timer()
+
+        # Attach to context
+        tool_call.span = span
+        tool_call.context_token = otel_context.attach(
+            set_span_in_context(span)
+        )
+
+        return tool_call
+
+    def stop_tool_call(self, tool_call: ToolCall) -> ToolCall:  # pylint: disable=no-self-use
+        """Finalize a tool call execution successfully.
+
+        Applies final attributes including tool_result, sets OK status, and ends span.
+
+        Args:
+            tool_call: ToolCall instance with span to finalize
+
+        Returns:
+            The same ToolCall
+        """
+        if tool_call.context_token is None or tool_call.span is None:
+            # TODO: Provide feedback that this invocation was not started
+            return tool_call
+
+        span = tool_call.span
+
+        # Finalize span with result (capture_content=True allows result if mode permits)
+        _finish_tool_call_span(span, tool_call, capture_content=True)
+
+        # Detach context and end span
+        otel_context.detach(tool_call.context_token)
+        span.end()
+
+        return tool_call
+
+    def fail_tool_call(  # pylint: disable=no-self-use
+        self, tool_call: ToolCall, error: Error
+    ) -> ToolCall:
+        """Fail a tool call execution with error.
+
+        Sets error attributes, ERROR status, and ends span.
+
+        Args:
+            tool_call: ToolCall instance with span to fail
+            error: Error details
+
+        Returns:
+            The same ToolCall
+        """
+        if tool_call.context_token is None or tool_call.span is None:
+            # TODO: Provide feedback that this invocation was not started
+            return tool_call
+
+        span = tool_call.span
+
+        # Set error_type on tool_call so it's included in attributes
+        tool_call.error_type = error.type.__qualname__
+
+        # Finalize span with error
+        _finish_tool_call_span(span, tool_call, capture_content=True)
+
+        # Apply additional error status with message
+        span.set_status(Status(StatusCode.ERROR, error.message))
+
+        # Detach context and end span
+        otel_context.detach(tool_call.context_token)
+        span.end()
+
+        return tool_call
+
+    @contextmanager
+    def tool_call(
+        self, tool_call: ToolCall | None = None
+    ) -> Iterator[ToolCall]:
+        """Context manager for tool call invocations.
+
+        Only set data attributes on the tool_call object, do not modify the span or context.
+
+        Starts the span on entry. On normal exit, finalizes the tool call and ends the span.
+        If an exception occurs inside the context, marks the span as error, ends it, and
+        re-raises the original exception.
+
+        Example:
+            with handler.tool_call(ToolCall(name="get_weather", arguments={"location": "Paris"})) as tc:
+                # Execute tool logic
+                tc.tool_result = {"temp": 20, "condition": "sunny"}
+        """
+        if tool_call is None:
+            tool_call = ToolCall(
+                name="",
+                arguments={},
+                id=None,
+            )
+        self.start_tool_call(tool_call)
+        try:
+            yield tool_call
+        except Exception as exc:
+            self.fail_tool_call(
+                tool_call, Error(message=str(exc), type=type(exc))
+            )
+            raise
+        self.stop_tool_call(tool_call)
+
     @contextmanager
     def llm(
         self, invocation: LLMInvocation | None = None

util/opentelemetry-util-genai/src/opentelemetry/util/genai/span_utils.py

@@ -37,6 +37,7 @@
     LLMInvocation,
     MessagePart,
     OutputMessage,
+    ToolCall,
 )
 from opentelemetry.util.genai.utils import (
     ContentCapturingMode,
@@ -279,6 +280,106 @@ def _get_llm_response_attributes(
     return {key: value for key, value in optional_attrs if value is not None}
 
 
+def _get_tool_call_span_name(tool_call: ToolCall) -> str:
+    """Get span name for tool call execution per semantic convention.
+
+    Format: "execute_tool {gen_ai.tool.name}"
+    """
+    return f"execute_tool {tool_call.name}".strip()
+
+
+def _apply_tool_call_attributes(
+    span: Span,
+    tool_call: ToolCall,
+    capture_content: bool = False,
+) -> None:
+    """Apply semantic convention attributes from ToolCall to span.
+
+    Follows span.gen_ai.execute_tool.internal specification from:
+    https://github.com/open-telemetry/semantic-conventions/blob/main/docs/gen-ai/gen-ai-spans.md#execute-tool-span
+
+    Required attributes:
+    - gen_ai.operation.name = "execute_tool"
+
+    Recommended attributes (if available):
+    - gen_ai.tool.name
+    - gen_ai.tool.call.id
+    - gen_ai.tool.type
+    - gen_ai.tool.description
+
+    Opt-In attributes (only if capture_content=True and experimental mode):
+    - gen_ai.tool.call.arguments (sensitive data)
+    - gen_ai.tool.call.result (sensitive data)
+
+    Conditionally required:
+    - error.type (if operation ended in error)
+    """
+    # Set REQUIRED attribute
+    span.set_attribute(GenAI.GEN_AI_OPERATION_NAME, "execute_tool")
+
+    # Set RECOMMENDED attributes (if present)
+    if tool_call.name:
+        span.set_attribute(GenAI.GEN_AI_TOOL_NAME, tool_call.name)
+
+    if tool_call.id:
+        span.set_attribute(GenAI.GEN_AI_TOOL_CALL_ID, tool_call.id)
+
+    if tool_call.tool_type:
+        span.set_attribute(GenAI.GEN_AI_TOOL_TYPE, tool_call.tool_type)
+
+    if tool_call.tool_description:
+        span.set_attribute(
+            GenAI.GEN_AI_TOOL_DESCRIPTION, tool_call.tool_description
+        )
+
+    # Set OPT-IN attributes (only if capture_content enabled)
+    if capture_content and is_experimental_mode():
+        content_mode = get_content_capturing_mode()
+        if content_mode in (
+            ContentCapturingMode.SPAN_ONLY,
+            ContentCapturingMode.SPAN_AND_EVENT,
+        ):
+            if tool_call.arguments is not None:
+                # Serialize to JSON string per spec
+                span.set_attribute(
+                    GenAI.GEN_AI_TOOL_CALL_ARGUMENTS,
+                    gen_ai_json_dumps(tool_call.arguments),
+                )
+
+            if tool_call.tool_result is not None:
+                span.set_attribute(
+                    GenAI.GEN_AI_TOOL_CALL_RESULT,
+                    gen_ai_json_dumps(tool_call.tool_result),
+                )
+
+    # Set CONDITIONALLY REQUIRED attributes
+    if tool_call.error_type:
+        span.set_attribute(error_attributes.ERROR_TYPE, tool_call.error_type)
+        span.set_status(Status(StatusCode.ERROR))
+
+
+def _finish_tool_call_span(
+    span: Span,
+    tool_call: ToolCall,
+    capture_content: bool = False,
+) -> None:
+    """Finalize tool call span with result or error.
+
+    Sets span name, applies final attributes, and sets status.
+    """
+    # Update span name with actual tool name
+    span.update_name(_get_tool_call_span_name(tool_call))
+
+    # Apply all attributes including result if available
+    _apply_tool_call_attributes(span, tool_call, capture_content)
+
+    # Set status based on error presence
+    if tool_call.error_type:
+        span.set_status(Status(StatusCode.ERROR))
+    else:
+        span.set_status(Status(StatusCode.OK))
+
+
 __all__ = [
     "_apply_llm_finish_attributes",
     "_apply_error_attributes",
@@ -287,4 +388,7 @@ def _get_llm_response_attributes(
     "_get_llm_response_attributes",
     "_get_llm_span_name",
     "_maybe_emit_llm_event",
+    "_apply_tool_call_attributes",
+    "_finish_tool_call_span",
+    "_get_tool_call_span_name",
 ]

util/opentelemetry-util-genai/src/opentelemetry/util/genai/types.py

@@ -69,6 +69,45 @@ class ToolCallRequest:
     type: Literal["tool_call"] = "tool_call"
 
 
+@dataclass()
+class ToolCall(ToolCallRequest):
+    """Represents a tool call for execution tracking with spans and metrics.
+
+    This type extends ToolCallRequest with additional fields for tracking tool execution
+    per the execute_tool span semantic conventions.
+
+    Reference: https://github.com/open-telemetry/semantic-conventions/blob/main/docs/gen-ai/gen-ai-spans.md#execute-tool-span
+
+    For simple message parts (tool calls requested by the model), consider using
+    ToolCallRequest instead to avoid unnecessary execution-tracking fields.
+
+    Semantic convention attributes for execute_tool spans:
+    - gen_ai.operation.name: "execute_tool" (Required)
+    - gen_ai.tool.name: Name of the tool (Recommended)
+    - gen_ai.tool.call.id: Tool call identifier (Recommended if available)
+    - gen_ai.tool.type: Type classification - "function", "extension", or "datastore" (Recommended if available)
+    - gen_ai.tool.description: Tool description (Recommended if available)
+    - gen_ai.tool.call.arguments: Parameters passed to tool (Opt-In, may contain sensitive data)
+    - gen_ai.tool.call.result: Result returned by tool (Opt-In, may contain sensitive data)
+    - error.type: Error type if operation failed (Conditionally Required)
+    """
+
+    # Execution-only fields (used for execute_tool spans):
+    # gen_ai.tool.type - Tool type: "function", "extension", or "datastore"
+    tool_type: str | None = None
+    # gen_ai.tool.description - Description of what the tool does
+    tool_description: str | None = None
+    # gen_ai.tool.call.result - Result returned by the tool (Opt-In, may contain sensitive data)
+    tool_result: Any = None
+    # error.type - Error type if the tool call failed
+    error_type: str | None = None
+
+    # Lifecycle tracking fields (used by TelemetryHandler):
+    context_token: ContextToken | None = None
+    span: Span | None = None
+    monotonic_start_s: float | None = None
+
+
 @dataclass()
 class ToolCallResponse:
     """Represents a tool call result sent to the model or a built-in tool call outcome and details