GenAI Utils | Inference Type and Span Creation

docs/nitpick-exceptions.ini

@@ -45,6 +45,7 @@ py-class=
     psycopg.AsyncConnection
     ObjectProxy
     fastapi.applications.FastAPI
+    _contextvars.Token
 
 any=
     ; API

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,25 @@ 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,120 @@
+# 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 opentelemetry.util.genai.span_utils import (
+    _apply_error_attributes,
+    _apply_finish_attributes,
+)
+from opentelemetry.util.genai.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
+        if not (invocation.request_model and invocation.request_model.strip()):
+            raise ValueError("request_model is required")
+        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,114 @@
+# 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()
+
+    # 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.
+    invocation = LLMInvocation(
+        request_model="my-model",
+        input_messages=[...],
+        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="..."))
+"""
+
+import time
+from contextlib import contextmanager
+from typing import Any, Iterator, Optional
+
+from opentelemetry.semconv.schemas import Schemas
+from opentelemetry.trace import get_tracer
+from opentelemetry.util.genai.generators import SpanGenerator
+from opentelemetry.util.genai.types import Error, LLMInvocation
+from opentelemetry.util.genai.version import __version__
+
+
+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)
+
+    @contextmanager
+    def llm(self, invocation: LLMInvocation) -> Iterator[LLMInvocation]:
+        """Context manager for LLM invocations.
+
+        Only set data attributes on the invocation object, do not modify the span or context.
+
+        Starts the span on entry. On normal exit, finalizes the invocation and ends the span.
+        If an exception occurs inside the context, marks the span as error, ends it, and
+        re-raises the original exception.
+        """
+        self._generator.start(invocation)
+        try:
+            yield invocation
+        except BaseException as exc:  # noqa: B902 - ensure we capture all exceptions incl. SystemExit, KeyboardInterrupt
+            invocation.end_time = time.time()
+            self._generator.error(
+                Error(message=str(exc), type=type(exc)), invocation
+            )
+            raise
+        invocation.end_time = time.time()
+        self._generator.finish(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