Small changes and cleanup to GenAi Utils package to enable google's GenAi instrumentation to use it (#4556)

DylanRussell · aabmass · web-flow · commit 7208140cdd75 · 2026-05-08T19:30:55.000Z
* Changes to genai utils

* Add changelog

* Fix lint error

* Operation name is allowed to vary according to the sem convs

* Revert changes to the cosntructor i didn't mean to make

---------

Co-authored-by: Aaron Abbott &lt;aaronabbott@google.com&gt;
diff --git a/instrumentation-genai/opentelemetry-instrumentation-anthropic/pyproject.toml b/instrumentation-genai/opentelemetry-instrumentation-anthropic/pyproject.toml
@@ -25,9 +25,9 @@ classifiers = [
   "Programming Language :: Python :: 3.14",
 ]
 dependencies = [
-  "opentelemetry-api ~= 1.39",
-  "opentelemetry-instrumentation ~= 0.60b0",
-  "opentelemetry-semantic-conventions ~= 0.60b0",
+  "opentelemetry-api ~= 1.40",
+  "opentelemetry-instrumentation ~= 0.61b0",
+  "opentelemetry-semantic-conventions ~= 0.61b0",
   "opentelemetry-util-genai >= 0.4b0.dev, <0.5b0",
 ]
 
diff --git a/instrumentation-genai/opentelemetry-instrumentation-anthropic/tests/requirements.oldest.txt b/instrumentation-genai/opentelemetry-instrumentation-anthropic/tests/requirements.oldest.txt
@@ -21,8 +21,8 @@ pytest==7.4.4
 pytest-vcr==1.0.2
 pytest-asyncio==0.21.0
 wrapt==1.16.0
-opentelemetry-api==1.39  # when updating, also update in pyproject.toml
-opentelemetry-sdk==1.39  # when updating, also update in pyproject.toml
-opentelemetry-semantic-conventions==0.60b0  # when updating, also update in pyproject.toml
+opentelemetry-api==1.40  # when updating, also update in pyproject.toml
+opentelemetry-sdk==1.40  # when updating, also update in pyproject.toml
+opentelemetry-semantic-conventions==0.61b0  # when updating, also update in pyproject.toml
 
 -e instrumentation-genai/opentelemetry-instrumentation-anthropic
diff --git a/instrumentation-genai/opentelemetry-instrumentation-openai-agents-v2/pyproject.toml b/instrumentation-genai/opentelemetry-instrumentation-openai-agents-v2/pyproject.toml
@@ -25,9 +25,9 @@ classifiers = [
   "Programming Language :: Python :: 3.14",
 ]
 dependencies = [
-  "opentelemetry-api >= 1.39",
-  "opentelemetry-instrumentation >= 0.58b0",
-  "opentelemetry-semantic-conventions >= 0.60b0",
+  "opentelemetry-api >= 1.40",
+  "opentelemetry-instrumentation >= 0.61b0",
+  "opentelemetry-semantic-conventions >= 0.61b0",
   "opentelemetry-util-genai >= 0.4b0.dev"
 ]
 
diff --git a/instrumentation-genai/opentelemetry-instrumentation-openai-agents-v2/tests/requirements.oldest.txt b/instrumentation-genai/opentelemetry-instrumentation-openai-agents-v2/tests/requirements.oldest.txt
@@ -26,9 +26,9 @@ pytest-asyncio==0.21.0
 wrapt==1.16.0
 opentelemetry-exporter-otlp-proto-grpc~=1.30
 opentelemetry-exporter-otlp-proto-http~=1.30
-opentelemetry-api==1.39  # when updating, also update in pyproject.toml
-opentelemetry-sdk==1.39  # when updating, also update in pyproject.toml
-opentelemetry-semantic-conventions==0.60b0  # when updating, also update in pyproject.toml
+opentelemetry-api==1.40  # when updating, also update in pyproject.toml
+opentelemetry-sdk==1.40  # when updating, also update in pyproject.toml
+opentelemetry-semantic-conventions==0.61b0  # when updating, also update in pyproject.toml
 grpcio>=1.60.0; implementation_name != "pypy"
 grpcio<1.60.0; implementation_name == "pypy"
 
diff --git a/instrumentation-genai/opentelemetry-instrumentation-openai-v2/pyproject.toml b/instrumentation-genai/opentelemetry-instrumentation-openai-v2/pyproject.toml
@@ -25,9 +25,9 @@ classifiers = [
   "Programming Language :: Python :: 3.14",
 ]
 dependencies = [
-  "opentelemetry-api ~= 1.39",
-  "opentelemetry-instrumentation ~= 0.60b0",
-  "opentelemetry-semantic-conventions ~= 0.60b0",
+  "opentelemetry-api ~= 1.40",
+  "opentelemetry-instrumentation ~= 0.61b0",
+  "opentelemetry-semantic-conventions ~= 0.61b0",
   "opentelemetry-util-genai >= 0.4b0.dev",
 ]
 
