otelzero 0.2.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,173 @@
1
+ """AWS Strands Agents instrumentation: switch on the framework's *own* OpenTelemetry.
2
+
3
+ `Strands Agents <https://github.com/strands-agents/sdk-python>`_ always traces
4
+ itself through the global OpenTelemetry tracer provider, in the GenAI semantic
5
+ conventions. Each run gets an ``invoke_agent {name}`` span, with
6
+ ``execute_event_loop_cycle``, ``chat`` and ``execute_tool {tool}`` spans under
7
+ it, plus ``gen_ai.*`` model, tool and usage attributes. That is more than a
8
+ wrapper around ``Agent.invoke_async`` could see, so this hook wraps nothing.
9
+ It makes sure the spans reach the registry and match otelzero's conventions:
10
+
11
+ * It configures otelzero's OTLP provider as the global one, so Strands' spans
12
+ export to ``{server_url}/v1/traces``.
13
+ * It opts Strands into the latest GenAI conventions through
14
+ ``OTEL_SEMCONV_STABILITY_OPT_IN`` (``gen_ai_latest_experimental``):
15
+ ``gen_ai.provider.name`` instead of the deprecated ``gen_ai.system``, and
16
+ ``gen_ai.input.messages`` / ``gen_ai.output.messages`` instead of
17
+ per-message events.
18
+ * It applies otelzero's content opt-in
19
+ (``OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT``). By default Strands
20
+ records prompts and completions unconditionally. With content capture off,
21
+ this hook turns on Strands' redaction (``gen_ai_unredacted_attributes=``),
22
+ so prompts, completions, system prompts and tool arguments are exported as
23
+ ``[REDACTED]``. With it on, the content goes on span attributes
24
+ (``gen_ai_span_attributes_only``) along with tool definitions
25
+ (``gen_ai_tool_definitions``), which is where the registry reads them.
26
+ * It attaches the shared :class:`~otelzero.hooks._native.NativeRunProcessor`,
27
+ which stamps otelzero's run identity on every Strands span and turns each
28
+ ``invoke_agent`` span into ``agent_start`` / ``agent_end`` / ``agent_error``.
29
+
30
+ Opt-in tokens the user already set are kept. Strands reads them when its tracer
31
+ is created, so if one already exists (an agent was built before this call),
32
+ it is refreshed in place. ``strands`` may therefore be imported before or after
33
+ the install call. The ``otel`` extra is required: the lifecycle events come from
34
+ spans, so tracing stays on even with ``OTELZERO_OTEL=0``.
35
+ """
36
+
37
+ from typing import Optional
38
+
39
+ from otelzero import otel, semconv
40
+ from otelzero.hooks import _native
41
+ from otelzero.telemetry import TelemetryClient
42
+
43
+ FRAMEWORK = "Strands Agents"
44
+
45
+ # Strands' tracer is ``get_tracer("strands.telemetry.tracer")``.
46
+ _SCOPES = ("strands",)
47
+
48
+ _LATEST = "gen_ai_latest_experimental"
49
+ _TOOL_DEFINITIONS = "gen_ai_tool_definitions"
50
+ _SPAN_ATTRIBUTES_ONLY = "gen_ai_span_attributes_only"
51
+ _UNREDACTED = "gen_ai_unredacted_attributes="
52
+
53
+ def _opt_in_tokens(capture_content: bool) -> list:
54
+ if capture_content:
55
+ return [_LATEST, _TOOL_DEFINITIONS, _SPAN_ATTRIBUTES_ONLY]
56
+ # An empty allow-list: every sensitive attribute is redacted.
57
+ return [_LATEST, _UNREDACTED]
58
+
59
+
60
+ def _refresh_tracer() -> None:
61
+ """Make an already-created Strands tracer pick up the new opt-in tokens.
62
+
63
+ ``strands.telemetry.tracer.Tracer`` parses ``OTEL_SEMCONV_STABILITY_OPT_IN``
64
+ in its constructor, and agents keep a reference to the singleton, so a
65
+ fresh one would not reach agents that already exist. Its flags are
66
+ recomputed in place instead. Calling ``__init__`` again would also
67
+ re-instrument threading, which logs a warning.
68
+ """
69
+ try:
70
+ from strands.telemetry import tracer as tracer_module
71
+ except ImportError: # pragma: no cover - checked by install
72
+ return
73
+ tracer = getattr(tracer_module, "_tracer_instance", None)
74
+ if tracer is None or not hasattr(tracer, "_parse_semconv_opt_in"):
75
+ return
76
+ try:
77
+ values = tracer._parse_semconv_opt_in()
78
+ tracer.use_latest_genai_conventions = _LATEST in values
79
+ tracer._include_tool_definitions = _TOOL_DEFINITIONS in values
80
+ tracer._span_attributes_only = tracer.is_langfuse or _SPAN_ATTRIBUTES_ONLY in values
81
+ unredacted = next((v for v in values if v.startswith(_UNREDACTED)), None)
82
+ tracer._redaction_enabled = unredacted is not None
83
+ tracer._unredacted_exact, tracer._unredacted_globs = (
84
+ tracer._compile_unredacted_patterns(unredacted.partition("=")[2] if unredacted else "")
85
+ )
86
+ except Exception as exc: # pragma: no cover - a Strands internals change
87
+ print(f"[MONITOR] {FRAMEWORK}: could not refresh the existing tracer: {exc}")
88
+
89
+
90
+ def install_strands_monitoring(
91
+ server_url: str = "http://localhost:8000",
92
+ user: Optional[str] = None,
93
+ api_key: Optional[str] = None,
94
+ session: Optional[str] = None,
95
+ name: Optional[str] = None,
96
+ ) -> TelemetryClient:
97
+ """
98
+ Install AWS Strands Agents monitoring via the framework's native OpenTelemetry.
99
+
100
+ Points Strands' own spans at ``{server_url}/v1/traces`` (or at
101
+ ``OTEL_EXPORTER_OTLP_ENDPOINT`` when set), opts them into the latest GenAI
102
+ semantic conventions, and sends ``agent_start`` and ``agent_end`` (or
103
+ ``agent_error``) for each run, built from its ``invoke_agent`` span. May be
104
+ called before or after ``strands`` is imported, but requires the ``otel``
105
+ extra.
106
+
107
+ Args:
108
+ server_url: URL of the monitoring server
109
+ user: Name of the executing user
110
+ api_key: Ingest key tying events to an owner (for the iOS app)
111
+ session: Per-run id used to group events in the app; exported on every
112
+ span as ``gen_ai.conversation.id``
113
+ name: Session title shown on the dashboard and apps. Strands' agent
114
+ span carries no prompt when a run starts, so no title is derived
115
+ when this is omitted. Pass it here or per run with
116
+ ``run_context(name=...)``.
117
+
118
+ Raises:
119
+ ImportError: ``strands`` is not installed.
120
+ RuntimeError: the OpenTelemetry SDK (the ``otel`` extra) is missing.
121
+ """
122
+ try:
123
+ import strands # noqa: F401
124
+ except ImportError as exc: # pragma: no cover - exercised by hand
125
+ raise ImportError(
126
+ "install_strands_monitoring needs strands importable: "
127
+ "uv pip install strands-agents"
128
+ ) from exc
129
+
130
+ telemetry = TelemetryClient(
131
+ server_url,
132
+ framework=FRAMEWORK,
133
+ user=user,
134
+ api_key=api_key,
135
+ session=session,
136
+ name=name,
137
+ )
138
+ provider = _native.start_tracing(FRAMEWORK, telemetry, server_url)
139
+ _native.attach_processor(
140
+ _native.global_provider(provider, FRAMEWORK),
141
+ telemetry,
142
+ framework=FRAMEWORK,
143
+ scopes=_SCOPES,
144
+ default_agent_name="Strands Agent",
145
+ )
146
+
147
+ _native.opt_in_tokens(
148
+ FRAMEWORK,
149
+ _opt_in_tokens(semconv.capture_content_enabled()),
150
+ # A redaction policy the user chose is theirs to keep.
151
+ skip_prefixes=(_UNREDACTED,),
152
+ )
153
+ _refresh_tracer()
154
+
155
+ print(
156
+ f"[MONITOR] {FRAMEWORK} monitoring installed via native OpenTelemetry "
157
+ f"(server: {server_url})"
158
+ )
159
+ return telemetry
160
+
161
+
162
+ def uninstall_strands_monitoring() -> None:
163
+ """Stop stamping identity and sending events; drop the opt-in tokens it added.
164
+
165
+ Strands keeps tracing through the global provider, since that's how it
166
+ always works. Only this hook's contributions stop.
167
+ """
168
+ from opentelemetry import trace
169
+
170
+ _native.detach(FRAMEWORK, otel._provider)
171
+ _native.detach(FRAMEWORK, trace.get_tracer_provider())
172
+ _native.release_opt_in(FRAMEWORK)
173
+ _refresh_tracer()
otelzero/otel.py ADDED
@@ -0,0 +1,372 @@
1
+ """
2
+ Optional OpenTelemetry tracing for otelzero.
3
+
4
+ A thin, dependency-optional wrapper around the OpenTelemetry SDK. It degrades to
5
+ a no-op when
6
+
7
+ * ``opentelemetry`` is not installed (the ``otel`` extra), or
8
+ * the ``OTELZERO_OTEL`` environment variable explicitly switches it off
9
+ (``0`` / ``false`` / ``no`` / ``off``),
10
+
11
+ so the client keeps working with zero OpenTelemetry dependencies. Tracing is
12
+ **on by default** (``OTELZERO_OTEL`` effectively ``1``): the import-hook
13
+ wrappers emit spans *in addition to* the HTTP telemetry (dual-emit), exporting
14
+ OTLP/HTTP to a collector or to otelzero's own ``/v1/traces`` receiver, and the
15
+ native-OTel hooks export the framework's own spans the same way.
16
+ """
17
+
18
+ import atexit
19
+ import contextlib
20
+ import os
21
+ from typing import Any, Callable, Dict, Iterator, Optional
22
+
23
+ from otelzero import semconv
24
+
25
+ try:
26
+ from opentelemetry import trace as _trace
27
+ from opentelemetry.trace import SpanKind, Status, StatusCode
28
+
29
+ _OTEL_API = True
30
+ except ImportError: # pragma: no cover - optional dependency
31
+ _trace = None
32
+ SpanKind = Status = StatusCode = None # type: ignore[assignment]
33
+ _OTEL_API = False
34
+
35
+ _TRACER_NAME = "otelzero"
36
+ _provider = None
37
+ _initialized = False
38
+
39
+
40
+ _OFF_VALUES = ("0", "false", "no", "off")
41
+
42
+
43
+ def otel_enabled() -> bool:
44
+ """True unless ``OTELZERO_OTEL`` explicitly switches tracing off.
45
+
46
+ Unset (or any other value) means on, so ``OTELZERO_OTEL`` is effectively
47
+ always ``1``; ``OTELZERO_OTEL=0`` remains as the escape hatch.
48
+ """
49
+ return os.environ.get("OTELZERO_OTEL", "").strip().lower() not in _OFF_VALUES
50
+
51
+
52
+ def init_tracing(
53
+ server_url: str,
54
+ service_name: str,
55
+ service_version: Optional[str] = None,
56
+ api_key: Optional[str] = None,
57
+ identity: Optional[Callable[[], Any]] = None,
58
+ *,
59
+ force: bool = False,
60
+ ) -> Any:
61
+ """Configure a global OTLP/HTTP tracer provider. Idempotent and lazy.
62
+
63
+ Does nothing when ``opentelemetry`` is not installed, or when
64
+ ``OTELZERO_OTEL=0`` switches tracing off -- unless ``force`` is given, for a
65
+ hook whose *only* channel is OpenTelemetry (a framework's native
66
+ instrumentation pointed at the registry), which cannot be switched off. Returns the provider, or ``None`` when tracing
67
+ is off or the SDK is missing, so such a hook can tell the two apart.
68
+ The OTLP endpoint resolves from the standard ``OTEL_EXPORTER_OTLP_*`` env
69
+ vars; if neither is set it targets the registry's ``{server_url}/v1/traces``
70
+ receiver so traces flow to the existing dashboard out of the box. When
71
+ targeting otelzero's own receiver, ``api_key`` (the ingest key) is sent as a
72
+ Bearer header so the owner-scoped ingest accepts the spans.
73
+
74
+ The resource describes the *process*, so it carries only the framework
75
+ identity: ``service_name``, unless ``OTEL_SERVICE_NAME`` or a ``service.name``
76
+ in ``OTEL_RESOURCE_ATTRIBUTES`` overrides it. Who is running and which flow it belongs to vary per run and are
77
+ set per span instead -- see :func:`otelzero.context.run_context`.
78
+
79
+ The provider also carries otelzero's translation layer (see
80
+ :mod:`otelzero.translate`): spans a framework's own OpenTelemetry bridge
81
+ emits through this provider -- LangChain's ``langsmith`` connector -- are
82
+ rewritten into the current GenAI conventions at export, and stamped with
83
+ the run's identity at start. ``identity`` is the ``(user, conversation_id,
84
+ ...)`` callable that supplies it, normally the first client's
85
+ :meth:`~otelzero.telemetry.TelemetryClient.run_identity`; without one only
86
+ an active ``run_context`` is read.
87
+ """
88
+ global _provider, _initialized
89
+ if _initialized or not _OTEL_API or not (force or otel_enabled()):
90
+ return _provider
91
+ _initialized = True
92
+ try:
93
+ from opentelemetry.exporter.otlp.proto.http.trace_exporter import (
94
+ OTLPSpanExporter,
95
+ )
96
+ from opentelemetry.sdk.resources import OTELResourceDetector, Resource
97
+ from opentelemetry.sdk.trace import TracerProvider
98
+ from opentelemetry.sdk.trace.export import BatchSpanProcessor
99
+ except ImportError: # pragma: no cover - SDK/exporter not installed
100
+ # Tracing is on by default, so stay quiet for clients without the
101
+ # extra; warn only when someone asked for spans explicitly.
102
+ if force or os.environ.get("OTELZERO_OTEL", "").strip():
103
+ print(
104
+ "[OTEL] the OpenTelemetry SDK is not installed; tracing disabled. "
105
+ "Install the 'otel' extra."
106
+ )
107
+ return None
108
+
109
+ # Resource.create lets explicit attributes beat the environment, so the
110
+ # framework label is only added when the user configured no service name.
111
+ attrs: Dict[str, Any] = {}
112
+ if not OTELResourceDetector().detect().attributes.get(semconv.SERVICE_NAME):
113
+ attrs[semconv.SERVICE_NAME] = service_name
114
+ if service_version:
115
+ attrs[semconv.SERVICE_VERSION] = service_version
116
+
117
+ if os.environ.get("OTEL_EXPORTER_OTLP_TRACES_ENDPOINT") or os.environ.get(
118
+ "OTEL_EXPORTER_OTLP_ENDPOINT"
119
+ ):
120
+ exporter = OTLPSpanExporter() # honour standard OTLP env configuration
121
+ else:
122
+ # otelzero's own receiver is owner-scoped, so authenticate with the ingest key.
123
+ headers = {"Authorization": f"Bearer {api_key}"} if api_key else None
124
+ exporter = OTLPSpanExporter(
125
+ endpoint=server_url.rstrip("/") + "/v1/traces", headers=headers
126
+ )
127
+
128
+ from otelzero.translate import IdentitySpanProcessor, TranslatingExporter
129
+
130
+ provider = TracerProvider(resource=Resource.create(attrs))
131
+ provider.add_span_processor(IdentitySpanProcessor(identity))
132
+ provider.add_span_processor(BatchSpanProcessor(TranslatingExporter(exporter)))
133
+ _trace.set_tracer_provider(provider)
134
+ _provider = provider
135
+ atexit.register(_shutdown)
136
+ return provider
137
+
138
+
139
+ def configure_for_test(exporter: Any) -> None:
140
+ """Install a synchronous in-memory provider for tests (bypasses env gating)."""
141
+ global _provider, _initialized
142
+ from opentelemetry.sdk.resources import Resource
143
+ from opentelemetry.sdk.trace import TracerProvider
144
+ from opentelemetry.sdk.trace.export import SimpleSpanProcessor
145
+
146
+ from otelzero.translate import IdentitySpanProcessor, TranslatingExporter
147
+
148
+ provider = TracerProvider(resource=Resource.create({"service.name": "otelzero-test"}))
149
+ provider.add_span_processor(IdentitySpanProcessor())
150
+ provider.add_span_processor(SimpleSpanProcessor(TranslatingExporter(exporter)))
151
+ _trace.set_tracer_provider(provider)
152
+ _provider = provider
153
+ _initialized = True
154
+
155
+
156
+ def _shutdown() -> None:
157
+ if _provider is not None:
158
+ try:
159
+ _provider.shutdown()
160
+ except Exception: # pragma: no cover - best-effort flush
161
+ pass
162
+
163
+
164
+ def force_flush(timeout_millis: int = 5000) -> None:
165
+ """Flush pending spans — useful at the end of short-lived scripts/demos."""
166
+ if _provider is not None:
167
+ try:
168
+ _provider.force_flush(timeout_millis)
169
+ except Exception: # pragma: no cover - best-effort
170
+ pass
171
+
172
+
173
+ def get_tracer() -> Any:
174
+ """Return the otelzero tracer, or ``None`` when OpenTelemetry isn't installed."""
175
+ if not _OTEL_API:
176
+ return None
177
+ return _trace.get_tracer(_TRACER_NAME)
178
+
179
+
180
+ @contextlib.contextmanager
181
+ def span(name: str, attributes: Optional[Dict[str, Any]] = None) -> Iterator[Any]:
182
+ """Start a current span, or yield ``None`` when tracing is unavailable.
183
+
184
+ Nesting is automatic: because the wrapped call runs inside this context
185
+ manager, any span started by an inner wrapper attaches to this one.
186
+ """
187
+ tracer = get_tracer()
188
+ if tracer is None:
189
+ yield None
190
+ return
191
+ # The wrappers handle errors explicitly via record_error(), so disable the
192
+ # SDK's auto exception recording to avoid double-recording on re-raise.
193
+ with tracer.start_as_current_span(
194
+ name,
195
+ kind=SpanKind.INTERNAL,
196
+ attributes=_clean(attributes),
197
+ record_exception=False,
198
+ set_status_on_exception=False,
199
+ ) as current:
200
+ yield current
201
+
202
+
203
+ def start_span(name: str, attributes: Optional[Dict[str, Any]] = None) -> Any:
204
+ """Start a span *without* making it current, or ``None`` when unavailable.
205
+
206
+ The counterpart to :func:`span` for a framework whose run entry point
207
+ returns before the run finishes -- LlamaIndex's ``Workflow.run`` schedules an
208
+ asyncio task and hands back a handler, so a ``with`` block would close the
209
+ span before the run even started. The caller owns the lifetime: make it
210
+ current where it should be inherited (:func:`use_span`) and close it with
211
+ :func:`end_span`.
212
+ """
213
+ tracer = get_tracer()
214
+ if tracer is None:
215
+ return None
216
+ # Same rationale as span(): errors are recorded explicitly via record_error().
217
+ return tracer.start_span(
218
+ name,
219
+ kind=SpanKind.INTERNAL,
220
+ attributes=_clean(attributes),
221
+ record_exception=False,
222
+ set_status_on_exception=False,
223
+ )
224
+
225
+
226
+ @contextlib.contextmanager
227
+ def use_span(span_obj: Any) -> Iterator[Any]:
228
+ """Make an already-started span current for the block, without ending it.
229
+
230
+ A deferred run holds this only around the call that *starts* the framework's
231
+ task, which is where the framework copies the context -- so the span becomes
232
+ the parent of everything that task later does.
233
+ """
234
+ if span_obj is None or not _OTEL_API:
235
+ yield span_obj
236
+ return
237
+ with _trace.use_span(
238
+ span_obj,
239
+ end_on_exit=False,
240
+ record_exception=False,
241
+ set_status_on_exception=False,
242
+ ):
243
+ yield span_obj
244
+
245
+
246
+ def end_span(span_obj: Any) -> None:
247
+ """End a span started by :func:`start_span`; a no-op for ``None``."""
248
+ if span_obj is not None:
249
+ span_obj.end()
250
+
251
+
252
+ def _recording(span_obj: Any) -> bool:
253
+ return span_obj is not None and getattr(span_obj, "is_recording", lambda: False)()
254
+
255
+
256
+ # There is deliberately no set_ok(): the conventions' error-recording rules say
257
+ # the span status code MUST be left unset when an operation ends without error,
258
+ # so a successful run simply doesn't touch it. ``span()`` disables the SDK's
259
+ # automatic status-on-exception for the same reason -- status is set in exactly
260
+ # one place, record_error() below.
261
+
262
+
263
+ def record_error(span_obj: Any, exc: BaseException) -> None:
264
+ """Mark a span failed, with ``error.type`` alongside the human message.
265
+
266
+ The conventions require ``error.type`` on any span that ends in error and
267
+ want it low-cardinality, so it carries the exception's class name while the
268
+ status message keeps the full text.
269
+ """
270
+ if _recording(span_obj):
271
+ span_obj.record_exception(exc)
272
+ span_obj.set_attribute(semconv.ERROR_TYPE, type(exc).__qualname__)
273
+ span_obj.set_status(Status(StatusCode.ERROR, str(exc)))
274
+
275
+
276
+ # Normalized usage key -> the GenAI attribute that records it. Total tokens are
277
+ # absent by design: the conventions record input and output separately, so
278
+ # otelzero's total stays in its own namespace rather than inventing a gen_ai.* name.
279
+ _USAGE_ATTRS = {
280
+ "input_tokens": semconv.GEN_AI_USAGE_INPUT_TOKENS,
281
+ "output_tokens": semconv.GEN_AI_USAGE_OUTPUT_TOKENS,
282
+ "reasoning_tokens": semconv.GEN_AI_USAGE_REASONING_OUTPUT_TOKENS,
283
+ "cache_read_tokens": semconv.GEN_AI_USAGE_CACHE_READ_INPUT_TOKENS,
284
+ }
285
+
286
+
287
+ def set_usage(span_obj: Any, usage: Optional[Dict[str, Any]]) -> None:
288
+ """Set token-usage span attributes from a normalized usage dict.
289
+
290
+ ``None`` values are skipped, so a provider that doesn't report reasoning
291
+ tokens sets no attribute at all rather than a misleading zero.
292
+ """
293
+ if not usage or not _recording(span_obj):
294
+ return
295
+ for key, attr in _USAGE_ATTRS.items():
296
+ value = usage.get(key)
297
+ if value is not None:
298
+ span_obj.set_attribute(attr, value)
299
+ if usage.get("total_tokens") is not None:
300
+ span_obj.set_attribute(semconv.OTELZERO_USAGE_TOTAL_TOKENS, usage["total_tokens"])
301
+
302
+
303
+ def set_model(span_obj: Any, model: Optional[str]) -> None:
304
+ """Set the request-model attribute on a span that did not know it upfront.
305
+
306
+ Some frameworks only reveal which model served a run in the response -- a
307
+ LangGraph node closes over its chat model, so nothing readable on the graph
308
+ says what it is, while the reply messages name it. Those hooks report it
309
+ through ``RunContext.set_model`` once the run is done, and this writes it to
310
+ the span that is about to close. A model already set at span creation wins,
311
+ since it was the one actually requested.
312
+ """
313
+ if not model or not _recording(span_obj):
314
+ return
315
+ attributes = getattr(span_obj, "attributes", None) or {}
316
+ if not attributes.get(semconv.GEN_AI_REQUEST_MODEL):
317
+ span_obj.set_attribute(semconv.GEN_AI_REQUEST_MODEL, model)
318
+
319
+
320
+ def set_finish_reasons(span_obj: Any, reasons: Optional[Any]) -> None:
321
+ """Set ``gen_ai.response.finish_reasons`` from a tuple of stop reasons.
322
+
323
+ Takes what :func:`semconv.finish_reasons` produces (``None`` when the
324
+ framework reported none), so a run that never learned why it stopped sets
325
+ no attribute at all.
326
+ """
327
+ if not reasons or not _recording(span_obj):
328
+ return
329
+ span_obj.set_attribute(semconv.GEN_AI_RESPONSE_FINISH_REASONS, reasons)
330
+
331
+
332
+ def set_messages(
333
+ span_obj: Any,
334
+ input_json: Optional[str],
335
+ output_json: Optional[str],
336
+ system_json: Optional[str] = None,
337
+ ) -> None:
338
+ """Set the Opt-In content attributes from pre-rendered JSON strings.
339
+
340
+ Takes the strings :func:`semconv.input_messages` and friends produce (which
341
+ are ``None`` unless the user opted in), so message lists never reach
342
+ :func:`_clean` -- whose ``str()`` fallback would emit a Python repr rather
343
+ than JSON. ``None`` values set no attribute.
344
+ """
345
+ if not _recording(span_obj):
346
+ return
347
+ for attr, value in (
348
+ (semconv.GEN_AI_INPUT_MESSAGES, input_json),
349
+ (semconv.GEN_AI_OUTPUT_MESSAGES, output_json),
350
+ (semconv.GEN_AI_SYSTEM_INSTRUCTIONS, system_json),
351
+ ):
352
+ if isinstance(value, str) and value:
353
+ span_obj.set_attribute(attr, value)
354
+
355
+
356
+ def _clean(attributes: Optional[Dict[str, Any]]) -> Dict[str, Any]:
357
+ """Drop None values and coerce non-primitive attribute values to str."""
358
+ if not attributes:
359
+ return {}
360
+ out: Dict[str, Any] = {}
361
+ for key, value in attributes.items():
362
+ if value is None:
363
+ continue
364
+ if isinstance(value, (str, bool, int, float)):
365
+ out[key] = value
366
+ elif isinstance(value, (list, tuple)) and all(
367
+ isinstance(item, (str, bool, int, float)) for item in value
368
+ ):
369
+ out[key] = list(value)
370
+ else:
371
+ out[key] = str(value)
372
+ return out