Skip to content

Commit a10d6de

Browse files
Achuth17Achuth17
committed
[google-genai] Provide a way to attach extra attributes to the operation-details event but not to the span
Add GENERATE_CONTENT_EVENT_ONLY_EXTRA_ATTRIBUTES_CONTEXT_KEY for caller-supplied attributes that should be emitted only on the gen_ai.client.inference.operation.details log event and never on the generate_content {model} span. Threaded through all four wrappers (sync/async x streaming/non-streaming). On key collisions with GENERATE_CONTENT_EXTRA_ATTRIBUTES_CONTEXT_KEY, the event-only value wins on the event; the span carries the existing extra-attributes value. Originally proposed at open-telemetry/opentelemetry-python-contrib#4581 before the package moved to this repo. Assisted-by: opencode agent
1 parent 975a98d commit a10d6de

5 files changed

Lines changed: 230 additions & 2 deletions

File tree

‎instrumentation/opentelemetry-instrumentation-google-genai/.changelog/24.added‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
`opentelemetry-instrumentation-google-genai`: Add `GENERATE_CONTENT_EVENT_ONLY_EXTRA_ATTRIBUTES_CONTEXT_KEY` for attaching caller-supplied attributes that are emitted only on the `gen_ai.client.inference.operation.details` log event and never on the `generate_content {model}` span. On key collisions with `GENERATE_CONTENT_EXTRA_ATTRIBUTES_CONTEXT_KEY`, the event-only value wins on the event.

