Fix merge conflicts, update tool start/stop/fail to match api

Author: keith-decker

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

@@ -56,9 +56,9 @@
 
     # Or, manage the lifecycle manually
     tool = ToolCall(name="get_weather", arguments={"location": "Paris"})
-    handler.start_tool_call(tool)
+    handler.start(tool)
     tool.tool_result = {"temp": 20}
-    handler.stop_tool_call(tool)
+    handler.stop(tool)
 """
 
 from __future__ import annotations
@@ -87,10 +87,10 @@
     _apply_embedding_finish_attributes,
     _apply_error_attributes,
     _apply_llm_finish_attributes,
-    _get_embedding_span_name,
-    _get_llm_span_name,
     _apply_tool_call_attributes,
     _finish_tool_call_span,
+    _get_embedding_span_name,
+    _get_llm_span_name,
     _get_tool_call_span_name,
     _maybe_emit_llm_event,
 )
@@ -166,17 +166,25 @@ def _record_embedding_metrics(
 
     def _start(self, invocation: _T) -> _T:
         """Start a GenAI invocation and create a pending span entry."""
+        span_kind = SpanKind.CLIENT
         if isinstance(invocation, LLMInvocation):
             span_name = _get_llm_span_name(invocation)
         elif isinstance(invocation, EmbeddingInvocation):
             span_name = _get_embedding_span_name(invocation)
+        elif isinstance(invocation, ToolCall):
+            span_name = _get_tool_call_span_name(invocation)
+            span_kind = SpanKind.INTERNAL
         else:
             span_name = ""
+
         span = self._tracer.start_span(
             name=span_name,
-            kind=SpanKind.CLIENT,
+            kind=span_kind,
         )
-        # Record a monotonic start timestamp (seconds) for duration
+        if isinstance(invocation, ToolCall):
+            _apply_tool_call_attributes(
+                span, invocation, capture_content=False
+            )
         # calculation using timeit.default_timer.
         invocation.monotonic_start_s = timeit.default_timer()
         invocation.span = span
@@ -200,6 +208,8 @@ def _stop(self, invocation: _T) -> _T:
             elif isinstance(invocation, EmbeddingInvocation):
                 _apply_embedding_finish_attributes(span, invocation)
                 self._record_embedding_metrics(invocation, span)
+            elif isinstance(invocation, ToolCall):
+                _finish_tool_call_span(span, invocation, capture_content=True)
         finally:
             # Detach context and end span even if finishing fails
             otel_context.detach(invocation.context_token)
@@ -230,6 +240,10 @@ def _fail(self, invocation: _T, error: Error) -> _T:
                 self._record_embedding_metrics(
                     invocation, span, error_type=error_type
                 )
+            elif isinstance(invocation, ToolCall):
+                invocation.error_type = error_type
+                _finish_tool_call_span(span, invocation, capture_content=True)
+                span.set_status(Status(StatusCode.ERROR, error.message))
         finally:
             # Detach context and end span even if finishing fails
             otel_context.detach(invocation.context_token)
@@ -266,105 +280,6 @@ def fail_llm(
         """Fail an LLM invocation and end its span with error status."""
         return self._fail(invocation, error)
 
-    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
@@ -388,15 +303,13 @@ def tool_call(
                 arguments={},
                 id=None,
             )
-        self.start_tool_call(tool_call)
+        self.start(tool_call)
         try:
             yield tool_call
         except Exception as exc:
-            self.fail_tool_call(
-                tool_call, Error(message=str(exc), type=type(exc))
-            )
+            self.fail(tool_call, Error(message=str(exc), type=type(exc)))
             raise
-        self.stop_tool_call(tool_call)
+        self.stop(tool_call)
 
     @contextmanager
     def llm(

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

@@ -69,45 +69,6 @@ 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

util/opentelemetry-util-genai/tests/test_handler_metrics.py

@@ -213,13 +213,13 @@ def setUp(self) -> None:
         self.handler = TelemetryHandler(tracer_provider=self.tracer_provider)
 
     def test_start_tool_call_creates_span(self):
-        """Test start_tool_call creates span with correct name and kind"""
+        """Test start creates span with correct name and kind for ToolCall"""
         tool = ToolCall(
             name="get_weather",
             arguments={"location": "Paris"},
             id="call_123",
         )
-        self.handler.start_tool_call(tool)
+        self.handler.start(tool)
 
         spans = self.span_exporter.get_finished_spans()
         self.assertEqual(len(spans), 0)  # Span not finished yet
@@ -231,17 +231,17 @@ def test_start_tool_call_creates_span(self):
         self.assertEqual(tool.span.kind, SpanKind.INTERNAL)
 
     def test_stop_tool_call_ends_span(self):
-        """Test stop_tool_call ends span successfully"""
+        """Test stop ends span successfully for ToolCall"""
         tool = ToolCall(
             name="get_weather",
             arguments={"location": "Paris"},
             id="call_123",
             tool_type="function",
             tool_description="Get current weather",
         )
-        self.handler.start_tool_call(tool)
+        self.handler.start(tool)
         tool.tool_result = {"temp": 20, "condition": "sunny"}
-        self.handler.stop_tool_call(tool)
+        self.handler.stop(tool)
 
         spans = self.span_exporter.get_finished_spans()
         self.assertEqual(len(spans), 1)
@@ -272,21 +272,21 @@ def test_stop_tool_call_ends_span(self):
         self.assertEqual(span.status.status_code, StatusCode.OK)
 
     def test_stop_tool_call_without_start(self):
-        """Test stop_tool_call without prior start is a no-op"""
+        """Test stop without prior start is a no-op for ToolCall"""
         tool = ToolCall(name="test", arguments={}, id=None)
-        # Don't call start_tool_call
-        self.handler.stop_tool_call(tool)
+        # Don't call start
+        self.handler.stop(tool)
 
         spans = self.span_exporter.get_finished_spans()
         self.assertEqual(len(spans), 0)
 
     def test_fail_tool_call_sets_error_status(self):
-        """Test fail_tool_call sets error status and attributes"""
+        """Test fail sets error status and attributes for ToolCall"""
         tool = ToolCall(name="failing_tool", arguments={}, id="call_456")
-        self.handler.start_tool_call(tool)
+        self.handler.start(tool)
 
         error = Error(message="Tool execution failed", type=ValueError)
-        self.handler.fail_tool_call(tool, error)
+        self.handler.fail(tool, error)
 
         spans = self.span_exporter.get_finished_spans()
         self.assertEqual(len(spans), 1)
@@ -316,9 +316,9 @@ def test_tool_call_with_content_capture(self):
             arguments={"location": "Paris"},
             id="call_123",
         )
-        self.handler.start_tool_call(tool)
+        self.handler.start(tool)
         tool.tool_result = {"temp": 20, "condition": "sunny"}
-        self.handler.stop_tool_call(tool)
+        self.handler.stop(tool)
 
         spans = self.span_exporter.get_finished_spans()
         span = spans[0]