Merge branch 'main' into sqlalchemy-semconv-opt-in

Author: xrmx

opamp/opentelemetry-opamp-client/CHANGELOG.md

@@ -7,6 +7,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## Unreleased
 
+## Version 0.2b0 (2026-04-01)
+
 - Breaking change: callback class `Callbacks` renamed to `OpAMPCallbacks`
   ([#4355](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/4355))
 

opamp/opentelemetry-opamp-client/src/opentelemetry/_opamp/version.py

@@ -12,4 +12,4 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-__version__ = "0.2b0.dev"
+__version__ = "0.3b0.dev"

util/opentelemetry-util-genai/CHANGELOG.md

@@ -7,6 +7,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## Unreleased
 
+
+- Add support for workflow in genAI utils handler.
+  ([https://github.com/open-telemetry/opentelemetry-python-contrib/pull/4366](#4366))
 - Enrich ToolCall type, breaking change: usage of ToolCall class renamed to ToolCallRequest 
   ([#4218](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/4218))
 - Add EmbeddingInvocation span lifecycle support

util/opentelemetry-util-genai/README.rst

@@ -1,58 +1,129 @@
 OpenTelemetry Util for GenAI
 ============================
 
+The GenAI Utils package provides boilerplate and helpers to standardize instrumentation for Generative AI.
+It offers APIs to minimize the work needed to instrument GenAI libraries,
+while providing standardization for generating spans, metrics, and events.
 
-The GenAI Utils package will include boilerplate and helpers to standardize instrumentation for Generative AI. 
-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. 
+Key Components
+--------------
+
+- ``TelemetryHandler`` -- manages LLM invocation lifecycles (spans, metrics, events)
+- ``LLMInvocation`` and message types (``Text``, ``Reasoning``, ``Blob``, etc.) -- structured data model for GenAI interactions
+- ``CompletionHook`` -- protocol for uploading content to external storage (built-in ``fsspec`` support)
+- Metrics -- ``gen_ai.client.operation.duration`` and ``gen_ai.client.token.usage`` histograms
+
+
+Usage
+-----
+
+See the module docstring in ``opentelemetry.util.genai.handler`` for usage examples,
+including context manager and manual lifecycle patterns.
+
+
+Environment Variables
+---------------------
+
+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.
-Set the environment variable `OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT` to one of:
-- `NO_CONTENT`: Do not capture message content (default).
-- `SPAN_ONLY`: Capture message content in spans only.
-- `EVENT_ONLY`: Capture message content in events only.
-- `SPAN_AND_EVENT`: Capture message content in both spans and events.
-
-To control event emission, you can optionally set `OTEL_INSTRUMENTATION_GENAI_EMIT_EVENT` to `true` or `false` (case-insensitive).
-This variable controls whether to emit `gen_ai.client.inference.operation.details` events.
-If not explicitly set, the default value is automatically determined by `OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT`:
-- When `NO_CONTENT` or `SPAN_ONLY` is set: defaults to `false`
-- When `EVENT_ONLY` or `SPAN_AND_EVENT` is set: defaults to `true`
+Set the environment variable ``OTEL_SEMCONV_STABILITY_OPT_IN`` to ``gen_ai_latest_experimental`` to enable experimental features.
+Set the environment variable ``OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT`` to one of:
+
+- ``NO_CONTENT``: Do not capture message content (default).
+- ``SPAN_ONLY``: Capture message content in spans only.
+- ``EVENT_ONLY``: Capture message content in events only.
+- ``SPAN_AND_EVENT``: Capture message content in both spans and events.
+
+To control event emission, you can optionally set ``OTEL_INSTRUMENTATION_GENAI_EMIT_EVENT`` to ``true`` or ``false`` (case-insensitive).
+This variable controls whether to emit ``gen_ai.client.inference.operation.details`` events.
+If not explicitly set, the default value is automatically determined by ``OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT``:
+
+- When ``NO_CONTENT`` or ``SPAN_ONLY`` is set: defaults to ``false``
+- When ``EVENT_ONLY`` or ``SPAN_AND_EVENT`` is set: defaults to ``true``
+
 If explicitly set, the user's value takes precedence over the default.
 
-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"}]')
-- `gen_ai.system_instructions`: Str('[{"content": "You are a helpful assistant.", "type": "text"}]') (when system instruction is provided)
-
-This package also supports embedding invocation spans via the `embedding` context manager.
-For embedding invocations, common attributes include:
-
-- `gen_ai.provider.name`: Str(openai)
-- `gen_ai.operation.name`: Str(embeddings)
-- `gen_ai.request.model`: Str(text-embedding-3-small)
-- `gen_ai.embeddings.dimension.count`: Int(1536)
-- `gen_ai.request.encoding_formats`: Slice(["float"])
-- `gen_ai.usage.input_tokens`: Int(24)
-- `server.address`: Str(api.openai.com)
-- `server.port`: Int(443)
-
-When `EVENT_ONLY` or `SPAN_AND_EVENT` mode is enabled and a LoggerProvider is configured, 
-the package also emits `gen_ai.client.inference.operation.details` events with structured 
-message content (as dictionaries instead of JSON strings). Note that when using `EVENT_ONLY` 
-or `SPAN_AND_EVENT`, the `OTEL_INSTRUMENTATION_GENAI_EMIT_EVENT` environment variable defaults 
-to `true`, so events will be emitted automatically unless explicitly set to `false`.
+When ``EVENT_ONLY`` or ``SPAN_AND_EVENT`` mode is enabled and a LoggerProvider is configured,
+the package also emits ``gen_ai.client.inference.operation.details`` events with structured
+message content (as dictionaries instead of JSON strings). Note that when using ``EVENT_ONLY``
+or ``SPAN_AND_EVENT``, the ``OTEL_INSTRUMENTATION_GENAI_EMIT_EVENT`` environment variable defaults
+to ``true``, so events will be emitted automatically unless explicitly set to ``false``.
+
+Completion Hook / Upload
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+- ``OTEL_INSTRUMENTATION_GENAI_COMPLETION_HOOK``: Name of the completion hook entry point to load (e.g. ``upload``).
+- ``OTEL_INSTRUMENTATION_GENAI_UPLOAD_BASE_PATH``: An ``fsspec``-compatible URI/path for uploading prompts and responses
+  (e.g. ``/path/to/prompts`` or ``gs://my_bucket``). Required when using the ``upload`` hook.
+- ``OTEL_INSTRUMENTATION_GENAI_UPLOAD_FORMAT``: Format for uploaded data -- ``json`` (default) or ``jsonl``.
+- ``OTEL_INSTRUMENTATION_GENAI_UPLOAD_MAX_QUEUE_SIZE``: Maximum number of concurrent uploads to queue (default: ``20``).
+
+
+Span Attributes
+---------------
+
+This package sets the following span attributes on LLM invocations:
+
+**Common attributes:**
+
+- ``gen_ai.operation.name``: Str(chat)
+- ``gen_ai.provider.name``: Str(openai)
+- ``gen_ai.request.model``: Str(gpt-4o)
+- ``server.address``: Str(api.openai.com)
+- ``server.port``: Int(443)
+
+**Response attributes:**
+
+- ``gen_ai.response.finish_reasons``: Slice(["stop"])
+- ``gen_ai.response.model``: Str(gpt-4o-2024-05-13)
+- ``gen_ai.response.id``: Str(chatcmpl-Bz8yrvPnydD9pObv625n2CGBPHS13)
+- ``gen_ai.usage.input_tokens``: Int(24)
+- ``gen_ai.usage.output_tokens``: Int(7)
+
+**Request parameter attributes (when provided):**
+
+- ``gen_ai.request.temperature``: Float(0.7)
+- ``gen_ai.request.top_p``: Float(1.0)
+- ``gen_ai.request.frequency_penalty``: Float(0.0)
+- ``gen_ai.request.presence_penalty``: Float(0.0)
+- ``gen_ai.request.max_tokens``: Int(1024)
+- ``gen_ai.request.stop_sequences``: Slice(["\\n"])
+- ``gen_ai.request.seed``: Int(42)
+
+**Content attributes (sensitive, requires content capturing enabled):**
+
+- ``gen_ai.input.messages``: Str('[{"role": "user", "parts": [{"content": "hello world", "type": "text"}]}]')
+- ``gen_ai.output.messages``: Str('[{"role": "assistant", "parts": [{"content": "hello back", "type": "text"}], "finish_reason": "stop"}]')
+- ``gen_ai.system_instructions``: Str('[{"content": "You are a helpful assistant.", "type": "text"}]')
+
+**Error attributes:**
+
+- ``error.type``: Str(TimeoutError)
+
+Embedding Span Attributes
+-------------------------
+
+This package also supports embedding invocation spans via the ``embedding`` context manager.
+For embedding invocations, the following attributes are set:
+
+**Common attributes:**
+
+- ``gen_ai.operation.name``: Str(embeddings)
+- ``gen_ai.provider.name``: Str(openai)
+- ``server.address``: Str(api.openai.com)
+- ``server.port``: Int(443)
+
+**Request attributes:**
+
+- ``gen_ai.request.model``: Str(text-embedding-3-small)
+- ``gen_ai.embeddings.dimension.count``: Int(1536)
+- ``gen_ai.request.encoding_formats``: Slice(["float"])
+
+**Response attributes:**
+
+- ``gen_ai.response.model``: Str(text-embedding-3-small)
+- ``gen_ai.usage.input_tokens``: Int(24)
 
 
 Installation
@@ -62,11 +133,15 @@ Installation
 
     pip install opentelemetry-util-genai
 
+For upload support (requires ``fsspec``)::
+
+    pip install opentelemetry-util-genai[upload]
+
 
 Design Document
 ---------------
 
-The design document for the OpenTelemetry GenAI Utils can be found at: `Design Document <https://docs.google.com/document/d/1w9TbtKjuRX_wymS8DRSwPA03_VhrGlyx65hHAdNik1E/edit?tab=t.qneb4vabc1wc#heading=h.kh4j6stirken>`_
+The design document for the OpenTelemetry GenAI Utils can be found at: `Design Document <https://docs.google.com/document/d/1LzNGylxot5zaIV1goOJZ2mz3LI0weFu1SgaMnyDv7gg/edit?usp=sharing>`_
 
 References
 ----------

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

@@ -60,6 +60,7 @@
 
 from __future__ import annotations
 
+import logging
 import timeit
 from contextlib import contextmanager
 from typing import Iterator, TypeVar
@@ -83,18 +84,38 @@
     _apply_embedding_finish_attributes,
     _apply_error_attributes,
     _apply_llm_finish_attributes,
+    _apply_workflow_finish_attributes,
     _get_embedding_span_name,
     _get_llm_span_name,
+    _get_workflow_span_name,
     _maybe_emit_llm_event,
 )
 from opentelemetry.util.genai.types import (
     EmbeddingInvocation,
     Error,
     GenAIInvocation,
     LLMInvocation,
+    WorkflowInvocation,
 )
 from opentelemetry.util.genai.version import __version__
 
+_logger = logging.getLogger(__name__)
+
+
+def _safe_detach(invocation: GenAIInvocation) -> None:
+    """Detach the context token if still present, as a safety net."""
+    if invocation.context_token is not None:
+        try:
+            otel_context.detach(invocation.context_token)
+        except Exception:  # pylint: disable=broad-except
+            pass
+    if invocation.span is not None:
+        try:
+            invocation.span.end()
+        except Exception:  # pylint: disable=broad-except
+            pass
+
+
 _T = TypeVar("_T", bound=GenAIInvocation)
 
 
@@ -160,13 +181,19 @@ def _start(self, invocation: _T) -> _T:
         """Start a GenAI invocation and create a pending span entry."""
         if isinstance(invocation, LLMInvocation):
             span_name = _get_llm_span_name(invocation)
+            kind = SpanKind.CLIENT
         elif isinstance(invocation, EmbeddingInvocation):
             span_name = _get_embedding_span_name(invocation)
+            kind = SpanKind.CLIENT
+        elif isinstance(invocation, WorkflowInvocation):
+            span_name = _get_workflow_span_name(invocation)
+            kind = SpanKind.INTERNAL
         else:
             span_name = ""
+            kind = SpanKind.CLIENT
         span = self._tracer.start_span(
             name=span_name,
-            kind=SpanKind.CLIENT,
+            kind=kind,
         )
         # Record a monotonic start timestamp (seconds) for duration
         # calculation using timeit.default_timer.
@@ -192,6 +219,9 @@ 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, WorkflowInvocation):
+                _apply_workflow_finish_attributes(span, invocation)
+                # TODO: Add workflow metrics when supported
         finally:
             # Detach context and end span even if finishing fails
             otel_context.detach(invocation.context_token)
@@ -222,6 +252,10 @@ def _fail(self, invocation: _T, error: Error) -> _T:
                 self._record_embedding_metrics(
                     invocation, span, error_type=error_type
                 )
+            elif isinstance(invocation, WorkflowInvocation):
+                _apply_workflow_finish_attributes(span, invocation)
+                _apply_error_attributes(span, error, error_type)
+                # TODO: Add workflow metrics when supported
         finally:
             # Detach context and end span even if finishing fails
             otel_context.detach(invocation.context_token)
@@ -304,6 +338,46 @@ def embedding(
             raise
         self.stop(invocation)
 
+    @contextmanager
+    def workflow(
+        self, invocation: WorkflowInvocation | None = None
+    ) -> Iterator[WorkflowInvocation]:
+        """Context manager for Workflow 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.
+        """
+        if invocation is None:
+            invocation = WorkflowInvocation()
+
+        try:
+            self.start(invocation)
+        except Exception:  # pylint: disable=broad-except
+            _logger.warning(
+                "Failed to start workflow telemetry", exc_info=True
+            )
+
+        try:
+            yield invocation
+        except Exception as exc:
+            try:
+                self.fail(invocation, Error(message=str(exc), type=type(exc)))
+            except Exception:  # pylint: disable=broad-except
+                _logger.warning(
+                    "Failed to record workflow failure", exc_info=True
+                )
+                _safe_detach(invocation)
+            raise
+
+        try:
+            self.stop(invocation)
+        except Exception:  # pylint: disable=broad-except
+            _logger.warning("Failed to stop workflow telemetry", exc_info=True)
+            _safe_detach(invocation)
+
 
 def get_telemetry_handler(
     tracer_provider: TracerProvider | None = None,