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.
- otelzero/__init__.py +62 -0
- otelzero/__main__.py +140 -0
- otelzero/context.py +86 -0
- otelzero/detection.py +58 -0
- otelzero/hooks/__init__.py +96 -0
- otelzero/hooks/_content.py +865 -0
- otelzero/hooks/_langsmith.py +504 -0
- otelzero/hooks/_native.py +517 -0
- otelzero/hooks/_usage.py +166 -0
- otelzero/hooks/adk.py +128 -0
- otelzero/hooks/base.py +546 -0
- otelzero/hooks/claude_sdk.py +267 -0
- otelzero/hooks/crewai.py +338 -0
- otelzero/hooks/databricks.py +260 -0
- otelzero/hooks/langchain.py +56 -0
- otelzero/hooks/langgraph.py +57 -0
- otelzero/hooks/llama_index.py +724 -0
- otelzero/hooks/microsoft.py +160 -0
- otelzero/hooks/openai_agents.py +313 -0
- otelzero/hooks/pydantic_ai.py +173 -0
- otelzero/hooks/smolagents.py +331 -0
- otelzero/hooks/snowflake.py +271 -0
- otelzero/hooks/strands.py +173 -0
- otelzero/otel.py +372 -0
- otelzero/semconv.py +327 -0
- otelzero/telemetry.py +238 -0
- otelzero/translate/__init__.py +214 -0
- otelzero/translate/langsmith.py +401 -0
- otelzero-0.2.0.dist-info/METADATA +1345 -0
- otelzero-0.2.0.dist-info/RECORD +33 -0
- otelzero-0.2.0.dist-info/WHEEL +5 -0
- otelzero-0.2.0.dist-info/licenses/LICENSE +202 -0
- otelzero-0.2.0.dist-info/top_level.txt +1 -0
|
@@ -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
|