pre-commit fix

Author: shuningc

util/opentelemetry-util-genai/CHANGELOG.md

@@ -22,6 +22,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   ([https://github.com/open-telemetry/opentelemetry-python-contrib/pull/3891](#3891))
 - Add parent class genAI invocation
   ([https://github.com/open-telemetry/opentelemetry-python-contrib/pull/3889](#3889))
+- Add `EmbeddingInvocation` span lifecycle support (`start_embedding`,
+  `stop_embedding`, `fail_embedding`), embedding span tests, and defer
+  embedding metrics emission (current no-op) to a follow-up PR.
+  ([#<PR_NUMBER>](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/<PR_NUMBER>))
 
 ## Version 0.2b0 (2025-10-14)
 

util/opentelemetry-util-genai/README.rst

@@ -36,6 +36,19 @@ This package provides these span attributes:
 - `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
+`EmbeddingInvocation` and `TelemetryHandler.start_embedding/stop_embedding/fail_embedding`.
+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.embedding.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` 

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

@@ -80,16 +80,15 @@
 )
 from opentelemetry.util.genai.metrics import InvocationMetricsRecorder
 from opentelemetry.util.genai.span_utils import (
+    _apply_embedding_finish_attributes,
     _apply_error_attributes,
     _apply_llm_finish_attributes,
-    _apply_embedding_finish_attributes,
     _maybe_emit_llm_event,
-    _maybe_emit_embedding_event,
 )
 from opentelemetry.util.genai.types import (
+    EmbeddingInvocation,
     Error,
     LLMInvocation,
-    EmbeddingInvocation,
 )
 from opentelemetry.util.genai.version import __version__
 
@@ -255,7 +254,6 @@ def stop_embedding(
         span = invocation.span
         _apply_embedding_finish_attributes(span, invocation)
         self._record_embedding_metrics(invocation, span)
-        _maybe_emit_embedding_event(self._logger, span, invocation)
         # Detach context and end span
         otel_context.detach(invocation.context_token)
         span.end()
@@ -273,10 +271,7 @@ def fail_embedding(
         _apply_embedding_finish_attributes(invocation.span, invocation)
         _apply_error_attributes(invocation.span, error)
         error_type = getattr(error.type, "__qualname__", None)
-        self._record_embedding_metrics(
-            invocation, span, error_type=error_type
-        )
-        _maybe_emit_embedding_event(self._logger, span, invocation, error)
+        self._record_embedding_metrics(invocation, span, error_type=error_type)
         # Detach context and end span
         otel_context.detach(invocation.context_token)
         span.end()

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

@@ -285,10 +285,6 @@ class EmbeddingInvocation(GenAIInvocation):
     Additional attributes to set on metrics. Must be of a low cardinality.
     These attributes will not be set on spans or events.
     """
-    # Monotonic start time in seconds (from timeit.default_timer) used
-    # for duration calculations to avoid mixing clock sources. This is
-    # populated by the TelemetryHandler when starting an invocation.
-    monotonic_start_s: float | None = None
 
 
 @dataclass

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

@@ -501,6 +501,82 @@ def test_parent_child_span_relationship(self):
         # Parent should not have a parent (root)
         assert parent_span.parent is None
 
+    @patch_env_vars(
+        stability_mode="gen_ai_latest_experimental",
+        content_capturing="SPAN_ONLY",
+        emit_event="",
+    )
+    def test_embedding_parent_child_span_relationship(self):
+        parent_invocation = EmbeddingInvocation(
+            request_model="embed-parent-model",
+            provider="test-provider",
+            input_tokens=10,
+        )
+        child_invocation = EmbeddingInvocation(
+            request_model="embed-child-model",
+            provider="test-provider",
+            input_tokens=5,
+        )
+
+        self.telemetry_handler.start_embedding(parent_invocation)
+        assert parent_invocation.span is not None
+        self.telemetry_handler.start_embedding(child_invocation)
+        assert child_invocation.span is not None
+        self.telemetry_handler.stop_embedding(child_invocation)
+        self.telemetry_handler.stop_embedding(parent_invocation)
+
+        spans = self.span_exporter.get_finished_spans()
+        assert len(spans) == 2
+        child_span = next(
+            s for s in spans if s.name == "embeddings embed-child-model"
+        )
+        parent_span = next(
+            s for s in spans if s.name == "embeddings embed-parent-model"
+        )
+
+        assert child_span.context.trace_id == parent_span.context.trace_id
+        assert child_span.parent is not None
+        assert child_span.parent.span_id == parent_span.context.span_id
+        assert parent_span.parent is None
+
+    @patch_env_vars(
+        stability_mode="gen_ai_latest_experimental",
+        content_capturing="SPAN_ONLY",
+        emit_event="",
+    )
+    def test_llm_parent_embedding_child_span_relationship(self):
+        message = _create_input_message("hi")
+        chat_generation = _create_output_message("ok")
+        child_invocation = EmbeddingInvocation(
+            request_model="embed-child-model",
+            provider="test-provider",
+            input_tokens=3,
+        )
+
+        with self.telemetry_handler.llm() as parent_invocation:
+            for attr, value in {
+                "request_model": "parent-model",
+                "input_messages": [message],
+                "provider": "test-provider",
+            }.items():
+                setattr(parent_invocation, attr, value)
+            self.telemetry_handler.start_embedding(child_invocation)
+            assert child_invocation.span is not None
+            self.telemetry_handler.stop_embedding(child_invocation)
+            parent_invocation.output_messages = [chat_generation]
+
+        spans = self.span_exporter.get_finished_spans()
+        assert len(spans) == 2
+        child_span = next(
+            s for s in spans if s.name == "embeddings embed-child-model"
+        )
+        parent_span = next(s for s in spans if s.name == "chat parent-model")
+
+        assert child_span.context.trace_id == parent_span.context.trace_id
+        assert child_span.parent is not None
+        assert child_span.parent.span_id == parent_span.context.span_id
+        assert parent_span.parent is None
+
     def test_llm_context_manager_error_path_records_error_status_and_attrs(
         self,
     ):
@@ -907,92 +983,6 @@ def test_embedding_manual_start_and_stop_creates_span(self):
             },
         )
 
-    @patch_env_vars(
-        stability_mode="gen_ai_latest_experimental",
-        content_capturing="EVENT_ONLY",
-        emit_event="true",
-    )
-    def test_emits_embedding_event(self):
-        invocation = EmbeddingInvocation(
-            request_model="event-embed-model",
-            provider="test-provider",
-            dimension_count=1024,
-            encoding_formats=["float"],
-            input_tokens=10,
-            server_address="event.server.com",
-            server_port=8443,
-        )
-
-        self.telemetry_handler.start_embedding(invocation)
-        self.telemetry_handler.stop_embedding(invocation)
-
-        logs = self.log_exporter.get_finished_logs()
-        self.assertEqual(len(logs), 1)
-        log_record = logs[0].log_record
-        self.assertEqual(
-            log_record.event_name, "gen_ai.client.embedding.operation.details"
-        )
-
-        attrs = log_record.attributes
-        self.assertIsNotNone(attrs)
-        self.assertEqual(attrs[GenAI.GEN_AI_OPERATION_NAME], "embeddings")
-        self.assertEqual(
-            attrs[GenAI.GEN_AI_REQUEST_MODEL], "event-embed-model"
-        )
-        self.assertEqual(attrs[GenAI.GEN_AI_PROVIDER_NAME], "test-provider")
-        self.assertEqual(attrs[GenAI.GEN_AI_EMBEDDING_DIMENSION_COUNT], 1024)
-        self.assertEqual(
-            _normalize_to_list(attrs[GenAI.GEN_AI_REQUEST_ENCODING_FORMATS]),
-            ["float"],
-        )
-        self.assertEqual(attrs[GenAI.GEN_AI_USAGE_INPUT_TOKENS], 10)
-        self.assertEqual(attrs[server_attributes.SERVER_ADDRESS], "event.server.com")
-        self.assertEqual(attrs[server_attributes.SERVER_PORT], 8443)
-
-        span = _get_single_span(self.span_exporter)
-        self.assertIsNotNone(log_record.trace_id)
-        self.assertIsNotNone(log_record.span_id)
-        self.assertIsNotNone(span.context)
-        self.assertEqual(log_record.trace_id, span.context.trace_id)
-        self.assertEqual(log_record.span_id, span.context.span_id)
-
-    @patch_env_vars(
-        stability_mode="gen_ai_latest_experimental",
-        content_capturing="EVENT_ONLY",
-        emit_event="true",
-    )
-    def test_emits_embedding_event_with_error(self):
-        class EmbeddingError(RuntimeError):
-            pass
-
-        invocation = EmbeddingInvocation(
-            request_model="error-embed-model",
-            provider="test-provider",
-            input_tokens=9,
-        )
-        self.telemetry_handler.start_embedding(invocation)
-        error = Error(message="embedding error", type=EmbeddingError)
-        self.telemetry_handler.fail_embedding(invocation, error)
-
-        logs = self.log_exporter.get_finished_logs()
-        self.assertEqual(len(logs), 1)
-        log_record = logs[0].log_record
-        attrs = log_record.attributes
-        self.assertEqual(
-            attrs[error_attributes.ERROR_TYPE], EmbeddingError.__qualname__
-        )
-        self.assertEqual(attrs[GenAI.GEN_AI_OPERATION_NAME], "embeddings")
-        self.assertEqual(
-            attrs[GenAI.GEN_AI_REQUEST_MODEL], "error-embed-model"
-        )
-
-        span = _get_single_span(self.span_exporter)
-        self.assertIsNotNone(log_record.trace_id)
-        self.assertIsNotNone(log_record.span_id)
-        self.assertIsNotNone(span.context)
-        self.assertEqual(log_record.trace_id, span.context.trace_id)
-        self.assertEqual(log_record.span_id, span.context.span_id)
-
 
 class AnyNonNone:
     def __eq__(self, other):