Merge branch 'main' into add_reasoning_token_attr

Author: lzchen

instrumentation-genai/AGENTS.md

@@ -19,7 +19,32 @@ This layer is responsible only for:
 Everything else (span creation, metric recording, event emission, context propagation)
 belongs in `util/opentelemetry-util-genai`.
 
-## 2. Invocation Pattern
+## 2. TelemetryHandler Initialization
+
+Construct `TelemetryHandler` once inside `_instrument()`, passing all OTel providers and the
+completion hook. Always prefer an explicitly injected hook (`kwargs.get("completion_hook")`)
+over the entry-point hook loaded by `load_completion_hook()`, so test code can override the
+hook without touching the environment.
+
+```python
+from opentelemetry.util.genai.completion_hook import load_completion_hook
+from opentelemetry.util.genai.handler import TelemetryHandler
+
+def _instrument(self, **kwargs):
+    tracer_provider = kwargs.get("tracer_provider")
+    meter_provider = kwargs.get("meter_provider")
+    logger_provider = kwargs.get("logger_provider")
+
+    handler = TelemetryHandler(
+        tracer_provider=tracer_provider,
+        meter_provider=meter_provider,
+        logger_provider=logger_provider,
+        completion_hook=kwargs.get("completion_hook") or load_completion_hook(),
+    )
+    # pass handler to each patch/wrapper function
+```
+
+## 3. Invocation Pattern
 
 Use `start_*()` and control span lifetime manually:
 
@@ -36,7 +61,7 @@ except Exception as exc:
     raise
 ```
 
-## 3. Semantic conventions
+## 4. Semantic conventions
 
 Attributes, spans, events, and metrics follow the
 [GenAI semantic conventions](https://github.com/open-telemetry/semantic-conventions/tree/main/docs/gen-ai).
@@ -45,14 +70,14 @@ Do not emit signals that are not covered by semconv.
 `gen_ai.*` attribute names and the enums for well-known values (e.g. `GenAiOutputTypeValues` for
 `gen_ai.output.type`) live in `opentelemetry.semconv._incubating.attributes.gen_ai_attributes`.
 
-## 4. Tests
+## 5. Tests
 
 - Use VCR cassettes for provider calls. Do not skip tests when an API key is missing.
 - Cover streaming and non-streaming variants when both exist.
 - Cover error scenarios, at minimum: provider error / endpoint unavailable, stream interrupted by
   network, stream closed early by the caller.
 
-## 5. Examples
+## 6. Examples
 
 New instrumentations ship a minimal example under the package's `examples/` directory, with
 both a `manual/` setup and a `zero-code/` (auto-instrumentation) variant.

instrumentation-genai/opentelemetry-instrumentation-openai-v2/CHANGELOG.md

@@ -35,6 +35,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Add strongly typed Responses API extractors with validation and content
   extraction improvements
   ([#4337](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/4337))
+- Add completion hook support.
+  ([#4315](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/4315))
+- Fix `response_format` handling: map `json_object`/`json_schema` to `json` output type.
+  ([#4315](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/4315))
+- Skip attribute values with `openai.Omit` value.
+  ([#4315](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/4315))
 - Default empty string for `gen_ai.request.model` attribute on missing model.
   ([#4494](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/4494))
 

instrumentation-genai/opentelemetry-instrumentation-openai-v2/README.rst

@@ -98,6 +98,23 @@ are not captured by default. To capture message content as log events, set the e
 - ``span_and_event`` - Used to enable content capturing on both *span* and *event* attributes when
   `latest experimental features <#enabling-the-latest-experimental-features>`_ are enabled.
 
