diff --git a/instrumentation-genai/opentelemetry-instrumentation-google-genai/CHANGELOG.md b/instrumentation-genai/opentelemetry-instrumentation-google-genai/CHANGELOG.md index bdc05dc98b..1ce5dabaa1 100644 --- a/instrumentation-genai/opentelemetry-instrumentation-google-genai/CHANGELOG.md +++ b/instrumentation-genai/opentelemetry-instrumentation-google-genai/CHANGELOG.md @@ -1,55 +1,55 @@ -# Changelog - -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 - --Add `gen_ai.usage.cache_read.input_tokens` attribute to capture cached tokens on spans/events when the experimental sem conv flag is set. ([#4313](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/4313)) - -## Version 0.7b0 (2026-02-20) -- Fix bug in how tokens are counted when using the streaming `generateContent` method. ([#4152](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/4152)). -- Add `gen_ai.tool.definitions` attribute to `gen_ai.client.inference.operation.details` log event ([#4142](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/4142)). -- Add `gen_ai.tool_definitions` to completion hook ([#4181](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/4181)) - - -## Version 0.6b0 (2026-01-27) - -- Enable the addition of custom attributes to the `generate_content {model.name}` span via the Context API. ([#3961](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/3961)). -- Enable the addition of custom attributes to `gen_ai.client.inference.operation.details` log events ([#4103](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/4103)). - -## Version 0.5b0 (2025-12-11) - -- Ensure log event is written and completion hook is called even when model call results in exception. Put new -log event (` gen_ai.client.inference.operation.details`) behind the flag `OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental`. -Ensure same sem conv attributes are on the log and span. Fix an issue where the instrumentation would crash when a pydantic.BaseModel class was passed as the response schema ([#3905](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/3905)). -- Add the `GEN_AI_OUTPUT_TYPE` sem conv request attributes to events/spans generated in the stable instrumentation. This was added pre sem conv 1.36 so it should be in the stable instrumentation. Fix a bug in how system instructions were recorded in the `gen_ai.system.message` log event. It will now always be recorded as `{"content" : "text of system instructions"}`. See ([#4011](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/4011)). - -## Version 0.4b0 (2025-10-16) - -- Implement the new semantic convention changes made in https://github.com/open-telemetry/semantic-conventions/pull/2179. -A single event (`gen_ai.client.inference.operation.details`) is used to capture Chat History. This is opt-in, -an environment variable OTEL_SEMCONV_STABILITY_OPT_IN needs to be set to `gen_ai_latest_experimental` to see them ([#3386](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/3386)) -- Support CompletionHook for upload to cloud storage. - -## Version 0.3b0 (2025-07-08) - -- Add automatic instrumentation to tool call functions ([#3446](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/3446)) - -## Version 0.2b0 (2025-04-28) - -- Add more request configuration options to the span attributes ([#3374](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/3374)) -- Restructure tests to keep in line with repository conventions ([#3344](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/3344)) - -- Fix [bug](https://github.com/open-telemetry/opentelemetry-python-contrib/issues/3416) where -span attribute `gen_ai.response.finish_reasons` is empty ([#3417](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/3417)) - -## Version 0.1b0 (2025-03-05) - -- Add support for async and streaming. - ([#3298](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/3298)) - -Create an initial version of Open Telemetry instrumentation for github.com/googleapis/python-genai. -([#3256](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/3256)) +# Changelog + +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 + +-Add `gen_ai.usage.cache_read.input_tokens` attribute to capture cached tokens on spans/events when the experimental sem conv flag is set. ([#4313](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/4313)) + +## Version 0.7b0 (2026-02-20) +- Fix bug in how tokens are counted when using the streaming `generateContent` method. ([#4152](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/4152)). +- Add `gen_ai.tool.definitions` attribute to `gen_ai.client.inference.operation.details` log event ([#4142](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/4142)). +- Add `gen_ai.tool_definitions` to completion hook ([#4181](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/4181)) + + +## Version 0.6b0 (2026-01-27) + +- Enable the addition of custom attributes to the `generate_content {model.name}` span via the Context API. ([#3961](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/3961)). +- Enable the addition of custom attributes to `gen_ai.client.inference.operation.details` log events ([#4103](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/4103)). + +## Version 0.5b0 (2025-12-11) + +- Ensure log event is written and completion hook is called even when model call results in exception. Put new +log event (` gen_ai.client.inference.operation.details`) behind the flag `OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental`. +Ensure same sem conv attributes are on the log and span. Fix an issue where the instrumentation would crash when a pydantic.BaseModel class was passed as the response schema ([#3905](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/3905)). +- Add the `GEN_AI_OUTPUT_TYPE` sem conv request attributes to events/spans generated in the stable instrumentation. This was added pre sem conv 1.36 so it should be in the stable instrumentation. Fix a bug in how system instructions were recorded in the `gen_ai.system.message` log event. It will now always be recorded as `{"content" : "text of system instructions"}`. See ([#4011](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/4011)). + +## Version 0.4b0 (2025-10-16) + +- Implement the new semantic convention changes made in https://github.com/open-telemetry/semantic-conventions/pull/2179. +A single event (`gen_ai.client.inference.operation.details`) is used to capture Chat History. This is opt-in, +an environment variable OTEL_SEMCONV_STABILITY_OPT_IN needs to be set to `gen_ai_latest_experimental` to see them ([#3386](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/3386)) +- Support CompletionHook for upload to cloud storage. + +## Version 0.3b0 (2025-07-08) + +- Add automatic instrumentation to tool call functions ([#3446](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/3446)) + +## Version 0.2b0 (2025-04-28) + +- Add more request configuration options to the span attributes ([#3374](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/3374)) +- Restructure tests to keep in line with repository conventions ([#3344](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/3344)) + +- Fix [bug](https://github.com/open-telemetry/opentelemetry-python-contrib/issues/3416) where +span attribute `gen_ai.response.finish_reasons` is empty ([#3417](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/3417)) + +## Version 0.1b0 (2025-03-05) + +- Add support for async and streaming. + ([#3298](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/3298)) + +Create an initial version of Open Telemetry instrumentation for github.com/googleapis/python-genai. +([#3256](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/3256)) diff --git a/instrumentation-genai/opentelemetry-instrumentation-google-genai/README.rst b/instrumentation-genai/opentelemetry-instrumentation-google-genai/README.rst index fc8e248b33..cc28614a42 100644 --- a/instrumentation-genai/opentelemetry-instrumentation-google-genai/README.rst +++ b/instrumentation-genai/opentelemetry-instrumentation-google-genai/README.rst @@ -1,107 +1,132 @@ -OpenTelemetry Google GenAI SDK Instrumentation -============================================== - -|pypi| - -.. |pypi| image:: https://badge.fury.io/py/opentelemetry-instrumentation-google-genai.svg - :target: https://pypi.org/project/opentelemetry-instrumentation-google-genai/ - -This library adds instrumentation to the `Google GenAI SDK library `_ -to emit telemetry data following `Semantic Conventions for GenAI systems `_. -It adds trace spans for GenAI operations, events/logs for recording prompts/responses, and emits metrics that describe the -GenAI operations in aggregate. - - -Experimental ------------- - -This package is still experimental. The instrumentation may not be complete or correct just yet. - -Please see "TODOS.md" for a list of known defects/TODOs that are blockers to package stability. - - -Installation ------------- - -If your application is already instrumented with OpenTelemetry, add this -package to your requirements. -:: - - pip install opentelemetry-instrumentation-google-genai - -If you don't have a Google GenAI SDK application, yet, try our `examples `_. - -Check out `zero-code example `_ for a quick start. - - -Usage ------ - -This section describes how to set up Google GenAI SDK instrumentation if you're setting OpenTelemetry up manually. -Check out the `manual example `_ for more details. - - -Instrumenting all clients -************************* - -When using the instrumentor, all clients will automatically trace GenAI ``generate_content`` operations. -You can also optionally capture prompts and responses as log events. - -Make sure to configure OpenTelemetry tracing, logging, metrics, and events to capture all telemetry emitted by the instrumentation. - -.. code-block:: python - - from opentelemetry.instrumentation.google_genai import GoogleGenAiSdkInstrumentor - from google.genai import Client - - GoogleGenAiSdkInstrumentor().instrument() - - client = Client() - response = client.models.generate_content( - model="gemini-1.5-flash-002", - contents="Write a short poem on OpenTelemetry." - ) - - -Limitations -*********** - -When using the Google GenAI SDK with automatic function calling enabled, -the OpenTelemetry instrumentation creates a span only for the top-level -``generate_content`` call. - -Internal model or tool calls triggered automatically by the SDK are executed -within the SDK internals and are not traced as separate spans. - - -Enabling message content -************************* - -Message content such as the contents of the prompt and response -are not captured by default. To capture message content as log events, set the environment variable -``OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT`` to ``true``. - - -Uninstrument -************ - -To uninstrument clients, call the uninstrument method: - -.. code-block:: python - - from opentelemetry.instrumentation.google_genai import GoogleGenAiSdkInstrumentor - - GoogleGenAiSdkInstrumentor().instrument() - # ... - - # Uninstrument all clients - GoogleGenAiSdkInstrumentor().uninstrument() - - -References ----------- -* `Google Gen AI SDK Documentation `_ -* `Google Gen AI SDK on GitHub `_ -* `Using Vertex AI with Google Gen AI SDK `_ -* `OpenTelemetry Project `_ -* `OpenTelemetry Python Examples `_ +OpenTelemetry Google GenAI SDK Instrumentation +============================================== + +|pypi| + +.. |pypi| image:: https://badge.fury.io/py/opentelemetry-instrumentation-google-genai.svg + :target: https://pypi.org/project/opentelemetry-instrumentation-google-genai/ + +This library adds instrumentation to the `Google GenAI SDK library `_ +to emit telemetry data following `Semantic Conventions for GenAI systems `_. +It adds trace spans for GenAI operations, events/logs for recording prompts/responses, and emits metrics that describe the +GenAI operations in aggregate. + + +Experimental +------------ + +This package is still experimental. The instrumentation may not be complete or correct just yet. + +Please see "TODOS.md" for a list of known defects/TODOs that are blockers to package stability. + + +Installation +------------ + +If your application is already instrumented with OpenTelemetry, add this +package to your requirements. +:: + + pip install opentelemetry-instrumentation-google-genai + +If you don't have a Google GenAI SDK application, yet, try our `examples `_. + +Check out `zero-code example `_ for a quick start. + + +Usage +----- + +This section describes how to set up Google GenAI SDK instrumentation if you're setting OpenTelemetry up manually. +Check out the `manual example `_ for more details. + + +Instrumenting all clients +************************* + +When using the instrumentor, all clients will automatically trace GenAI ``generate_content`` operations. +You can also optionally capture prompts and responses as log events. + +Make sure to configure OpenTelemetry tracing, logging, metrics, and events to capture all telemetry emitted by the instrumentation. + +.. code-block:: python + + from opentelemetry.instrumentation.google_genai import GoogleGenAiSdkInstrumentor + from google.genai import Client + + GoogleGenAiSdkInstrumentor().instrument() + + client = Client() + response = client.models.generate_content( + model="gemini-1.5-flash-002", + contents="Write a short poem on OpenTelemetry." + ) + + +Limitations +*********** + +When using the Google GenAI SDK with automatic function calling enabled, +the OpenTelemetry instrumentation creates a span only for the top-level +``generate_content`` call. + +Internal model or tool calls triggered automatically by the SDK are executed +within the SDK internals and are not traced as separate spans. + + +Enabling message content +************************* + +Message content such as the contents of the prompt and response +are not captured by default. To capture message content as log events, set the environment variable +``OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT`` to ``true``. + +Configuration recording +*********************** + +The instrumentation can optionally record ``GenerateContentConfig`` parameters +as span attributes under the ``gcp.gen_ai.operation.config.*`` namespace. + +By default, no config fields are recorded. You can control which fields are +captured using the following environment variables: + +* ``OTEL_GOOGLE_GENAI_GENERATE_CONTENT_CONFIG_INCLUDES`` — A comma-separated + list of config field names to include in the span attributes. For example: + + .. code-block:: bash + + export OTEL_GOOGLE_GENAI_GENERATE_CONTENT_CONFIG_INCLUDES=temperature,max_output_tokens + +* ``OTEL_GOOGLE_GENAI_GENERATE_CONTENT_CONFIG_EXCLUDES`` — A comma-separated + list of config field names to exclude from the span attributes: + + .. code-block:: bash + + export OTEL_GOOGLE_GENAI_GENERATE_CONTENT_CONFIG_EXCLUDES=stop_sequences + +If both variables are set, the includes list is applied first, then the +excludes list filters the result further. + +Uninstrument +************ + +To uninstrument clients, call the uninstrument method: + +.. code-block:: python + + from opentelemetry.instrumentation.google_genai import GoogleGenAiSdkInstrumentor + + GoogleGenAiSdkInstrumentor().instrument() + # ... + + # Uninstrument all clients + GoogleGenAiSdkInstrumentor().uninstrument() + + +References +---------- +* `Google Gen AI SDK Documentation `_ +* `Google Gen AI SDK on GitHub `_ +* `Using Vertex AI with Google Gen AI SDK `_ +* `OpenTelemetry Project `_ +* `OpenTelemetry Python Examples `_