diff --git a/instrumentation-genai/opentelemetry-instrumentation-openai-v2/tests/requirements.oldest.txt b/instrumentation-genai/opentelemetry-instrumentation-openai-v2/tests/requirements.oldest.txt
@@ -29,9 +29,9 @@ pytest-vcr==1.0.2
 pytest-asyncio==0.21.0
 wrapt==1.16.0
 opentelemetry-exporter-otlp-proto-http~=1.30
-opentelemetry-api==1.39  # when updating, also update in pyproject.toml
-opentelemetry-sdk==1.39  # when updating, also update in pyproject.toml
-opentelemetry-semantic-conventions==0.60b0  # when updating, also update in pyproject.toml
+opentelemetry-api==1.40  # when updating, also update in pyproject.toml
+opentelemetry-sdk==1.40  # when updating, also update in pyproject.toml
+opentelemetry-semantic-conventions==0.61b0  # when updating, also update in pyproject.toml
 
 -e instrumentation-genai/opentelemetry-instrumentation-openai-v2
 -e util/opentelemetry-util-genai
diff --git a/instrumentation-genai/opentelemetry-instrumentation-vertexai/pyproject.toml b/instrumentation-genai/opentelemetry-instrumentation-vertexai/pyproject.toml
@@ -25,9 +25,9 @@ classifiers = [
   "Programming Language :: Python :: 3.14",
 ]
 dependencies = [
-  "opentelemetry-api ~= 1.39",
-  "opentelemetry-instrumentation ~= 0.60b0",
-  "opentelemetry-semantic-conventions ~= 0.60b0",
+  "opentelemetry-api ~= 1.40",
+  "opentelemetry-instrumentation ~= 0.61b0",
+  "opentelemetry-semantic-conventions ~= 0.61b0",
   "opentelemetry-util-genai >= 0.4b0.dev, <0.5b0",
 ]
 
diff --git a/instrumentation-genai/opentelemetry-instrumentation-vertexai/tests/requirements.oldest.txt b/instrumentation-genai/opentelemetry-instrumentation-vertexai/tests/requirements.oldest.txt
@@ -65,10 +65,10 @@ grpcio>=1.75.1 ; python_version >= "3.14"
 shapely==2.0.6 ; python_version < "3.10"
 shapely==2.1.2 ; python_version >= "3.10"
 # when updating, also update in pyproject.toml
-opentelemetry-api==1.39
-opentelemetry-sdk==1.39
-opentelemetry-semantic-conventions==0.60b0
-opentelemetry-instrumentation==0.60b0
+opentelemetry-api==1.40
+opentelemetry-sdk==1.40
+opentelemetry-semantic-conventions==0.61b0
+opentelemetry-instrumentation==0.61b0
 # opentelemetry-util-genai[upload]==0.2b0
 -e util/opentelemetry-util-genai[upload]
 fsspec==2025.9.0
