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
otelzero/semconv.py
ADDED
|
@@ -0,0 +1,327 @@
|
|
|
1
|
+
"""OpenTelemetry GenAI semantic-convention names otelzero speaks.
|
|
2
|
+
|
|
3
|
+
Every ``gen_ai.*`` attribute key, operation value, and span-name template used by
|
|
4
|
+
the client hooks and by the server's OTLP ingest/export lives here, so the wire
|
|
5
|
+
format has exactly one definition instead of being retyped across a dozen call
|
|
6
|
+
sites.
|
|
7
|
+
|
|
8
|
+
The conventions come from `open-telemetry/semantic-conventions-genai
|
|
9
|
+
<https://github.com/open-telemetry/semantic-conventions-genai>`_ (status:
|
|
10
|
+
development).
|
|
11
|
+
|
|
12
|
+
**Every otelzero span is ``SpanKind.INTERNAL``**, which decides most of what
|
|
13
|
+
follows. The conventions define a materially smaller attribute set for the *internal*
|
|
14
|
+
``invoke_agent`` span than for the ``client`` one, and otelzero is bound by the
|
|
15
|
+
former. Three consequences that all look like omissions otherwise:
|
|
16
|
+
|
|
17
|
+
* **``gen_ai.provider.name`` is not emitted.** It replaced the deprecated
|
|
18
|
+
``gen_ai.system``, but it names the *inference provider* (``openai``,
|
|
19
|
+
``anthropic``, ``aws.bedrock``) rather than the orchestration framework -- and
|
|
20
|
+
it is listed only on the ``create_agent`` and ``invoke_agent`` client spans.
|
|
21
|
+
otelzero's framework label stays on the ``service.name`` resource attribute
|
|
22
|
+
instead. The constant remains defined because ingest still *reads* it from
|
|
23
|
+
third-party traces.
|
|
24
|
+
* **``gen_ai.agent.id`` is not emitted** either, for the same reason plus a
|
|
25
|
+
second: the spec calls recording in-memory agent instance ids on it NOT
|
|
26
|
+
RECOMMENDED, and instance ids are all otelzero's hooks can see. See
|
|
27
|
+
``OTELZERO_AGENT_ID``.
|
|
28
|
+
* **There is no total-token attribute.** The spec records input and output
|
|
29
|
+
separately on purpose, so otelzero's total stays under its own ``otelzero.*``
|
|
30
|
+
namespace rather than squatting on a ``gen_ai.*`` name that may later mean
|
|
31
|
+
something else.
|
|
32
|
+
|
|
33
|
+
.. warning::
|
|
34
|
+
``otelzero.semconv`` and ``kiji_agent_registry.semconv`` are byte-for-byte
|
|
35
|
+
copies of each other. ``kiji-agent-registry`` does not depend on ``otelzero`` (they
|
|
36
|
+
install independently), so the vocabulary is duplicated rather than imported.
|
|
37
|
+
``tests/test_semconv_migration.py`` asserts the two files stay identical --
|
|
38
|
+
edit both, or neither.
|
|
39
|
+
"""
|
|
40
|
+
|
|
41
|
+
from typing import Optional
|
|
42
|
+
|
|
43
|
+
# --- Resource attributes -----------------------------------------------------
|
|
44
|
+
# otelzero labels a trace's framework with service.name, since the GenAI
|
|
45
|
+
# conventions have no attribute for "which agent framework produced this".
|
|
46
|
+
SERVICE_NAME = "service.name"
|
|
47
|
+
SERVICE_VERSION = "service.version"
|
|
48
|
+
|
|
49
|
+
# --- Span attributes: GenAI conventions --------------------------------------
|
|
50
|
+
GEN_AI_OPERATION_NAME = "gen_ai.operation.name"
|
|
51
|
+
GEN_AI_AGENT_NAME = "gen_ai.agent.name"
|
|
52
|
+
GEN_AI_AGENT_DESCRIPTION = "gen_ai.agent.description"
|
|
53
|
+
|
|
54
|
+
# Defined on the ``create_agent`` and ``invoke_agent`` *client* spans only, so
|
|
55
|
+
# otelzero reads them off third-party traces but never emits them -- every span
|
|
56
|
+
# it emits is INTERNAL. See the note on OTELZERO_AGENT_ID below.
|
|
57
|
+
GEN_AI_PROVIDER_NAME = "gen_ai.provider.name"
|
|
58
|
+
GEN_AI_AGENT_ID = "gen_ai.agent.id"
|
|
59
|
+
GEN_AI_CONVERSATION_ID = "gen_ai.conversation.id"
|
|
60
|
+
GEN_AI_WORKFLOW_NAME = "gen_ai.workflow.name"
|
|
61
|
+
GEN_AI_REQUEST_MODEL = "gen_ai.request.model"
|
|
62
|
+
GEN_AI_RESPONSE_MODEL = "gen_ai.response.model"
|
|
63
|
+
# Where the conventions carry a run's stop reasons. The per-message
|
|
64
|
+
# ``finish_reason`` field is deprecated in favour of this attribute.
|
|
65
|
+
GEN_AI_RESPONSE_FINISH_REASONS = "gen_ai.response.finish_reasons"
|
|
66
|
+
GEN_AI_TOOL_NAME = "gen_ai.tool.name"
|
|
67
|
+
GEN_AI_TOOL_CALL_ID = "gen_ai.tool.call.id"
|
|
68
|
+
GEN_AI_TOOL_DEFINITIONS = "gen_ai.tool.definitions"
|
|
69
|
+
# Opt-In content attributes: the run's prompt, its response, and the system
|
|
70
|
+
# prompt. Carried as JSON strings (see ``input_messages`` and friends below) and
|
|
71
|
+
# absent unless the user sets CAPTURE_CONTENT_ENV.
|
|
72
|
+
GEN_AI_INPUT_MESSAGES = "gen_ai.input.messages"
|
|
73
|
+
GEN_AI_OUTPUT_MESSAGES = "gen_ai.output.messages"
|
|
74
|
+
GEN_AI_SYSTEM_INSTRUCTIONS = "gen_ai.system_instructions"
|
|
75
|
+
GEN_AI_USAGE_INPUT_TOKENS = "gen_ai.usage.input_tokens"
|
|
76
|
+
GEN_AI_USAGE_OUTPUT_TOKENS = "gen_ai.usage.output_tokens"
|
|
77
|
+
GEN_AI_USAGE_REASONING_OUTPUT_TOKENS = "gen_ai.usage.reasoning.output_tokens"
|
|
78
|
+
GEN_AI_USAGE_CACHE_READ_INPUT_TOKENS = "gen_ai.usage.cache_read.input_tokens"
|
|
79
|
+
|
|
80
|
+
# --- Span attributes: general conventions ------------------------------------
|
|
81
|
+
# Both are span-level, not resource-level: one process can serve many users and
|
|
82
|
+
# many concurrent flows, so this identity has to vary per run.
|
|
83
|
+
USER_NAME = "user.name"
|
|
84
|
+
ERROR_TYPE = "error.type"
|
|
85
|
+
|
|
86
|
+
# --- Span attributes: otelzero extensions ------------------------------------
|
|
87
|
+
# Namespaced under otelzero.* because the GenAI conventions have no equivalent.
|
|
88
|
+
# The instrumentation library owns this namespace: otelzero is usable against
|
|
89
|
+
# any OTLP backend, so the vocabulary is named for the emitter, not for whichever
|
|
90
|
+
# server happens to receive it.
|
|
91
|
+
OTELZERO_USAGE_TOTAL_TOKENS = "otelzero.usage.total_tokens"
|
|
92
|
+
OTELZERO_AGENT_CLASS = "otelzero.agent.class"
|
|
93
|
+
# The human title of the session a span belongs to (``name=`` on an install call,
|
|
94
|
+
# or run_context(name=...)). gen_ai.conversation.id carries the session's id;
|
|
95
|
+
# the conventions have no attribute for its display name.
|
|
96
|
+
OTELZERO_SESSION_NAME = "otelzero.session.name"
|
|
97
|
+
# Not gen_ai.agent.id: that attribute is absent from the internal invoke_agent
|
|
98
|
+
# span, and the conventions say it is NOT RECOMMENDED to record in-memory agent
|
|
99
|
+
# instance ids on it "due to their transient nature" -- which is exactly what
|
|
100
|
+
# Strands' Agent.agent_id and Agent Framework's Agent.id are.
|
|
101
|
+
OTELZERO_AGENT_ID = "otelzero.agent.id"
|
|
102
|
+
OTELZERO_TASK_DESCRIPTION = "otelzero.task.description"
|
|
103
|
+
OTELZERO_TASK_EXPECTED_OUTPUT = "otelzero.task.expected_output"
|
|
104
|
+
OTELZERO_NUM_AGENTS = "otelzero.num_agents"
|
|
105
|
+
OTELZERO_NUM_TASKS = "otelzero.num_tasks"
|
|
106
|
+
OTELZERO_NUM_MESSAGES = "otelzero.num_messages"
|
|
107
|
+
OTELZERO_STEPS = "otelzero.steps"
|
|
108
|
+
# Where the registry's export puts stored message content when the *server*
|
|
109
|
+
# process has not opted in to the gen_ai.* content attributes: the export is a
|
|
110
|
+
# dump of what is already stored, so the content is respelled rather than
|
|
111
|
+
# dropped. Ingest reads these too, so an export re-ingests as a fixpoint.
|
|
112
|
+
OTELZERO_INPUT_MESSAGES = "otelzero.input_messages"
|
|
113
|
+
OTELZERO_OUTPUT_MESSAGES = "otelzero.output_messages"
|
|
114
|
+
OTELZERO_SYSTEM_INSTRUCTIONS = "otelzero.system_instructions"
|
|
115
|
+
|
|
116
|
+
# --- Operation values --------------------------------------------------------
|
|
117
|
+
# The gen_ai.operation.name enum entries otelzero emits.
|
|
118
|
+
OP_INVOKE_AGENT = "invoke_agent"
|
|
119
|
+
OP_INVOKE_WORKFLOW = "invoke_workflow"
|
|
120
|
+
OP_CREATE_AGENT = "create_agent"
|
|
121
|
+
OP_EXECUTE_TOOL = "execute_tool"
|
|
122
|
+
OP_CHAT = "chat"
|
|
123
|
+
OP_TEXT_COMPLETION = "text_completion"
|
|
124
|
+
OP_GENERATE_CONTENT = "generate_content"
|
|
125
|
+
OP_EMBEDDINGS = "embeddings"
|
|
126
|
+
OP_RETRIEVAL = "retrieval"
|
|
127
|
+
OP_PLAN = "plan"
|
|
128
|
+
|
|
129
|
+
# A CrewAI Task is the *parent* of the agent invocation it delegates to, so none
|
|
130
|
+
# of the predefined values fit. The enum permits a custom value where none
|
|
131
|
+
# applies ("otherwise, a custom value MAY be used"); it is documented in the
|
|
132
|
+
# README as the spec asks.
|
|
133
|
+
OP_EXECUTE_TASK = "execute_task"
|
|
134
|
+
|
|
135
|
+
# --- Superseded names, read on ingest only -----------------------------------
|
|
136
|
+
# The client emits the names above and nothing else. The server keeps reading
|
|
137
|
+
# these so a client older than the server it reports to still produces agent
|
|
138
|
+
# cards and token counts. See kiji_agent_registry.otlp.
|
|
139
|
+
#
|
|
140
|
+
# The whole ``mira.*`` namespace lives here now: it was the extension vocabulary
|
|
141
|
+
# before the rename to ``otelzero.*``, and agents deployed against the old
|
|
142
|
+
# release are still emitting it. Ingest reads it; export never writes it.
|
|
143
|
+
LEGACY_GEN_AI_SYSTEM = "gen_ai.system"
|
|
144
|
+
LEGACY_MIRA_USER = "mira.user"
|
|
145
|
+
LEGACY_MIRA_USAGE_REASONING_TOKENS = "mira.usage.reasoning_tokens"
|
|
146
|
+
LEGACY_MIRA_USAGE_CACHE_READ_TOKENS = "mira.usage.cache_read_tokens"
|
|
147
|
+
LEGACY_MIRA_AGENT_GOAL = "mira.agent.goal"
|
|
148
|
+
LEGACY_MIRA_AGENT_TOOLS = "mira.agent.tools"
|
|
149
|
+
LEGACY_MIRA_TOOL_CALL_ID = "mira.tool.call_id"
|
|
150
|
+
LEGACY_MIRA_CHAIN = "mira.chain"
|
|
151
|
+
LEGACY_MIRA_APP_NAME = "mira.app_name"
|
|
152
|
+
|
|
153
|
+
# The pre-rename spellings of the nine attributes above.
|
|
154
|
+
LEGACY_MIRA_USAGE_TOTAL_TOKENS = "mira.usage.total_tokens"
|
|
155
|
+
LEGACY_MIRA_AGENT_CLASS = "mira.agent.class"
|
|
156
|
+
LEGACY_MIRA_AGENT_ID = "mira.agent.id"
|
|
157
|
+
LEGACY_MIRA_TASK_DESCRIPTION = "mira.task.description"
|
|
158
|
+
LEGACY_MIRA_TASK_EXPECTED_OUTPUT = "mira.task.expected_output"
|
|
159
|
+
LEGACY_MIRA_NUM_AGENTS = "mira.num_agents"
|
|
160
|
+
LEGACY_MIRA_NUM_TASKS = "mira.num_tasks"
|
|
161
|
+
LEGACY_MIRA_NUM_MESSAGES = "mira.num_messages"
|
|
162
|
+
LEGACY_MIRA_STEPS = "mira.steps"
|
|
163
|
+
|
|
164
|
+
LEGACY_OP_CREW = "crew"
|
|
165
|
+
LEGACY_OP_AGENT = "agent"
|
|
166
|
+
LEGACY_OP_TASK = "task"
|
|
167
|
+
|
|
168
|
+
# Pre-1.0 span names, still matched by the ingest when a span carries no
|
|
169
|
+
# recognizable gen_ai.operation.name.
|
|
170
|
+
LEGACY_SPAN_NAME_CREW = "crew.kickoff"
|
|
171
|
+
LEGACY_SPAN_NAME_AGENT = "agent.execute_task"
|
|
172
|
+
LEGACY_SPAN_NAME_TASK = "task.execute"
|
|
173
|
+
LEGACY_SPAN_NAME_LANGCHAIN_AGENT = "langchain.agent.invoke"
|
|
174
|
+
|
|
175
|
+
|
|
176
|
+
def span_name(operation: str, subject: Optional[str] = None) -> str:
|
|
177
|
+
"""Build a span name from the ``{operation} {subject}`` templates.
|
|
178
|
+
|
|
179
|
+
The conventions name spans after the operation plus its subject -- the agent
|
|
180
|
+
name for ``invoke_agent``, the workflow name for ``invoke_workflow``, the
|
|
181
|
+
tool name for ``execute_tool`` -- and fall back to the bare operation when
|
|
182
|
+
the subject is not readily available.
|
|
183
|
+
"""
|
|
184
|
+
subject = (subject or "").strip()
|
|
185
|
+
return f"{operation} {subject}" if subject else operation
|
|
186
|
+
|
|
187
|
+
|
|
188
|
+
# The conventions' opt-in switch for recording instructions, inputs, and
|
|
189
|
+
# outputs. gen_ai.tool.definitions, gen_ai.input.messages, gen_ai.output.messages
|
|
190
|
+
# and gen_ai.system_instructions all sit at requirement level Opt-In, which means
|
|
191
|
+
# "add if and only if the user configures the instrumentation to do so".
|
|
192
|
+
CAPTURE_CONTENT_ENV = "OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT"
|
|
193
|
+
|
|
194
|
+
|
|
195
|
+
def capture_content_enabled() -> bool:
|
|
196
|
+
"""True when the user has opted in to recording GenAI content.
|
|
197
|
+
|
|
198
|
+
Besides the boolean spellings this takes the conventions' ``SPAN_ONLY`` and
|
|
199
|
+
``SPAN_AND_EVENT`` modes, in any case. otelzero records content on spans
|
|
200
|
+
only, so ``EVENT_ONLY`` and ``NO_CONTENT`` leave it off.
|
|
201
|
+
"""
|
|
202
|
+
import os
|
|
203
|
+
|
|
204
|
+
return os.environ.get(CAPTURE_CONTENT_ENV, "").strip().lower() in (
|
|
205
|
+
"1",
|
|
206
|
+
"true",
|
|
207
|
+
"yes",
|
|
208
|
+
"on",
|
|
209
|
+
"span_only",
|
|
210
|
+
"span_and_event",
|
|
211
|
+
)
|
|
212
|
+
|
|
213
|
+
|
|
214
|
+
def tool_definitions(names) -> Optional[str]:
|
|
215
|
+
"""Render tool *names* as a ``gen_ai.tool.definitions`` JSON string.
|
|
216
|
+
|
|
217
|
+
Returns ``None`` unless content capture is opted in, so callers can pass this
|
|
218
|
+
straight into a span-attribute dict and have it dropped by default. otelzero's
|
|
219
|
+
own dashboard and apps are unaffected either way: the tool list also rides
|
|
220
|
+
the log envelope's ``details``, which is what they actually read.
|
|
221
|
+
|
|
222
|
+
otelzero's hooks can see which tools an agent was given but not their parameter
|
|
223
|
+
schemas, so each becomes a minimal function entry. The attribute is defined
|
|
224
|
+
as structured data; spans may carry it as a JSON string where structured
|
|
225
|
+
values are not supported, which is the case for OTLP attributes.
|
|
226
|
+
"""
|
|
227
|
+
import json
|
|
228
|
+
|
|
229
|
+
if not capture_content_enabled():
|
|
230
|
+
return None
|
|
231
|
+
entries = [{"type": "function", "name": str(n)} for n in (names or []) if n]
|
|
232
|
+
return json.dumps(entries) if entries else None
|
|
233
|
+
|
|
234
|
+
|
|
235
|
+
# --- Message content ---------------------------------------------------------
|
|
236
|
+
# The conventions define gen_ai.input.messages / gen_ai.output.messages as
|
|
237
|
+
# structured data: an array of chat messages, each ``{"role": ..., "parts":
|
|
238
|
+
# [...]}`` where a part is one of
|
|
239
|
+
#
|
|
240
|
+
# {"type": "text", "content": "..."}
|
|
241
|
+
# {"type": "reasoning", "content": "..."}
|
|
242
|
+
# {"type": "tool_call", "id": "...", "name": "...", "arguments": ...}
|
|
243
|
+
# {"type": "tool_call_response", "id": "...", "response": ...}
|
|
244
|
+
#
|
|
245
|
+
# Roles are ``user``, ``system``, ``assistant`` or ``tool``.
|
|
246
|
+
# gen_ai.system_instructions is a bare array of parts. OTLP attributes cannot
|
|
247
|
+
# carry nested values, so all three ride the wire as JSON strings; the builders
|
|
248
|
+
# below render them.
|
|
249
|
+
#
|
|
250
|
+
# A run's stop reasons are *not* part of this content: an output message's
|
|
251
|
+
# ``finish_reason`` field is deprecated, and the reasons ride the separate
|
|
252
|
+
# gen_ai.response.finish_reasons attribute instead (see :func:`finish_reasons`).
|
|
253
|
+
#
|
|
254
|
+
# Shaping a framework's prompt/response into these messages (and bounding
|
|
255
|
+
# their size) is the client's job -- see ``otelzero.hooks._content`` -- so this
|
|
256
|
+
# module stays a pure vocabulary the server copy can share unchanged.
|
|
257
|
+
|
|
258
|
+
|
|
259
|
+
def _text_message(role: str, text: str, **extra) -> dict:
|
|
260
|
+
return {"role": role, "parts": [{"type": "text", "content": text}], **extra}
|
|
261
|
+
|
|
262
|
+
|
|
263
|
+
def input_messages(messages) -> Optional[str]:
|
|
264
|
+
"""Render a run's prompt as a ``gen_ai.input.messages`` JSON string.
|
|
265
|
+
|
|
266
|
+
``messages`` is a list of already-shaped message dicts, or a bare string
|
|
267
|
+
(wrapped as one ``user`` text message). Returns ``None`` unless content
|
|
268
|
+
capture is opted in, or when there is nothing to record, so callers can pass
|
|
269
|
+
the result straight into a span-attribute dict.
|
|
270
|
+
"""
|
|
271
|
+
import json
|
|
272
|
+
|
|
273
|
+
if not capture_content_enabled() or not messages:
|
|
274
|
+
return None
|
|
275
|
+
if isinstance(messages, str):
|
|
276
|
+
messages = [_text_message("user", messages)]
|
|
277
|
+
return json.dumps(list(messages))
|
|
278
|
+
|
|
279
|
+
|
|
280
|
+
def output_messages(messages) -> Optional[str]:
|
|
281
|
+
"""Render a run's response as a ``gen_ai.output.messages`` JSON string.
|
|
282
|
+
|
|
283
|
+
``messages`` is a list of already-shaped message dicts, or a bare string
|
|
284
|
+
(wrapped as one ``assistant`` text message). Same ``None`` contract as
|
|
285
|
+
:func:`input_messages`. Stop reasons are not stamped onto the messages --
|
|
286
|
+
see :func:`finish_reasons`.
|
|
287
|
+
"""
|
|
288
|
+
import json
|
|
289
|
+
|
|
290
|
+
if not capture_content_enabled() or not messages:
|
|
291
|
+
return None
|
|
292
|
+
if isinstance(messages, str):
|
|
293
|
+
messages = [_text_message("assistant", messages)]
|
|
294
|
+
return json.dumps(list(messages))
|
|
295
|
+
|
|
296
|
+
|
|
297
|
+
def finish_reasons(reasons) -> Optional[tuple]:
|
|
298
|
+
"""Render a run's stop reasons as a ``gen_ai.response.finish_reasons`` value.
|
|
299
|
+
|
|
300
|
+
The conventions carry finish reasons on the span -- one per generated choice
|
|
301
|
+
-- and deprecate the ``finish_reason`` field an output message used to hold.
|
|
302
|
+
A bare string is one reason. Unlike the message content this is not Opt-In:
|
|
303
|
+
a stop reason names *how* a run ended, not what was said.
|
|
304
|
+
|
|
305
|
+
``None`` when nothing was reported, so a run whose framework named no reason
|
|
306
|
+
sets no attribute rather than claiming it stopped cleanly.
|
|
307
|
+
"""
|
|
308
|
+
if not reasons:
|
|
309
|
+
return None
|
|
310
|
+
if isinstance(reasons, str):
|
|
311
|
+
reasons = [reasons]
|
|
312
|
+
return tuple(str(r) for r in reasons if r) or None
|
|
313
|
+
|
|
314
|
+
|
|
315
|
+
def system_instructions(parts) -> Optional[str]:
|
|
316
|
+
"""Render a system prompt as a ``gen_ai.system_instructions`` JSON string.
|
|
317
|
+
|
|
318
|
+
``parts`` is a list of already-shaped parts, or a bare string (wrapped as one
|
|
319
|
+
text part). Same ``None`` contract as :func:`input_messages`.
|
|
320
|
+
"""
|
|
321
|
+
import json
|
|
322
|
+
|
|
323
|
+
if not capture_content_enabled() or not parts:
|
|
324
|
+
return None
|
|
325
|
+
if isinstance(parts, str):
|
|
326
|
+
parts = [{"type": "text", "content": parts}]
|
|
327
|
+
return json.dumps(list(parts))
|
otelzero/telemetry.py
ADDED
|
@@ -0,0 +1,238 @@
|
|
|
1
|
+
"""The telemetry client: turns agent lifecycle events into server-bound logs.
|
|
2
|
+
|
|
3
|
+
``TelemetryClient`` owns the HTTP connection to the monitoring server and the
|
|
4
|
+
background-send machinery. Framework import hooks (see :mod:`otelzero.hooks`)
|
|
5
|
+
call into a shared instance of this class.
|
|
6
|
+
"""
|
|
7
|
+
|
|
8
|
+
import os
|
|
9
|
+
import threading
|
|
10
|
+
import uuid
|
|
11
|
+
from datetime import datetime, timezone
|
|
12
|
+
from typing import Dict, Optional, Tuple
|
|
13
|
+
|
|
14
|
+
import httpx
|
|
15
|
+
|
|
16
|
+
from otelzero import otel
|
|
17
|
+
from otelzero.context import current_scope
|
|
18
|
+
from otelzero.detection import _detect_framework_version, _detect_user
|
|
19
|
+
|
|
20
|
+
|
|
21
|
+
def derive_session_name(text: Optional[str], max_len: int = 48) -> Optional[str]:
|
|
22
|
+
"""Turn a run's intent text (a task/goal/prompt) into a short, stable title.
|
|
23
|
+
|
|
24
|
+
Deterministic and cheap -- no LLM call: take the first non-empty line,
|
|
25
|
+
collapse whitespace, strip wrapping quotes/backticks, and truncate on a word
|
|
26
|
+
boundary with an ellipsis. This is what makes a session read as
|
|
27
|
+
"Summarize Q3 earnings call" instead of a random codename, and because it is
|
|
28
|
+
pure the same intent always yields the same title. Returns ``None`` for empty
|
|
29
|
+
or whitespace-only input so callers can fall back to a codename.
|
|
30
|
+
"""
|
|
31
|
+
if not text:
|
|
32
|
+
return None
|
|
33
|
+
line = next((ln.strip() for ln in str(text).splitlines() if ln.strip()), "")
|
|
34
|
+
line = " ".join(line.split()).strip("\"'`")
|
|
35
|
+
if not line:
|
|
36
|
+
return None
|
|
37
|
+
if len(line) > max_len:
|
|
38
|
+
head = line[:max_len].rsplit(" ", 1)[0]
|
|
39
|
+
line = (head or line[:max_len]).rstrip(" ,.;:—-") + "…"
|
|
40
|
+
return line
|
|
41
|
+
|
|
42
|
+
|
|
43
|
+
class TelemetryClient:
|
|
44
|
+
"""Client for sending telemetry data to the monitoring server"""
|
|
45
|
+
|
|
46
|
+
def __init__(
|
|
47
|
+
self,
|
|
48
|
+
server_url: str = "http://localhost:8000",
|
|
49
|
+
framework: Optional[str] = None,
|
|
50
|
+
framework_version: Optional[str] = None,
|
|
51
|
+
user: Optional[str] = None,
|
|
52
|
+
api_key: Optional[str] = None,
|
|
53
|
+
session: Optional[str] = None,
|
|
54
|
+
model: Optional[str] = None,
|
|
55
|
+
name: Optional[str] = None,
|
|
56
|
+
):
|
|
57
|
+
self.server_url = server_url
|
|
58
|
+
self.framework = framework
|
|
59
|
+
# Detect the framework's installed version when not provided.
|
|
60
|
+
self.framework_version = framework_version or _detect_framework_version(
|
|
61
|
+
framework
|
|
62
|
+
)
|
|
63
|
+
# Default LLM model id for logs that don't carry a per-run one. Unlike
|
|
64
|
+
# the framework version there is nothing to auto-detect at install time
|
|
65
|
+
# (the model lives on each run's options), so hooks pass it per call.
|
|
66
|
+
self.model = model
|
|
67
|
+
# Fall back to the OS login name when no user is provided.
|
|
68
|
+
self.user = user or _detect_user()
|
|
69
|
+
# The ingest key ties events to an owner so the iOS app sees only its
|
|
70
|
+
# own agents. Falls back to the OTELZERO_API_KEY env var.
|
|
71
|
+
self.api_key = api_key or os.environ.get("OTELZERO_API_KEY")
|
|
72
|
+
# A per-process session id so the app can group one run's events. When a
|
|
73
|
+
# process serves several callers, wrap each run in run_context() to give
|
|
74
|
+
# it its own id instead -- see otelzero.context.
|
|
75
|
+
self.session = session or os.environ.get("OTELZERO_SESSION") or uuid.uuid4().hex[:8]
|
|
76
|
+
# A short, human title for this run, shown identically across the web
|
|
77
|
+
# dashboard and the mobile apps (they render this instead of each deriving
|
|
78
|
+
# a codename from the id). An explicit name wins and is left untouched;
|
|
79
|
+
# otherwise the first framework hook to see the run's intent fills it in
|
|
80
|
+
# via suggest_session_name(). None until then -- clients fall back to a
|
|
81
|
+
# codename for an unnamed session.
|
|
82
|
+
explicit = name.strip() if isinstance(name, str) else None
|
|
83
|
+
self.session_name: Optional[str] = explicit or None
|
|
84
|
+
# Attach the ingest key to every request the client makes, not just the
|
|
85
|
+
# telemetry POST: a multi-tenant server (kiji-cloud) scopes reads to an
|
|
86
|
+
# owner and 401s any anonymous call (e.g. a demo's /api/stats reachability
|
|
87
|
+
# probe), so the credential has to ride on the client by construction.
|
|
88
|
+
default_headers = (
|
|
89
|
+
{"Authorization": f"Bearer {self.api_key}"} if self.api_key else {}
|
|
90
|
+
)
|
|
91
|
+
self.client = httpx.Client(timeout=5.0, headers=default_headers)
|
|
92
|
+
self._send_queue = []
|
|
93
|
+
self._lock = threading.Lock()
|
|
94
|
+
|
|
95
|
+
# Configure OpenTelemetry tracing (on by default; a no-op without the
|
|
96
|
+
# 'otel' extra or with OTELZERO_OTEL=0). Idempotent across multiple clients.
|
|
97
|
+
otel.init_tracing(
|
|
98
|
+
server_url,
|
|
99
|
+
service_name=framework or "otelzero-agent",
|
|
100
|
+
service_version=self.framework_version,
|
|
101
|
+
api_key=self.api_key,
|
|
102
|
+
identity=self.run_identity,
|
|
103
|
+
)
|
|
104
|
+
|
|
105
|
+
def run_identity(self) -> Tuple[Optional[str], str, Optional[str]]:
|
|
106
|
+
"""``(user, session, session_name)`` for the run currently in scope.
|
|
107
|
+
|
|
108
|
+
A :func:`~otelzero.context.run_context` block overrides the client's
|
|
109
|
+
process-wide defaults, so one process serving several users reports each
|
|
110
|
+
run under its own identity instead of merging them. Outside such a block
|
|
111
|
+
this is just the client's own fields.
|
|
112
|
+
"""
|
|
113
|
+
scope = current_scope()
|
|
114
|
+
if scope is None:
|
|
115
|
+
return self.user, self.session, self.session_name
|
|
116
|
+
return scope.user or self.user, scope.conversation_id, scope.session_name
|
|
117
|
+
|
|
118
|
+
def suggest_session_name(self, text: Optional[str]) -> None:
|
|
119
|
+
"""Name the session from a run's intent text -- first meaningful wins.
|
|
120
|
+
|
|
121
|
+
A no-op once a name is set (explicitly at construction or by an earlier
|
|
122
|
+
suggestion), so the title is stable for the life of the run and never
|
|
123
|
+
flips as more events stream in. Framework hooks call this with the best
|
|
124
|
+
intent text they have (a task description, agent goal, or prompt) just
|
|
125
|
+
before the run's start event, so every subsequent log carries the name.
|
|
126
|
+
|
|
127
|
+
Inside a :func:`~otelzero.context.run_context` the title belongs to
|
|
128
|
+
that flow rather than the process, so concurrent runs don't inherit
|
|
129
|
+
whichever one happened to be named first.
|
|
130
|
+
"""
|
|
131
|
+
scope = current_scope()
|
|
132
|
+
if scope.session_name if scope is not None else self.session_name:
|
|
133
|
+
return
|
|
134
|
+
title = derive_session_name(text)
|
|
135
|
+
if not title:
|
|
136
|
+
return
|
|
137
|
+
if scope is not None:
|
|
138
|
+
scope.session_name = title
|
|
139
|
+
else:
|
|
140
|
+
self.session_name = title
|
|
141
|
+
|
|
142
|
+
def send_log(
|
|
143
|
+
self,
|
|
144
|
+
event_type: str,
|
|
145
|
+
agent_name: Optional[str] = None,
|
|
146
|
+
agent_role: Optional[str] = None,
|
|
147
|
+
model: Optional[str] = None,
|
|
148
|
+
details: Optional[Dict] = None,
|
|
149
|
+
error: Optional[str] = None,
|
|
150
|
+
traceback: Optional[str] = None,
|
|
151
|
+
session: Optional[str] = None,
|
|
152
|
+
):
|
|
153
|
+
"""Send a log entry to the server.
|
|
154
|
+
|
|
155
|
+
``session`` overrides the run's session id, for a hook that files a run
|
|
156
|
+
under the framework's own conversation id (see
|
|
157
|
+
:mod:`otelzero.hooks._native`).
|
|
158
|
+
"""
|
|
159
|
+
user, scope_session, session_name = self.run_identity()
|
|
160
|
+
session = session or scope_session
|
|
161
|
+
log_data = {
|
|
162
|
+
"event_type": event_type,
|
|
163
|
+
"timestamp": datetime.now(timezone.utc).isoformat(),
|
|
164
|
+
"session": session,
|
|
165
|
+
"session_name": session_name,
|
|
166
|
+
"agent_name": agent_name,
|
|
167
|
+
"agent_role": agent_role,
|
|
168
|
+
"framework": self.framework,
|
|
169
|
+
"framework_version": self.framework_version,
|
|
170
|
+
"model": model or self.model,
|
|
171
|
+
"user": user,
|
|
172
|
+
"details": details,
|
|
173
|
+
"error": error,
|
|
174
|
+
"traceback": traceback,
|
|
175
|
+
}
|
|
176
|
+
|
|
177
|
+
# Send in background thread to not block execution
|
|
178
|
+
threading.Thread(target=self._send_async, args=(log_data,), daemon=True).start()
|
|
179
|
+
|
|
180
|
+
def _send_async(self, log_data: Dict):
|
|
181
|
+
"""Send log data asynchronously"""
|
|
182
|
+
headers = {}
|
|
183
|
+
if self.api_key:
|
|
184
|
+
headers["Authorization"] = f"Bearer {self.api_key}"
|
|
185
|
+
try:
|
|
186
|
+
response = self.client.post(
|
|
187
|
+
f"{self.server_url}/api/telemetry", json=log_data, headers=headers
|
|
188
|
+
)
|
|
189
|
+
if response.status_code != 200:
|
|
190
|
+
print(f"[TELEMETRY] Failed to send log: {response.status_code}")
|
|
191
|
+
except Exception as e:
|
|
192
|
+
print(f"[TELEMETRY] Error sending log: {e}")
|
|
193
|
+
|
|
194
|
+
|
|
195
|
+
def install_monitoring(
|
|
196
|
+
server_url: str = "http://localhost:8000",
|
|
197
|
+
framework: Optional[str] = None,
|
|
198
|
+
framework_version: Optional[str] = None,
|
|
199
|
+
user: Optional[str] = None,
|
|
200
|
+
api_key: Optional[str] = None,
|
|
201
|
+
session: Optional[str] = None,
|
|
202
|
+
model: Optional[str] = None,
|
|
203
|
+
name: Optional[str] = None,
|
|
204
|
+
):
|
|
205
|
+
"""
|
|
206
|
+
Create a TelemetryClient for manual instrumentation (framework-agnostic).
|
|
207
|
+
|
|
208
|
+
Args:
|
|
209
|
+
server_url: URL of the monitoring server
|
|
210
|
+
framework: Name of the agent framework (e.g. "LangChain", "AutoGen")
|
|
211
|
+
framework_version: Version string of the framework. Auto-detected from
|
|
212
|
+
installed package if not provided and framework is set.
|
|
213
|
+
user: Name of the executing user
|
|
214
|
+
api_key: Ingest key tying events to an owner (so the iOS app sees only
|
|
215
|
+
its own agents). Falls back to the OTELZERO_API_KEY env var.
|
|
216
|
+
session: Per-run id used to group events in the app. Defaults to a
|
|
217
|
+
random id.
|
|
218
|
+
model: LLM model id attached to every log (e.g. "gpt-4o"). Per-call
|
|
219
|
+
values passed to ``send_log`` take precedence.
|
|
220
|
+
name: Explicit human title for this run, shown across the dashboard and
|
|
221
|
+
mobile apps. When omitted the title is derived from the run's intent
|
|
222
|
+
(task/goal/prompt) as events are instrumented, falling back to a
|
|
223
|
+
codename if none is captured.
|
|
224
|
+
"""
|
|
225
|
+
telemetry = TelemetryClient(
|
|
226
|
+
server_url,
|
|
227
|
+
framework=framework,
|
|
228
|
+
framework_version=framework_version,
|
|
229
|
+
user=user,
|
|
230
|
+
api_key=api_key,
|
|
231
|
+
session=session,
|
|
232
|
+
model=model,
|
|
233
|
+
name=name,
|
|
234
|
+
)
|
|
235
|
+
print(
|
|
236
|
+
f"[MONITOR] Monitoring installed (server: {server_url}, framework: {framework})"
|
|
237
|
+
)
|
|
238
|
+
return telemetry
|