update documentation

Author: keith-decker

util/opentelemetry-util-genai/README.rst

@@ -8,16 +8,9 @@ while providing standardization for generating both types of otel, "spans and me
 
 This package provides these span attributes.
 -> gen_ai.operation.name: Str(chat)
+-> gen_ai.provider.name: Str(openai)
 -> gen_ai.system: Str(ChatOpenAI)
 -> gen_ai.request.model: Str(gpt-3.5-turbo)
--> gen_ai.request.top_p: Double(0.9)
--> gen_ai.request.frequency_penalty: Double(0.5)
--> gen_ai.request.presence_penalty: Double(0.5)
--> gen_ai.request.stop_sequences: Slice(["\n","Human:","AI:"])
--> gen_ai.request.seed: Int(100)
--> gen_ai.request.max_tokens: Int(100)
--> gen_ai.provider.name: Str(openai)
--> gen_ai.request.temperature: Double(0.1)
 -> gen_ai.response.finish_reasons: Slice(["stop"])
 -> gen_ai.response.model: Str(gpt-3.5-turbo-0125)
 -> gen_ai.response.id: Str(chatcmpl-Bz8yrvPnydD9pObv625n2CGBPHS13)

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

@@ -1,3 +1,17 @@
+# 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
 
 

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

@@ -12,6 +12,26 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+"""
+Emitters for GenAI telemetry instrumentation.
+
+This module defines classes and utilities for mapping GenAI (Generative AI) invocations
+to OpenTelemetry spans, metrics, and events. Emitters manage the lifecycle of telemetry
+data for LLM (Large Language Model) operations, including success and error reporting.
+
+Classes:
+    BaseEmitter: Abstract base class for GenAI telemetry emitters.
+    SpanMetricEventEmitter: Emits spans, metrics, and events for full telemetry.
+    SpanMetricEmitter: Emits only spans and metrics (no events).
+
+Functions:
+    _get_property_value: Utility to extract property values from objects or dicts.
+    _message_to_log_record: Converts a GenAI message to an OpenTelemetry LogRecord.
+    _chat_generation_to_log_record: Converts a chat generation to a LogRecord.
+    _get_metric_attributes: Builds metric attributes for telemetry reporting.
+
+"""
+
 from dataclasses import dataclass, field
 from typing import Dict, List, Optional
 from uuid import UUID
@@ -214,17 +234,6 @@ def init(self, invocation: LLMInvocation):
 
         for message in invocation.messages:
             system = invocation.attributes.get("system")
-            # Event API is deprecated, use structured logs instead
-            # event = _message_to_event(
-            #     message=message,
-            #     provider_name=system,
-            #     framework=invocation.attributes.get("framework"),
-            # )
-            # if event and self._event_logger:
-            #     self._event_logger.emit(
-            #         event
-            #     )
-
             log = _message_to_log_record(
                 message=message,
                 provider_name=system,
@@ -280,15 +289,6 @@ def emit(self, invocation: LLMInvocation):
             for index, chat_generation in enumerate(
                 invocation.chat_generations
             ):
-                # Event API is deprecated. Use structured logs instead
-                # event = _chat_generation_to_event(
-                #         chat_generation, index, system, framework
-                #     )
-                # if event and self._event_logger:
-                #     self._event_logger.emit(
-                #         event
-                #     )
-
                 log = _chat_generation_to_log_record(
                     chat_generation,
                     index,

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

@@ -12,6 +12,28 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+"""
+Telemetry handler for GenAI invocations.
+
+This module provides the `TelemetryHandler` class, which manages the lifecycle of
+GenAI (Generative AI) invocations and emits telemetry data as spans, metrics, and events.
+It supports starting, stopping, and failing LLM invocations,
+and provides module-level convenience functions for these operations.
+
+Classes:
+    TelemetryHandler: Manages GenAI invocation lifecycles and emits telemetry.
+
+Functions:
+    get_telemetry_handler: Returns a singleton TelemetryHandler instance.
+    llm_start: Starts a new LLM invocation.
+    llm_stop: Stops an LLM invocation and emits telemetry.
+    llm_fail: Marks an LLM invocation as failed and emits error telemetry.
+
+Usage:
+    Use the module-level functions (`llm_start`, `llm_stop`, `llm_fail`) to
+    instrument GenAI invocations for telemetry collection.
+"""
+
 import time
 from threading import Lock
 from typing import Any, List, Optional

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

@@ -1,3 +1,17 @@
+# 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 opentelemetry.metrics import Histogram, Meter
 from opentelemetry.semconv._incubating.metrics import gen_ai_metrics