Skip to content

Commit 4cbeb1c

Browse files
RiyaChaturvedi37RiyaChaturvedi37
committed
docs(google-genai): document config recording environment variables
Refs #3438 Signed-off-by: RiyaChaturvedi37 <chaturvediriya37@gmail.com>
1 parent bca3c85 commit 4cbeb1c

1 file changed

Lines changed: 132 additions & 107 deletions

File tree

  • instrumentation-genai/opentelemetry-instrumentation-google-genai

‎instrumentation-genai/opentelemetry-instrumentation-google-genai/README.rst‎

Lines changed: 132 additions & 107 deletions
Original file line numberDiff line numberDiff line change
@@ -1,107 +1,132 @@
1-
OpenTelemetry Google GenAI SDK Instrumentation
2-
==============================================
3-
4-
|pypi|
5-
6-
.. |pypi| image:: https://badge.fury.io/py/opentelemetry-instrumentation-google-genai.svg
7-
:target: https://pypi.org/project/opentelemetry-instrumentation-google-genai/
8-
9-
This library adds instrumentation to the `Google GenAI SDK library <https://pypi.org/project/google-genai/>`_
10-
to emit telemetry data following `Semantic Conventions for GenAI systems <https://opentelemetry.io/docs/specs/semconv/gen-ai/>`_.
11-
It adds trace spans for GenAI operations, events/logs for recording prompts/responses, and emits metrics that describe the
12-
GenAI operations in aggregate.
13-
14-
15-
Experimental
16-
------------
17-
18-
This package is still experimental. The instrumentation may not be complete or correct just yet.
19-
20-
Please see "TODOS.md" for a list of known defects/TODOs that are blockers to package stability.
21-
22-
23-
Installation
24-
------------
25-
26-
If your application is already instrumented with OpenTelemetry, add this
27-
package to your requirements.
28-
::
29-
30-
pip install opentelemetry-instrumentation-google-genai
31-
32-
If you don't have a Google GenAI SDK application, yet, try our `examples <examples>`_.
33-
34-
Check out `zero-code example <examples/zero-code>`_ for a quick start.
35-
36-
37-
Usage
38-
-----
39-
40-
This section describes how to set up Google GenAI SDK instrumentation if you're setting OpenTelemetry up manually.
41-
Check out the `manual example <examples/manual>`_ for more details.
42-
43-
44-
Instrumenting all clients
45-
*************************
46-
47-
When using the instrumentor, all clients will automatically trace GenAI ``generate_content`` operations.
48-
You can also optionally capture prompts and responses as log events.
49-
50-
Make sure to configure OpenTelemetry tracing, logging, metrics, and events to capture all telemetry emitted by the instrumentation.
51-
52-
.. code-block:: python
53-
54-
from opentelemetry.instrumentation.google_genai import GoogleGenAiSdkInstrumentor
55-
from google.genai import Client
56-
57-
GoogleGenAiSdkInstrumentor().instrument()
58-
59-
client = Client()
60-
response = client.models.generate_content(
61-
model="gemini-1.5-flash-002",
62-
contents="Write a short poem on OpenTelemetry."
63-
)
64-
65-
66-
Limitations
67-
***********
68-
69-
When using the Google GenAI SDK with automatic function calling enabled,
70-
the OpenTelemetry instrumentation creates a span only for the top-level
71-
``generate_content`` call.
72-
73-
Internal model or tool calls triggered automatically by the SDK are executed
74-
within the SDK internals and are not traced as separate spans.
75-
76-
77-
Enabling message content
78-
*************************
79-
80-
Message content such as the contents of the prompt and response
81-
are not captured by default. To capture message content as log events, set the environment variable
82-
``OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT`` to ``true``.
83-
84-
85-
Uninstrument
86-
************
87-
88-
To uninstrument clients, call the uninstrument method:
89-
90-
.. code-block:: python
91-
92-
from opentelemetry.instrumentation.google_genai import GoogleGenAiSdkInstrumentor
93-
94-
GoogleGenAiSdkInstrumentor().instrument()
95-
# ...
96-
97-
# Uninstrument all clients
98-
GoogleGenAiSdkInstrumentor().uninstrument()
99-
100-
101-
References
102-
----------
103-
* `Google Gen AI SDK Documentation <https://ai.google.dev/gemini-api/docs/sdks>`_
104-
* `Google Gen AI SDK on GitHub <https://github.com/googleapis/python-genai>`_
105-
* `Using Vertex AI with Google Gen AI SDK <https://cloud.google.com/vertex-ai/generative-ai/docs/sdks/overview>`_
106-
* `OpenTelemetry Project <https://opentelemetry.io/>`_
107-
* `OpenTelemetry Python Examples <https://github.com/open-telemetry/opentelemetry-python/tree/main/docs/examples>`_
1+
OpenTelemetry Google GenAI SDK Instrumentation
2+
==============================================
3+
4+
|pypi|
5+
6+
.. |pypi| image:: https://badge.fury.io/py/opentelemetry-instrumentation-google-genai.svg
7+
:target: https://pypi.org/project/opentelemetry-instrumentation-google-genai/
8+
9+
This library adds instrumentation to the `Google GenAI SDK library <https://pypi.org/project/google-genai/>`_
10+
to emit telemetry data following `Semantic Conventions for GenAI systems <https://opentelemetry.io/docs/specs/semconv/gen-ai/>`_.
11+
It adds trace spans for GenAI operations, events/logs for recording prompts/responses, and emits metrics that describe the
12+
GenAI operations in aggregate.
13+
14+
15+
Experimental
16+
------------
17+
18+
This package is still experimental. The instrumentation may not be complete or correct just yet.
19+
20+
Please see "TODOS.md" for a list of known defects/TODOs that are blockers to package stability.
21+
22+
23+
Installation
24+
------------
25+
26+
If your application is already instrumented with OpenTelemetry, add this
27+
package to your requirements.
28+
::
29+
30+
pip install opentelemetry-instrumentation-google-genai
31+
32+
If you don't have a Google GenAI SDK application, yet, try our `examples <examples>`_.
33+
34+
Check out `zero-code example <examples/zero-code>`_ for a quick start.
35+
36+
37+
Usage
38+
-----
39+
40+
This section describes how to set up Google GenAI SDK instrumentation if you're setting OpenTelemetry up manually.
41+
Check out the `manual example <examples/manual>`_ for more details.
42+
43+
44+
Instrumenting all clients
45+
*************************
46+
47+
When using the instrumentor, all clients will automatically trace GenAI ``generate_content`` operations.
48+
You can also optionally capture prompts and responses as log events.
49+
50+
Make sure to configure OpenTelemetry tracing, logging, metrics, and events to capture all telemetry emitted by the instrumentation.
51+
52+
.. code-block:: python
53+
54+
from opentelemetry.instrumentation.google_genai import GoogleGenAiSdkInstrumentor
55+
from google.genai import Client
56+
57+
GoogleGenAiSdkInstrumentor().instrument()
58+
59+
client = Client()
60+
response = client.models.generate_content(
61+
model="gemini-1.5-flash-002",
62+
contents="Write a short poem on OpenTelemetry."
63+
)
64+
65+
66+
Limitations
67+
***********
68+
69+
When using the Google GenAI SDK with automatic function calling enabled,
70+
the OpenTelemetry instrumentation creates a span only for the top-level
71+
``generate_content`` call.
72+
73+
Internal model or tool calls triggered automatically by the SDK are executed
74+
within the SDK internals and are not traced as separate spans.
75+
76+
77+
Enabling message content
78+
*************************
79+
80+
Message content such as the contents of the prompt and response
81+
are not captured by default. To capture message content as log events, set the environment variable
82+
``OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT`` to ``true``.
83+
84+
Configuration recording
85+
***********************
86+
87+
The instrumentation can optionally record ``GenerateContentConfig`` parameters
88+
as span attributes under the ``gcp.gen_ai.operation.config.*`` namespace.
89+
90+
By default, no config fields are recorded. You can control which fields are
91+
captured using the following environment variables:
92+
93+
* ``OTEL_GOOGLE_GENAI_GENERATE_CONTENT_CONFIG_INCLUDES`` — A comma-separated
94+
list of config field names to include in the span attributes. For example:
95+
96+
.. code-block:: bash
97+
98+
export OTEL_GOOGLE_GENAI_GENERATE_CONTENT_CONFIG_INCLUDES=temperature,max_output_tokens
99+
100+
* ``OTEL_GOOGLE_GENAI_GENERATE_CONTENT_CONFIG_EXCLUDES`` — A comma-separated
101+
list of config field names to exclude from the span attributes:
102+
103+
.. code-block:: bash
104+
105+
export OTEL_GOOGLE_GENAI_GENERATE_CONTENT_CONFIG_EXCLUDES=stop_sequences
106+
107+
If both variables are set, the includes list is applied first, then the
108+
excludes list filters the result further.
109+
110+
Uninstrument
111+
************
112+
113+
To uninstrument clients, call the uninstrument method:
114+
115+
.. code-block:: python
116+
117+
from opentelemetry.instrumentation.google_genai import GoogleGenAiSdkInstrumentor
118+
119+
GoogleGenAiSdkInstrumentor().instrument()
120+
# ...
121+
122+
# Uninstrument all clients
123+
GoogleGenAiSdkInstrumentor().uninstrument()
124+
125+
126+
References
127+
----------
128+
* `Google Gen AI SDK Documentation <https://ai.google.dev/gemini-api/docs/sdks>`_
129+
* `Google Gen AI SDK on GitHub <https://github.com/googleapis/python-genai>`_
130+
* `Using Vertex AI with Google Gen AI SDK <https://cloud.google.com/vertex-ai/generative-ai/docs/sdks/overview>`_
131+
* `OpenTelemetry Project <https://opentelemetry.io/>`_
132+
* `OpenTelemetry Python Examples <https://github.com/open-telemetry/opentelemetry-python/tree/main/docs/examples>`_

0 commit comments

Comments
 (0)