GenAI Utils | Inference Type and Span Creation

util/opentelemetry-util-genai/CHANGELOG.md

@@ -9,3 +9,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - Add a utility to parse the `OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT` environment variable.
   Add `gen_ai_latest_experimental` as a new value to the Sem Conv stability flag ([#3716](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/3716)).
+
+### Added
+
+- Generate Spans for LLM invocations
+- Helper functions for starting and finishing LLM invocations

util/opentelemetry-util-genai/README.rst

@@ -6,6 +6,24 @@ The GenAI Utils package will include boilerplate and helpers to standardize inst
 This package will provide APIs and decorators to minimize the work needed to instrument genai libraries, 
 while providing standardization for generating both types of otel, "spans and metrics" and "spans, metrics and events"
 
+This package relies on environment variables to configure capturing of message content. 
+By default, message content will not be captured.
+Set the environment variable `OTEL_SEMCONV_STABILITY_OPT_IN` to `gen_ai_latest_experimental` to enable experimental features.
+And set the environment variable `OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT` to `SPAN_ONLY` or `SPAN_AND_EVENT` to capture message content in spans.
+
+This package provides these span attributes.
+-> gen_ai.provider.name: Str(openai)
+-> gen_ai.operation.name: Str(chat)
+-> gen_ai.request.model: Str(gpt-3.5-turbo)
+-> gen_ai.response.finish_reasons: Slice(["stop"])
+-> gen_ai.response.model: Str(gpt-3.5-turbo-0125)
+-> gen_ai.response.id: Str(chatcmpl-Bz8yrvPnydD9pObv625n2CGBPHS13)
+-> gen_ai.usage.input_tokens: Int(24)
+-> gen_ai.usage.output_tokens: Int(7)
+-> gen_ai.input.messages: Str('[{"role": "Human", "parts": [{"content": "hello world", "type": "text"}]}]')
+-> gen_ai.output.messages: Str('[{"role": "AI", "parts": [{"content": "hello back", "type": "text"}], "finish_reason": "stop"}]')
+
+
 Installation
 ------------
 

util/opentelemetry-util-genai/pyproject.toml

@@ -8,7 +8,7 @@ dynamic = ["version"]
 description = "OpenTelemetry GenAI Utils"
 readme = "README.rst"
 license = "Apache-2.0"
-requires-python = ">=3.8"
+requires-python = ">=3.9"
 authors = [
   { name = "OpenTelemetry Authors", email = "[email protected]" },
 ]
@@ -25,8 +25,8 @@ classifiers = [
   "Programming Language :: Python :: 3.13",
 ]
 dependencies = [
-  "opentelemetry-instrumentation ~= 0.51b0",
-  "opentelemetry-semantic-conventions ~= 0.51b0",
+  "opentelemetry-instrumentation ~= 0.57b0",
+  "opentelemetry-semantic-conventions ~= 0.57b0",
   "opentelemetry-api>=1.31.0",
 ]
 

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

@@ -0,0 +1,13 @@
+# Copyright The OpenTelemetry Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.

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

@@ -0,0 +1,119 @@
+# Copyright The OpenTelemetry Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""
+Span generation utilities for GenAI telemetry.
+
+This module maps GenAI (Generative AI) invocations to OpenTelemetry spans and
+applies GenAI semantic convention attributes.
+
+Classes:
+    - BaseTelemetryGenerator: Abstract base for GenAI telemetry emitters.
+    - SpanGenerator: Concrete implementation that creates and finalizes spans
+      for LLM operations (e.g., chat) and records input/output messages when
+      experimental mode and content capture settings allow.
+
+Usage:
+    See `opentelemetry/util/genai/handler.py` for `TelemetryHandler`, which
+    constructs `LLMInvocation` objects and delegates to `SpanGenerator.start`,
+    `SpanGenerator.finish`, and `SpanGenerator.error` to produce spans that
+    follow the GenAI semantic conventions.
+"""
+
+from contextvars import Token
+from typing import Dict, Optional
+from uuid import UUID
+
+from typing_extensions import TypeAlias
+
+from opentelemetry import context as otel_context
+from opentelemetry import trace
+from opentelemetry.semconv._incubating.attributes import (
+    gen_ai_attributes as GenAI,
+)
+from opentelemetry.trace import (
+    Span,
+    SpanKind,
+    Tracer,
+    set_span_in_context,
+)
+
+from .span_utils import (
+    _apply_error_attributes,
+    _apply_finish_attributes,
+)
+from .types import Error, LLMInvocation
+
+# Type alias matching the token type expected by opentelemetry.context.detach
+ContextToken: TypeAlias = Token[otel_context.Context]
+
+
+class BaseTelemetryGenerator:
+    """
+    Abstract base for emitters mapping GenAI types -> OpenTelemetry.
+    """
+
+    def start(self, invocation: LLMInvocation) -> None:
+        raise NotImplementedError
+
+    def finish(self, invocation: LLMInvocation) -> None:
+        raise NotImplementedError
+
+    def error(self, error: Error, invocation: LLMInvocation) -> None:
+        raise NotImplementedError
+
+
+class SpanGenerator(BaseTelemetryGenerator):
+    """
+    Generates only spans.
+    """
+
+    def __init__(
+        self,
+        tracer: Optional[Tracer] = None,
+    ):
+        self._tracer: Tracer = tracer or trace.get_tracer(__name__)
+
+        # Store the active span and its context attachment token
+        self._active: Dict[UUID, tuple[Span, ContextToken]] = {}
+
+    def start(self, invocation: LLMInvocation):
+        # Create a span and attach it as current; keep the token to detach later
+        span = self._tracer.start_span(
+            name=f"{GenAI.GenAiOperationNameValues.CHAT.value} {invocation.request_model}",
+            kind=SpanKind.CLIENT,
+        )
+        invocation.span = span
+        invocation.context_token = otel_context.attach(
+            set_span_in_context(span)
+        )
+
+    def finish(self, invocation: LLMInvocation):
+        if invocation.context_token is None or invocation.span is None:
+            return
+
+        _apply_finish_attributes(invocation.span, invocation)
+        # Detach context and end span
+        otel_context.detach(invocation.context_token)
+        invocation.span.end()
+
+    def error(self, error: Error, invocation: LLMInvocation):
+        if invocation.context_token is None or invocation.span is None:
+            return
+
+        _apply_error_attributes(invocation.span, error)
+        # Detach context and end span
+        otel_context.detach(invocation.context_token)
+        invocation.span.end()
+        return

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

@@ -0,0 +1,144 @@
+# Copyright The OpenTelemetry Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""
+Telemetry handler for GenAI invocations.
+
+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.
+
+Classes:
+    - TelemetryHandler: Manages GenAI invocation lifecycles and emits telemetry.
+
+Functions:
+    - get_telemetry_handler: Returns a singleton `TelemetryHandler` instance.
+
+Usage:
+    handler = get_telemetry_handler()
+    handler.start_llm(input_messages, request_model, **attrs)
+    handler.stop_llm(invocation, output_messages, **attrs)
+    handler.fail_llm(invocation, error, **attrs)
+"""
+
+import time
+from typing import Any, List, Optional
+
+from opentelemetry.semconv.schemas import Schemas
+from opentelemetry.trace import get_tracer
+
+from .generators import SpanGenerator
+from .types import Error, InputMessage, LLMInvocation, OutputMessage
+from .version import __version__
+
+
+def _apply_known_attrs_to_invocation(
+    invocation: LLMInvocation, attributes: dict[str, Any]
+) -> None:
+    """Pop known fields from attributes and set them on the invocation.
+
+    Mutates the provided attributes dict by popping known keys, leaving
+    only unknown/custom attributes behind for the caller to persist into
+    invocation.attributes.
+    """
+    if "provider" in attributes:
+        invocation.provider = attributes.pop("provider")
+    if "response_model_name" in attributes:
+        invocation.response_model_name = attributes.pop("response_model_name")
+    if "response_id" in attributes:
+        invocation.response_id = attributes.pop("response_id")
+    if "input_tokens" in attributes:
+        invocation.input_tokens = attributes.pop("input_tokens")
+    if "output_tokens" in attributes:
+        invocation.output_tokens = attributes.pop("output_tokens")
+
+
+class TelemetryHandler:
+    """
+    High-level handler managing GenAI invocation lifecycles and emitting
+    them as spans, metrics, and events.
+    """
+
+    def __init__(self, **kwargs: Any):
+        tracer_provider = kwargs.get("tracer_provider")
+        self._tracer = get_tracer(
+            __name__,
+            __version__,
+            tracer_provider,
+            schema_url=Schemas.V1_36_0.value,
+        )
+
+        self._generator = SpanGenerator(tracer=self._tracer)
+
+    def start_llm(
+        self,
+        request_model: str,
+        input_messages: List[InputMessage],
+        **attributes: Any,
+    ) -> LLMInvocation:
+        """Start an LLM invocation and create a pending span entry.
+
+        Known attributes provided via ``**attributes`` (``provider``,
+        ``response_model_name``, ``response_id``, ``input_tokens``,
+        ``output_tokens``) are extracted and set as explicit fields on the
+        ``LLMInvocation``. Any remaining keys are preserved in
+        ``invocation.attributes`` for custom metadata.
+
+        Returns the ``LLMInvocation`` to use with `stop_llm` and `fail_llm`.
+        """
+        invocation = LLMInvocation(
+            request_model=request_model,
+            input_messages=input_messages,
+            attributes=attributes,
+        )
+        _apply_known_attrs_to_invocation(invocation, invocation.attributes)
+        self._generator.start(invocation)
+        return invocation
+
+    def stop_llm(
+        self,
+        invocation: LLMInvocation,
+        output_messages: List[OutputMessage],
+        **attributes: Any,
+    ) -> LLMInvocation:
+        """Finalize an LLM invocation successfully and end its span."""
+        invocation.end_time = time.time()
+        invocation.output_messages = output_messages
+        _apply_known_attrs_to_invocation(invocation, attributes)
+        invocation.attributes.update(attributes)
+        self._generator.finish(invocation)
+        return invocation
+
+    def fail_llm(
+        self, invocation: LLMInvocation, error: Error, **attributes: Any
+    ) -> LLMInvocation:
+        """Fail an LLM invocation and end its span with error status."""
+        invocation.end_time = time.time()
+        _apply_known_attrs_to_invocation(invocation, attributes)
+        invocation.attributes.update(**attributes)
+        self._generator.error(error, invocation)
+        return invocation
+
+
+def get_telemetry_handler(**kwargs: Any) -> TelemetryHandler:
+    """
+    Returns a singleton TelemetryHandler instance.
+    """
+    handler: Optional[TelemetryHandler] = getattr(
+        get_telemetry_handler, "_default_handler", None
+    )
+    if handler is None:
+        handler = TelemetryHandler(**kwargs)
+        setattr(get_telemetry_handler, "_default_handler", handler)
+    return handler