diff --git a/util/opentelemetry-util-genai/CHANGELOG.md b/util/opentelemetry-util-genai/CHANGELOG.md
@@ -12,6 +12,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   ([#4538](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/4538))
 - Apply attribute for sampling on instantiation of all invocation types.
   ([#4553](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/4553))
+- Minor code cleanup and changes in preparation of moving google's GenAI instrumentation
+  library to use this util library ([#4556](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/4556))
 
 ## Version 0.4b0 (2026-05-01)
 
diff --git a/util/opentelemetry-util-genai/README.rst b/util/opentelemetry-util-genai/README.rst
@@ -10,7 +10,7 @@ Key Components
 --------------
 
 - ``TelemetryHandler`` -- manages LLM invocation lifecycles (spans, metrics, events)
-- ``LLMInvocation`` and message types (``Text``, ``Reasoning``, ``Blob``, etc.) -- structured data model for GenAI interactions
+- ``InferenceInvocation`` 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
 
diff --git a/util/opentelemetry-util-genai/pyproject.toml b/util/opentelemetry-util-genai/pyproject.toml
@@ -25,9 +25,9 @@ classifiers = [
   "Programming Language :: Python :: 3.14",
 ]
 dependencies = [
-  "opentelemetry-instrumentation ~= 0.60b0",
-  "opentelemetry-semantic-conventions ~= 0.60b0",
-  "opentelemetry-api ~= 1.39",
+  "opentelemetry-instrumentation ~= 0.61b0",
+  "opentelemetry-semantic-conventions ~= 0.61b0",
+  "opentelemetry-api ~= 1.40",
 ]
 
 [project.entry-points.opentelemetry_genai_completion_hook]
diff --git a/util/opentelemetry-util-genai/src/opentelemetry/util/genai/_inference_invocation.py b/util/opentelemetry-util-genai/src/opentelemetry/util/genai/_inference_invocation.py
@@ -31,10 +31,7 @@
 )
 
 # TODO: Migrate to GenAI constants once available in semconv package
-_GEN_AI_USAGE_CACHE_CREATION_INPUT_TOKENS = (
-    "gen_ai.usage.cache_creation.input_tokens"
-)
-_GEN_AI_USAGE_CACHE_READ_INPUT_TOKENS = "gen_ai.usage.cache_read.input_tokens"
+_GEN_AI_REASONING_OUTPUT_TOKENS = "gen_ai.usage.reasoning.output_tokens"
 
 
 class InferenceInvocation(GenAIInvocation):
@@ -55,18 +52,21 @@ def __init__(
         request_model: str | None = None,
         server_address: str | None = None,
         server_port: int | None = None,
+        operation_name: str | None = None,
     ) -> None:
+        operation_name = (
+            operation_name or GenAI.GenAiOperationNameValues.CHAT.value
+        )
         """Use handler.start_inference(provider) or handler.inference(provider) instead of calling this directly."""
-        _operation_name = GenAI.GenAiOperationNameValues.CHAT.value
         super().__init__(
             tracer,
             metrics_recorder,
             logger,
             completion_hook,
-            operation_name=_operation_name,
-            span_name=f"{_operation_name} {request_model}"
+            operation_name=operation_name,
+            span_name=f"{operation_name} {request_model}"
             if request_model
-            else _operation_name,
+            else operation_name,
             span_kind=SpanKind.CLIENT,
         )
         self.provider = provider
@@ -81,7 +81,9 @@ def __init__(
         self.response_id: str | None = None
         self.finish_reasons: list[str] | None = None
         self.input_tokens: int | None = None
+        # Output tokens will ultimately be the sum of normal output tokens and thinking tokens.
         self.output_tokens: int | None = None
+        self.thinking_tokens: int | None = None
         self.temperature: float | None = None
         self.top_p: float | None = None
         self.frequency_penalty: float | None = None
@@ -129,6 +131,12 @@ def _get_base_attributes(self) -> dict[str, Any]:
 
     def _get_attributes(self) -> dict[str, Any]:
         attrs = self._get_base_attributes()
+        if self.output_tokens is None and self.thinking_tokens is None:
+            output_tokens = None
+        else:
+            output_tokens = (self.output_tokens or 0) + (
+                self.thinking_tokens or 0
+            )
         optional_attrs = (
             (GenAI.GEN_AI_REQUEST_TEMPERATURE, self.temperature),
             (GenAI.GEN_AI_REQUEST_TOP_P, self.top_p),
@@ -141,15 +149,19 @@ def _get_attributes(self) -> dict[str, Any]:
             (GenAI.GEN_AI_RESPONSE_MODEL, self.response_model_name),
             (GenAI.GEN_AI_RESPONSE_ID, self.response_id),
             (GenAI.GEN_AI_USAGE_INPUT_TOKENS, self.input_tokens),
-            (GenAI.GEN_AI_USAGE_OUTPUT_TOKENS, self.output_tokens),
+            (GenAI.GEN_AI_USAGE_OUTPUT_TOKENS, output_tokens),
             (
-                _GEN_AI_USAGE_CACHE_CREATION_INPUT_TOKENS,
+                GenAI.GEN_AI_USAGE_CACHE_CREATION_INPUT_TOKENS,
                 self.cache_creation_input_tokens,
             ),
             (
-                _GEN_AI_USAGE_CACHE_READ_INPUT_TOKENS,
+                GenAI.GEN_AI_USAGE_CACHE_READ_INPUT_TOKENS,
                 self.cache_read_input_tokens,
             ),
+            (
+                _GEN_AI_REASONING_OUTPUT_TOKENS,
+                self.thinking_tokens,
+            ),
         )
         attrs.update({k: v for k, v in optional_attrs if v is not None})
         return attrs
diff --git a/util/opentelemetry-util-genai/src/opentelemetry/util/genai/_invocation.py b/util/opentelemetry-util-genai/src/opentelemetry/util/genai/_invocation.py
@@ -209,13 +209,20 @@ def get_content_attributes(
             ContentCapturingMode.SPAN_AND_EVENT,
         )
     )
-    if mode not in allowed_modes:
-        return {}
 
     def serialize(items: Sequence[Any]) -> Any:
         dicts = [asdict(item) for item in items]
         return gen_ai_json_dumps(dicts) if for_span else dicts
 
+    # Tool definitions are always captured, the sem conv recommends adding params / description only
+    # when the content capture mode is set..
+    if mode not in allowed_modes:
+        return (
+            {GenAI.GEN_AI_TOOL_DEFINITIONS: serialize(tool_definitions)}
+            if tool_definitions
+            else {}
+        )
+
     optional_attrs = (
         (
             GenAI.GEN_AI_INPUT_MESSAGES,
diff --git a/util/opentelemetry-util-genai/src/opentelemetry/util/genai/_tool_invocation.py b/util/opentelemetry-util-genai/src/opentelemetry/util/genai/_tool_invocation.py
@@ -94,6 +94,7 @@ def _apply_finish(self, error: Error | None = None) -> None:
             (GenAI.GEN_AI_TOOL_CALL_ID, self.tool_call_id),
             (GenAI.GEN_AI_TOOL_TYPE, self.tool_type),
             (GenAI.GEN_AI_TOOL_DESCRIPTION, self.tool_description),
+            (GenAI.GEN_AI_TOOL_CALL_ARGUMENTS, self.arguments),
         )
         attributes: dict[str, Any] = {
             GenAI.GEN_AI_OPERATION_NAME: self._operation_name,
diff --git a/util/opentelemetry-util-genai/src/opentelemetry/util/genai/handler.py b/util/opentelemetry-util-genai/src/opentelemetry/util/genai/handler.py
@@ -141,6 +141,7 @@ def start_inference(
         request_model: str | None = None,
         server_address: str | None = None,
         server_port: int | None = None,
+        operation_name: str | None = None,
     ) -> InferenceInvocation:
         """Create and start an LLM inference invocation.
 
@@ -156,6 +157,7 @@ def start_inference(
             request_model=request_model,
             server_address=server_address,
             server_port=server_port,
+            operation_name=operation_name,
         )
 
     def start_llm(self, invocation: LLMInvocation) -> LLMInvocation:
diff --git a/util/opentelemetry-util-genai/tests/test_utils.py b/util/opentelemetry-util-genai/tests/test_utils.py
@@ -14,7 +14,7 @@
 )
 from opentelemetry.sdk._logs import LoggerProvider
 from opentelemetry.sdk._logs.export import (
-    InMemoryLogExporter,
+    InMemoryLogRecordExporter,
     SimpleLogRecordProcessor,
 )
 from opentelemetry.sdk.trace import ReadableSpan, TracerProvider
@@ -213,7 +213,7 @@ def setUp(self):
         tracer_provider.add_span_processor(
             SimpleSpanProcessor(self.span_exporter)
         )
-        self.log_exporter = InMemoryLogExporter()
+        self.log_exporter = InMemoryLogRecordExporter()
         logger_provider = LoggerProvider()
         logger_provider.add_log_record_processor(
             SimpleLogRecordProcessor(self.log_exporter)
diff --git a/util/opentelemetry-util-genai/tests/test_utils_events.py b/util/opentelemetry-util-genai/tests/test_utils_events.py
@@ -6,7 +6,7 @@
 
 from opentelemetry.sdk._logs import LoggerProvider
 from opentelemetry.sdk._logs.export import (
-    InMemoryLogExporter,
+    InMemoryLogRecordExporter,
     SimpleLogRecordProcessor,
 )
 from opentelemetry.sdk.trace import TracerProvider
@@ -40,7 +40,7 @@ def setUp(self):
         tracer_provider.add_span_processor(
             SimpleSpanProcessor(self.span_exporter)
         )
-        self.log_exporter = InMemoryLogExporter()
+        self.log_exporter = InMemoryLogRecordExporter()
         logger_provider = LoggerProvider()
         logger_provider.add_log_record_processor(
             SimpleLogRecordProcessor(self.log_exporter)

Original file line number	Diff line number	Diff line change
`@@ -25,9 +25,9 @@ classifiers = [`
`25`	`25`	`"Programming Language :: Python :: 3.14",`
`26`	`26`	`]`
`27`	`27`	`dependencies = [`
`28`		`- "opentelemetry-api ~= 1.39",`
`29`		`- "opentelemetry-instrumentation ~= 0.60b0",`
`30`		`- "opentelemetry-semantic-conventions ~= 0.60b0",`
	`28`	`+ "opentelemetry-api ~= 1.40",`
	`29`	`+ "opentelemetry-instrumentation ~= 0.61b0",`
	`30`	`+ "opentelemetry-semantic-conventions ~= 0.61b0",`
`31`	`31`	`"opentelemetry-util-genai >= 0.4b0.dev, <0.5b0",`
`32`	`32`	`]`
`33`	`33`