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/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