GenAI Utils | Initial Helpers for Inference

util/opentelemetry-util-genai/CHANGELOG.md

@@ -5,4 +5,13 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## Unreleased
+## [Unreleased]
+
+### Added
+
+- Generate Spans for LLM invocations
+- Generate Metrics for LLM invocations
+- Generate Logs for LLM invocations
+- Helper functions for starting and finishing LLM invocations
+
+

util/opentelemetry-util-genai/README.rst

@@ -1,11 +1,43 @@
 OpenTelemetry Util for GenAI
-=======================
+============================
 
 
 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 provides these span attributes.
+-> gen_ai.provider.name: Str(openai)
+-> gen_ai.operation.name: Str(chat)
+-> gen_ai.framework: Str(langchain)
+-> gen_ai.system: Str(openai) # deprecated
+-> 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\": \"user\", \"content\": \"hello world\"}]")
+
+
+This package also provides these metric attributes.
+Token Usage Metrics:
+-> gen_ai.provider.name: Str(openai)
+-> gen_ai.operation.name: Str(chat)
+-> gen_ai.framework: Str(langchain)
+-> gen_ai.request.model: Str(gpt-3.5-turbo)
+-> gen_ai.response.model: Str(gpt-3.5-turbo-0125)
+-> gen_ai.usage.input_tokens: Int(24)
+-> gen_ai.usage.output_tokens: Int(7)
+-> gen_ai.token.type: Str(input|output)
+
+Duration Metrics:
+-> gen_ai.provider.name: Str(openai)
+-> gen_ai.operation.name: Str(chat)
+-> gen_ai.framework: Str(langchain)
+-> gen_ai.request.model: Str(gpt-3.5-turbo)
+-> gen_ai.response.model: Str(gpt-3.5-turbo-0125)
+
 Installation
 ------------
 

util/opentelemetry-util-genai/pyproject.toml

@@ -25,9 +25,9 @@ classifiers = [
   "Programming Language :: Python :: 3.13",
 ]
 dependencies = [
-  "opentelemetry-instrumentation ~= 0.51b0",
-  "opentelemetry-semantic-conventions ~= 0.51b0",
-  "opentelemetry-api>=1.31.0",
+  "opentelemetry-instrumentation ~= 0.57b0",
+  "opentelemetry-semantic-conventions ~= 0.57b0",
+  "opentelemetry-api>=1.36.0",
 ]
 
 [project.optional-dependencies]

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/data.py

@@ -0,0 +1,69 @@
+# 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.
+
+from dataclasses import dataclass
+from typing import List, Literal, Optional, Type, TypedDict
+
+
+class TextPart(TypedDict):
+    type: Literal["text"]
+    content: str
+
+
+# Keep room for future parts without changing the return type
+# addition of tools can use Part = Union[TextPart, ToolPart]
+Part = TextPart
+
+
+class OtelMessage(TypedDict):
+    role: str
+    # role: Literal["user", "assistant", "system", "tool", "tool_message"] # TODO: check semconvs for allowed roles
+    parts: List[Part]
+
+
+@dataclass
+class Message:
+    content: str
+    type: str
+    name: str
+
+    def _to_semconv_dict(self) -> OtelMessage:
+        """Convert the message to a dictionary suitable for OpenTelemetry semconvs.
+
+        Ref: https://github.com/open-telemetry/semantic-conventions/blob/main/docs/registry/attributes/gen-ai.md#gen-ai-input-messages
+        """
+
+        # TODO: Support tool_call and tool_call response
+        return {
+            "role": self.type,
+            "parts": [
+                {
+                    "content": self.content,
+                    "type": "text",
+                }
+            ],
+        }
+
+
+@dataclass
+class ChatGeneration:
+    content: str
+    type: str
+    finish_reason: Optional[str] = None
+
+
+@dataclass
+class Error:
+    message: str
+    type: Type[BaseException]