+Uploading prompts and completions
+*********************************
+
+To enable the built-in upload hook, set:
+
+- ``OTEL_INSTRUMENTATION_GENAI_COMPLETION_HOOK=upload``
+- ``OTEL_INSTRUMENTATION_GENAI_UPLOAD_BASE_PATH`` to an ``fsspec``-compatible URI/path
+  (e.g. ``/path/to/prompts`` or ``gs://my_bucket``).
+
+Install the ``upload`` extra to pull in ``fsspec``::
+
+    pip install opentelemetry-util-genai[upload]
+
+See the `opentelemetry-util-genai
+<https://github.com/open-telemetry/opentelemetry-python-contrib/blob/main/util/opentelemetry-util-genai/README.rst>`_
+for additional options.
+
 Enabling the latest experimental features
 ***********************************************
 

instrumentation-genai/opentelemetry-instrumentation-openai-v2/examples/manual/.env

@@ -29,3 +29,8 @@ OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=span_only
 #
 # Comment out if you want to use semantic conventions of version 1.30.0.
 OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental
+
+# Uncomment to upload prompts and responses to an fsspec-compatible
+# destination instead of or in addition to recording them inline on spans/events.
+# OTEL_INSTRUMENTATION_GENAI_COMPLETION_HOOK=upload
+# OTEL_INSTRUMENTATION_GENAI_UPLOAD_BASE_PATH=/path/to/prompts

instrumentation-genai/opentelemetry-instrumentation-openai-v2/examples/manual/README.rst

@@ -13,6 +13,7 @@ Note: `.env <.env>`_ file configures additional environment variables:
 
 - ``OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=span_only`` configures OpenAI instrumentation to capture prompt and completion contents on *span* attributes.
 - ``OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental`` enables latest experimental features.
+- ``OTEL_INSTRUMENTATION_GENAI_COMPLETION_HOOK`` (commented out) - uncomment along with ``OTEL_INSTRUMENTATION_GENAI_UPLOAD_BASE_PATH`` to upload prompts and completions to an ``fsspec``-compatible destination instead of recording them inline. Also uncomment the ``opentelemetry-util-genai[upload]`` line in `requirements.txt <requirements.txt>`_ and reinstall.
 
 Setup
 -----
@@ -41,3 +42,18 @@ Run the example like this:
 
 You should see a poem generated by OpenAI while traces and logs export to your
 configured observability tool.
+
+Custom completion hook
+----------------------
+
+`custom_hook.py <custom_hook.py>`_ is a variant of ``main.py`` that passes a
+custom ``CompletionHook`` implementation programmatically via
+``OpenAIInstrumentor().instrument(completion_hook=...)``. The example hook
+prints prompts and completions to stdout; real hooks typically forward content
+to external storage and record reference URIs on the span/log_record.
+
+Run it the same way:
+
+::
+
+    dotenv run -- python custom_hook.py

instrumentation-genai/opentelemetry-instrumentation-openai-v2/examples/manual/custom_hook.py

@@ -0,0 +1,95 @@
+# pylint: skip-file
+"""Same as main.py, but instruments OpenAI with a custom CompletionHook
+that prints prompts and completions to stdout.
+
+Run with: dotenv run -- python custom_hook.py
+"""
+
+import os
+
+from openai import OpenAI
+
+from opentelemetry import _logs, metrics, trace
+from opentelemetry.exporter.otlp.proto.grpc._log_exporter import (
+    OTLPLogExporter,
+)
+from opentelemetry.exporter.otlp.proto.grpc.metric_exporter import (
+    OTLPMetricExporter,
+)
+from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import (
+    OTLPSpanExporter,
+)
+from opentelemetry.instrumentation.openai_v2 import OpenAIInstrumentor
+from opentelemetry.sdk._logs import LoggerProvider
+from opentelemetry.sdk._logs.export import BatchLogRecordProcessor
+from opentelemetry.sdk.metrics import MeterProvider
+from opentelemetry.sdk.metrics.export import PeriodicExportingMetricReader
+from opentelemetry.sdk.trace import TracerProvider
+from opentelemetry.sdk.trace.export import BatchSpanProcessor
+from opentelemetry.util.genai.completion_hook import CompletionHook
+from opentelemetry.util.genai.types import (
+    InputMessage,
+    MessagePart,
+    OutputMessage,
+    ToolDefinition,
+)
+
+
+class PrintCompletionHook(CompletionHook):
+    """Minimal CompletionHook that prints inputs/outputs to stdout.
+
+    Real hooks typically forward content to external storage (object store,
+    database, etc.) and record reference URIs on the span/log_record.
+    """
+
+    def on_completion(
+        self,
+        *,
+        inputs: list[InputMessage],
+        outputs: list[OutputMessage],
+        system_instruction: list[MessagePart],
+        tool_definitions: list[ToolDefinition] | None = None,
+        span=None,
+        log_record=None,
+    ) -> None:
+        print(f"[hook] inputs: {inputs}")
+        print(f"[hook] outputs: {outputs}")
+
+
+trace.set_tracer_provider(TracerProvider())
+trace.get_tracer_provider().add_span_processor(
+    BatchSpanProcessor(OTLPSpanExporter())
+)
+
+_logs.set_logger_provider(LoggerProvider())
+_logs.get_logger_provider().add_log_record_processor(
+    BatchLogRecordProcessor(OTLPLogExporter())
+)
+
+metrics.set_meter_provider(
+    MeterProvider(
+        metric_readers=[
+            PeriodicExportingMetricReader(OTLPMetricExporter()),
+        ]
+    )
+)
+
+OpenAIInstrumentor().instrument(completion_hook=PrintCompletionHook())
+
+
+def main():
+    client = OpenAI()
+    chat_completion = client.chat.completions.create(
+        model=os.getenv("CHAT_MODEL", "gpt-4o-mini"),
+        messages=[
+            {
+                "role": "user",
+                "content": "Write a short poem on OpenTelemetry.",
+            },
+        ],
+    )
+    print(chat_completion.choices[0].message.content)
+
+
+if __name__ == "__main__":
+    main()

instrumentation-genai/opentelemetry-instrumentation-openai-v2/examples/manual/requirements.txt

@@ -3,3 +3,7 @@ openai~=1.57.3
 opentelemetry-sdk~=1.36.0
 opentelemetry-exporter-otlp-proto-grpc~=1.36.0
 opentelemetry-instrumentation-openai-v2~=2.1b0
+
+# Uncomment to enable the upload completion hook (pulls in fsspec).
+# Required when OTEL_INSTRUMENTATION_GENAI_COMPLETION_HOOK=upload.
+# opentelemetry-util-genai[upload]

instrumentation-genai/opentelemetry-instrumentation-openai-v2/examples/zero-code/.env

@@ -32,3 +32,8 @@ OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=span_only
 #
 # Comment out if you want to use semantic conventions of version 1.30.0.
 OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental
+
+# Uncomment to upload prompts and responses to an fsspec-compatible
+# destination instead of or in addition to recording them inline on spans/events.
+# OTEL_INSTRUMENTATION_GENAI_COMPLETION_HOOK=upload
+# OTEL_INSTRUMENTATION_GENAI_UPLOAD_BASE_PATH=/path/to/prompts

instrumentation-genai/opentelemetry-instrumentation-openai-v2/examples/zero-code/README.rst

@@ -15,6 +15,7 @@ Note: `.env <.env>`_ file configures additional environment variables:
 - ``OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=span_only`` configures OpenAI instrumentation to capture prompt and completion contents on *span* attributes.
 - ``OTEL_LOGS_EXPORTER=otlp`` to specify exporter type.
 - ``OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental`` enables latest experimental features.
+- ``OTEL_INSTRUMENTATION_GENAI_COMPLETION_HOOK`` (commented out) - uncomment along with ``OTEL_INSTRUMENTATION_GENAI_UPLOAD_BASE_PATH`` to upload prompts and completions to an ``fsspec``-compatible destination instead of recording them inline. Also uncomment the ``opentelemetry-util-genai[upload]`` line in `requirements.txt <requirements.txt>`_ and reinstall.
 
 Setup
 -----

instrumentation-genai/opentelemetry-instrumentation-openai-v2/examples/zero-code/requirements.txt

@@ -4,3 +4,7 @@ opentelemetry-sdk~=1.36.0
 opentelemetry-exporter-otlp-proto-grpc~=1.36.0
 opentelemetry-distro~=0.57b0
 opentelemetry-instrumentation-openai-v2~=2.1b0
+
+# Uncomment to enable the upload completion hook (pulls in fsspec).
+# Required when OTEL_INSTRUMENTATION_GENAI_COMPLETION_HOOK=upload.
+# opentelemetry-util-genai[upload]