‎instrumentation/opentelemetry-instrumentation-google-genai/src/opentelemetry/instrumentation/google_genai/__init__.py‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -30,12 +30,16 @@
3030
---
3131
"""
3232

33-
from .generate_content import GENERATE_CONTENT_EXTRA_ATTRIBUTES_CONTEXT_KEY
33+
from .generate_content import (
34+
GENERATE_CONTENT_EVENT_ONLY_EXTRA_ATTRIBUTES_CONTEXT_KEY,
35+
GENERATE_CONTENT_EXTRA_ATTRIBUTES_CONTEXT_KEY,
36+
)
3437
from .instrumentor import GoogleGenAiSdkInstrumentor
3538
from .version import __version__
3639

3740
__all__ = [
3841
"GoogleGenAiSdkInstrumentor",
3942
"GENERATE_CONTENT_EXTRA_ATTRIBUTES_CONTEXT_KEY",
43+
"GENERATE_CONTENT_EVENT_ONLY_EXTRA_ATTRIBUTES_CONTEXT_KEY",
4044
"__version__",
4145
]

‎instrumentation/opentelemetry-instrumentation-google-genai/src/opentelemetry/instrumentation/google_genai/generate_content.py‎

Lines changed: 52 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -101,6 +101,20 @@
101101
"generate_content_extra_attributes_context_key"
102102
)
103103

104+
# Attributes attached under this context key are emitted only on the
105+
# `gen_ai.client.inference.operation.details` log event; they are NEVER
106+
# attached to the `generate_content {model}` span. Use this for caller-supplied
107+
# attributes that must not land on broadly-sampled spans -- for example, an
108+
# end-user identifier that is acceptable in telemetry log events but
109+
# undesirable on spans. On key collisions with values supplied via
110+
# ``GENERATE_CONTENT_EXTRA_ATTRIBUTES_CONTEXT_KEY``, the event-only value wins
111+
# on the event.
112+
GENERATE_CONTENT_EVENT_ONLY_EXTRA_ATTRIBUTES_CONTEXT_KEY = (
113+
context_api.create_key(
114+
"generate_content_event_only_extra_attributes_context_key"
115+
)
116+
)
117+
104118

105119
class _MethodsSnapshot:
106120
def __init__(self):
@@ -495,6 +509,15 @@ def _get_extra_generate_content_attributes() -> dict[str, AttributeValue]:
495509
return dict(attrs or {})
496510

497511

512+
def _get_event_only_extra_generate_content_attributes() -> dict[
513+
str, AttributeValue
514+
]:
515+
attrs = context_api.get_value(
516+
GENERATE_CONTENT_EVENT_ONLY_EXTRA_ATTRIBUTES_CONTEXT_KEY
517+
)
518+
return dict(attrs or {})
519+
520+
498521
class _GenerateContentInstrumentationHelper:
499522
def __init__(
500523
self,
@@ -750,6 +773,9 @@ def _maybe_log_completion_details(
750773
candidates: list[Candidate],
751774
config: Optional[GenerateContentConfigOrDict] = None,
752775
tool_definitions: Optional[list[ToolDefinition]] = None,
776+
event_only_extra_attributes: Optional[
777+
dict[str, AttributeValue]
778+
] = None,
753779
):
754780
if not self.experimental_sem_convs_enabled:
755781
return
@@ -763,11 +789,15 @@ def _maybe_log_completion_details(
763789
)
764790
output_messages = to_output_messages(candidates=candidates)
765791
span = trace.get_current_span()
792+
# event_only_extra_attributes win on the event when colliding with
793+
# extra_attributes; they are intentionally NOT set on the span
794+
# (the caller did not include them in the span.set_attributes() call).
766795
event = LogRecord(
767796
event_name="gen_ai.client.inference.operation.details",
768797
attributes=extra_attributes
769798
| request_attributes
770-
| final_attributes,
799+
| final_attributes
800+
| (event_only_extra_attributes or {}),
771801
)
772802
# New sem conv only gets added here when we've verified that experimental mode is set.
773803
span.set_attribute(
@@ -1032,6 +1062,10 @@ def instrumented_generate_content(
10321062
model, "google.genai.Models.generate_content"
10331063
) as span:
10341064
extra_attributes = _get_extra_generate_content_attributes()
1065+
event_only_extra_attributes = (
1066+
_get_event_only_extra_generate_content_attributes()
1067+
)
1068+
# event_only_extra_attributes are intentionally excluded from the span.
10351069
span.set_attributes(extra_attributes | request_attributes)
10361070
if not helper.experimental_sem_convs_enabled:
10371071
helper.process_request(contents, config, span)
@@ -1068,6 +1102,7 @@ def instrumented_generate_content(
10681102
candidates,
10691103
config,
10701104
maybe_tool_definitions,
1105+
event_only_extra_attributes=event_only_extra_attributes,
10711106
)
10721107
helper._record_token_usage_metric()
10731108
helper._record_duration_metric()
@@ -1109,6 +1144,10 @@ def instrumented_generate_content_stream(
11091144
model, "google.genai.Models.generate_content_stream"
11101145
) as span:
11111146
extra_attributes = _get_extra_generate_content_attributes()
1147+
event_only_extra_attributes = (
1148+
_get_event_only_extra_generate_content_attributes()
1149+
)
1150+
# event_only_extra_attributes are intentionally excluded from the span.
11121151
span.set_attributes(extra_attributes | request_attributes)
11131152
if not helper.experimental_sem_convs_enabled:
11141153
helper.process_request(contents, config, span)
@@ -1145,6 +1184,7 @@ def instrumented_generate_content_stream(
11451184
candidates,
11461185
config,
11471186
maybe_tool_definitions,
1187+
event_only_extra_attributes=event_only_extra_attributes,
11481188
)
11491189
helper._record_token_usage_metric()
11501190
helper._record_duration_metric()
@@ -1186,6 +1226,10 @@ async def instrumented_generate_content(
11861226
model, "google.genai.AsyncModels.generate_content"
11871227
) as span:
11881228
extra_attributes = _get_extra_generate_content_attributes()
1229+
event_only_extra_attributes = (
1230+
_get_event_only_extra_generate_content_attributes()
1231+
)
1232+
# event_only_extra_attributes are intentionally excluded from the span.
11891233
span.set_attributes(extra_attributes | request_attributes)
11901234
if not helper.experimental_sem_convs_enabled:
11911235
helper.process_request(contents, config, span)
@@ -1221,6 +1265,7 @@ async def instrumented_generate_content(
12211265
candidates,
12221266
config,
12231267
maybe_tool_definitions,
1268+
event_only_extra_attributes=event_only_extra_attributes,
12241269
)
12251270
helper._record_token_usage_metric()
12261271
helper._record_duration_metric()
@@ -1264,6 +1309,10 @@ async def instrumented_generate_content_stream(
12641309
end_on_exit=False,
12651310
) as span:
12661311
extra_attributes = _get_extra_generate_content_attributes()
1312+
event_only_extra_attributes = (
1313+
_get_event_only_extra_generate_content_attributes()
1314+
)
1315+
# event_only_extra_attributes are intentionally excluded from the span.
12671316
span.set_attributes(extra_attributes | request_attributes)
12681317
if not helper.experimental_sem_convs_enabled:
12691318
helper.process_request(contents, config, span)
@@ -1291,6 +1340,7 @@ async def instrumented_generate_content_stream(
12911340
[],
12921341
config,
12931342
maybe_tool_definitions,
1343+
event_only_extra_attributes=event_only_extra_attributes,
12941344
)
12951345
helper._record_duration_metric()
12961346
with trace.use_span(span, end_on_exit=True):
@@ -1328,6 +1378,7 @@ async def _response_async_generator_wrapper():
13281378
candidates,
13291379
config,
13301380
maybe_tool_definitions,
1381+
event_only_extra_attributes=event_only_extra_attributes,
13311382
)
13321383
helper._record_token_usage_metric()
13331384
helper._record_duration_metric()

‎instrumentation/opentelemetry-instrumentation-google-genai/tests/generate_content/nonstreaming_base.py‎

Lines changed: 88 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,7 @@
2323
_StabilityMode,
2424
)
2525
from opentelemetry.instrumentation.google_genai import (
26+
GENERATE_CONTENT_EVENT_ONLY_EXTRA_ATTRIBUTES_CONTEXT_KEY,
2627
GENERATE_CONTENT_EXTRA_ATTRIBUTES_CONTEXT_KEY,
2728
)
2829
from opentelemetry.semconv._incubating.attributes import gen_ai_attributes
@@ -925,6 +926,93 @@ def test_new_semconv_log_has_extra_genai_attributes(self):
925926
finally:
926927
context_api.detach(tok)
927928

929+
def test_event_only_extra_attributes_not_set_on_span(self):
930+
"""event_only_extra_attributes must never appear on the span attributes."""
931+
self.configure_valid_response(text="Yep, it works!")
932+
tok = context_api.attach(
933+
context_api.set_value(
934+
GENERATE_CONTENT_EVENT_ONLY_EXTRA_ATTRIBUTES_CONTEXT_KEY,
935+
{"user.id": "user-42"},
936+
)
937+
)
938+
try:
939+
self.generate_content(
940+
model="gemini-2.0-flash", contents="Does this work?"
941+
)
942+
span = self.otel.get_span_named(
943+
"generate_content gemini-2.0-flash"
944+
)
945+
self.assertNotIn("user.id", span.attributes)
946+
finally:
947+
context_api.detach(tok)
948+
949+
def test_event_only_extra_attributes_set_on_event_only(self):
950+
"""event_only_extra_attributes land on the operation-details event but not on the span.
951+
952+
Also verifies the collision-precedence rule: when a key appears in both
953+
``GENERATE_CONTENT_EXTRA_ATTRIBUTES_CONTEXT_KEY`` and
954+
``GENERATE_CONTENT_EVENT_ONLY_EXTRA_ATTRIBUTES_CONTEXT_KEY``, the
955+
event-only value wins on the event, while the span carries the
956+
``extra_attributes`` value (event-only is never on the span).
957+
"""
958+
patched_environ = patch.dict(
959+
"os.environ",
960+
{
961+
"OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT": "EVENT_ONLY",
962+
"OTEL_SEMCONV_STABILITY_OPT_IN": "gen_ai_latest_experimental",
963+
},
964+
)
965+
patched_otel_mapping = patch.dict(
966+
_OpenTelemetrySemanticConventionStability._OTEL_SEMCONV_STABILITY_SIGNAL_MAPPING,
967+
{
968+
_OpenTelemetryStabilitySignalType.GEN_AI: _StabilityMode.GEN_AI_LATEST_EXPERIMENTAL
969+
},
970+
)
971+
with patched_environ, patched_otel_mapping:
972+
self.configure_valid_response(text="Yep, it works!")
973+
tok_extra = context_api.attach(
974+
context_api.set_value(
975+
GENERATE_CONTENT_EXTRA_ATTRIBUTES_CONTEXT_KEY,
976+
{"shared.key": "from_extra"},
977+
)
978+
)
979+
tok_event_only = context_api.attach(
980+
context_api.set_value(
981+
GENERATE_CONTENT_EVENT_ONLY_EXTRA_ATTRIBUTES_CONTEXT_KEY,
982+
{
983+
"user.id": "user-42",
984+
"shared.key": "from_event_only",
985+
},
986+
)
987+
)
988+
try:
989+
self.generate_content(
990+
model="gemini-2.0-flash",
991+
contents="Does this work?",
992+
)
993+
994+
span = self.otel.get_span_named(
995+
"generate_content gemini-2.0-flash"
996+
)
997+
self.assertNotIn("user.id", span.attributes)
998+
# On the span, only `extra_attributes` contributes the shared key.
999+
self.assertEqual(span.attributes["shared.key"], "from_extra")
1000+
1001+
self.otel.assert_has_event_named(
1002+
"gen_ai.client.inference.operation.details"
1003+
)
1004+
event = self.otel.get_event_named(
1005+
"gen_ai.client.inference.operation.details"
1006+
)
1007+
self.assertEqual(event.attributes["user.id"], "user-42")
1008+
# On the event, event_only wins on the collision.
1009+
self.assertEqual(
1010+
event.attributes["shared.key"], "from_event_only"
1011+
)
1012+
finally:
1013+
context_api.detach(tok_event_only)
1014+
context_api.detach(tok_extra)
1015+
9281016
def test_records_metrics_data(self):
9291017
self.configure_valid_response()
9301018
self.generate_content(model="gemini-2.0-flash", contents="Some input")

‎instrumentation/opentelemetry-instrumentation-google-genai/tests/generate_content/streaming_base.py‎

Lines changed: 84 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,7 @@
1111
_StabilityMode,
1212
)
1313
from opentelemetry.instrumentation.google_genai import (
14+
GENERATE_CONTENT_EVENT_ONLY_EXTRA_ATTRIBUTES_CONTEXT_KEY,
1415
GENERATE_CONTENT_EXTRA_ATTRIBUTES_CONTEXT_KEY,
1516
)
1617

@@ -130,3 +131,86 @@ def test_new_semconv_log_has_extra_genai_attributes(self):
130131
)
131132
finally:
132133
context_api.detach(tok)
134+
135+
def test_event_only_extra_attributes_not_set_on_span(self):
136+
"""event_only_extra_attributes must never appear on the span attributes."""
137+
self.configure_valid_response(text="Yep, it works!")
138+
tok = context_api.attach(
139+
context_api.set_value(
140+
GENERATE_CONTENT_EVENT_ONLY_EXTRA_ATTRIBUTES_CONTEXT_KEY,
141+
{"user.id": "user-42"},
142+
)
143+
)
144+
try:
145+
self.generate_content(
146+
model="gemini-2.0-flash", contents="Does this work?"
147+
)
148+
span = self.otel.get_span_named(
149+
"generate_content gemini-2.0-flash"
150+
)
151+
self.assertNotIn("user.id", span.attributes)
152+
finally:
153+
context_api.detach(tok)
154+
155+
def test_event_only_extra_attributes_set_on_event_only(self):
156+
"""event_only_extra_attributes land on the operation-details event but not on the span.
157+
158+
Also verifies that on key collision with
159+
``GENERATE_CONTENT_EXTRA_ATTRIBUTES_CONTEXT_KEY``, the event-only value
160+
wins on the event while the span carries the ``extra_attributes`` value.
161+
"""
162+
patched_environ = patch.dict(
163+
"os.environ",
164+
{
165+
"OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT": "EVENT_ONLY",
166+
"OTEL_SEMCONV_STABILITY_OPT_IN": "gen_ai_latest_experimental",
167+
},
168+
)
169+
patched_otel_mapping = patch.dict(
170+
_OpenTelemetrySemanticConventionStability._OTEL_SEMCONV_STABILITY_SIGNAL_MAPPING,
171+
{
172+
_OpenTelemetryStabilitySignalType.GEN_AI: _StabilityMode.GEN_AI_LATEST_EXPERIMENTAL
173+
},
174+
)
175+
with patched_environ, patched_otel_mapping:
176+
self.configure_valid_response(text="Yep, it works!")
177+
tok_extra = context_api.attach(
178+
context_api.set_value(
179+
GENERATE_CONTENT_EXTRA_ATTRIBUTES_CONTEXT_KEY,
180+
{"shared.key": "from_extra"},
181+
)
182+
)
183+
tok_event_only = context_api.attach(
184+
context_api.set_value(
185+
GENERATE_CONTENT_EVENT_ONLY_EXTRA_ATTRIBUTES_CONTEXT_KEY,
186+
{
187+
"user.id": "user-42",
188+
"shared.key": "from_event_only",
189+
},
190+
)
191+
)
192+
try:
193+
self.generate_content(
194+
model="gemini-2.0-flash",
195+
contents="Does this work?",
196+
)
197+
198+
span = self.otel.get_span_named(
199+
"generate_content gemini-2.0-flash"
200+
)
201+
self.assertNotIn("user.id", span.attributes)
202+
self.assertEqual(span.attributes["shared.key"], "from_extra")
203+
204+
self.otel.assert_has_event_named(
205+
"gen_ai.client.inference.operation.details"
206+
)
207+
event = self.otel.get_event_named(
208+
"gen_ai.client.inference.operation.details"
209+
)
210+
self.assertEqual(event.attributes["user.id"], "user-42")
211+
self.assertEqual(
212+
event.attributes["shared.key"], "from_event_only"
213+
)
214+
finally:
215+
context_api.detach(tok_event_only)
216+
context_api.detach(tok_extra)

0 commit comments

Comments
 (0)