respan-instrumentation-livekit 0.1.0__tar.gz

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,66 @@
1
+ Metadata-Version: 2.4
2
+ Name: respan-instrumentation-livekit
3
+ Version: 0.1.0
4
+ Summary: Respan instrumentation plugin for LiveKit Agents
5
+ License: Apache 2.0
6
+ Author: Respan
7
+ Author-email: team@respan.ai
8
+ Requires-Python: >=3.11,<3.14
9
+ Classifier: License :: Other/Proprietary License
10
+ Classifier: Programming Language :: Python :: 3
11
+ Classifier: Programming Language :: Python :: 3.11
12
+ Classifier: Programming Language :: Python :: 3.12
13
+ Classifier: Programming Language :: Python :: 3.13
14
+ Requires-Dist: livekit-agents (>=1.6.0)
15
+ Requires-Dist: opentelemetry-semantic-conventions-ai (>=0.4.1)
16
+ Requires-Dist: respan-sdk (>=2.6.1)
17
+ Requires-Dist: respan-tracing (>=2.17.0,<3.0.0)
18
+ Description-Content-Type: text/markdown
19
+
20
+ # Respan LiveKit Instrumentation
21
+
22
+ Respan instrumentation plugin for [LiveKit Agents](https://docs.livekit.io/agents/).
23
+ It translates LiveKit's native `livekit-agents` LLM spans into canonical Respan
24
+ chat spans and emits Respan tool spans for `execute_function_call`.
25
+
26
+ ## Installation
27
+
28
+ ```bash
29
+ pip install respan-ai respan-instrumentation-livekit livekit-agents
30
+ ```
31
+
32
+ ## Usage
33
+
34
+ ```python
35
+ import os
36
+
37
+ from livekit.agents import llm
38
+ from respan import Respan, workflow
39
+ from respan_instrumentation_livekit import LiveKitInstrumentor
40
+
41
+ respan = Respan(
42
+ api_key=os.environ["RESPAN_API_KEY"],
43
+ app_name="livekit-example",
44
+ instrumentations=[LiveKitInstrumentor()],
45
+ )
46
+
47
+
48
+ @workflow(name="livekit_chat.workflow")
49
+ async def run_chat(model: llm.LLM) -> str:
50
+ chat_ctx = llm.ChatContext.empty()
51
+ chat_ctx.add_message(role="user", content="Say hello in one sentence.")
52
+ response = await model.chat(chat_ctx=chat_ctx).collect()
53
+ return response.text
54
+ ```
55
+
56
+ ## Captured Spans
57
+
58
+ - LiveKit `LLMStream` requests become Respan `chat` spans with request messages,
59
+ completions, tool calls, tool definitions when available, model, provider, and
60
+ token usage.
61
+ - LiveKit `execute_function_call` executions become Respan `tool` spans.
62
+
63
+ Use `Respan(..., customer_identifier=..., thread_identifier=..., metadata=...)`
64
+ or `respan.propagate_attributes(...)` to attach Respan attributes to LiveKit
65
+ spans.
66
+
@@ -0,0 +1,46 @@
1
+ # Respan LiveKit Instrumentation
2
+
3
+ Respan instrumentation plugin for [LiveKit Agents](https://docs.livekit.io/agents/).
4
+ It translates LiveKit's native `livekit-agents` LLM spans into canonical Respan
5
+ chat spans and emits Respan tool spans for `execute_function_call`.
6
+
7
+ ## Installation
8
+
9
+ ```bash
10
+ pip install respan-ai respan-instrumentation-livekit livekit-agents
11
+ ```
12
+
13
+ ## Usage
14
+
15
+ ```python
16
+ import os
17
+
18
+ from livekit.agents import llm
19
+ from respan import Respan, workflow
20
+ from respan_instrumentation_livekit import LiveKitInstrumentor
21
+
22
+ respan = Respan(
23
+ api_key=os.environ["RESPAN_API_KEY"],
24
+ app_name="livekit-example",
25
+ instrumentations=[LiveKitInstrumentor()],
26
+ )
27
+
28
+
29
+ @workflow(name="livekit_chat.workflow")
30
+ async def run_chat(model: llm.LLM) -> str:
31
+ chat_ctx = llm.ChatContext.empty()
32
+ chat_ctx.add_message(role="user", content="Say hello in one sentence.")
33
+ response = await model.chat(chat_ctx=chat_ctx).collect()
34
+ return response.text
35
+ ```
36
+
37
+ ## Captured Spans
38
+
39
+ - LiveKit `LLMStream` requests become Respan `chat` spans with request messages,
40
+ completions, tool calls, tool definitions when available, model, provider, and
41
+ token usage.
42
+ - LiveKit `execute_function_call` executions become Respan `tool` spans.
43
+
44
+ Use `Respan(..., customer_identifier=..., thread_identifier=..., metadata=...)`
45
+ or `respan.propagate_attributes(...)` to attach Respan attributes to LiveKit
46
+ spans.
@@ -0,0 +1,29 @@
1
+ [tool.poetry]
2
+ name = "respan-instrumentation-livekit"
3
+ version = "0.1.0"
4
+ description = "Respan instrumentation plugin for LiveKit Agents"
5
+ authors = ["Respan <team@respan.ai>"]
6
+ license = "Apache 2.0"
7
+ readme = "README.md"
8
+ packages = [
9
+ { include = "respan_instrumentation_livekit", from = "./src" },
10
+ ]
11
+
12
+ [tool.poetry.dependencies]
13
+ python = ">=3.11,<3.14"
14
+ respan-tracing = "^2.17.0"
15
+ respan-sdk = ">=2.6.1"
16
+ livekit-agents = ">=1.6.0"
17
+ opentelemetry-semantic-conventions-ai = ">=0.4.1"
18
+
19
+ [tool.poetry.plugins."respan.instrumentations"]
20
+ livekit = "respan_instrumentation_livekit:LiveKitInstrumentor"
21
+
22
+ [tool.pytest.ini_options]
23
+ markers = [
24
+ "integration: live network tests (requires API keys)",
25
+ ]
26
+
27
+ [build-system]
28
+ requires = ["poetry-core"]
29
+ build-backend = "poetry.core.masonry.api"
@@ -0,0 +1,5 @@
1
+ """Respan LiveKit Agents instrumentation."""
2
+
3
+ from respan_instrumentation_livekit._instrumentation import LiveKitInstrumentor
4
+
5
+ __all__ = ["LiveKitInstrumentor"]
@@ -0,0 +1,32 @@
1
+ """LiveKit instrumentation constants.
2
+
3
+ LiveKit-owned ``lk.*`` keys stay package-local. Respan-owned keys are imported
4
+ from ``respan-sdk`` where they are used.
5
+ """
6
+
7
+ LIVEKIT_INSTRUMENTATION_NAME = "livekit"
8
+ LIVEKIT_SCOPE_NAME = "livekit-agents"
9
+ LIVEKIT_LLM_REQUEST_SPAN_NAME = "llm_request"
10
+ LIVEKIT_CHAT_SPAN_NAME = "livekit.llm.chat"
11
+
12
+ ASSISTANT_ROLE = "assistant"
13
+ FUNCTION_KEY = "function"
14
+ FUNCTION_TOOL_TYPE = "function"
15
+ ID_KEY = "id"
16
+ NAME_KEY = "name"
17
+ ROLE_KEY = "role"
18
+ TOOL_ROLE = "tool"
19
+ TYPE_KEY = "type"
20
+ USER_ROLE = "user"
21
+
22
+ ATTR_LLM_METRICS = "lk.llm_metrics"
23
+ ATTR_PROVIDER_REQUEST_IDS = "lk.provider_request_ids"
24
+
25
+ EVENT_GEN_AI_SYSTEM_MESSAGE = "gen_ai.system.message"
26
+ EVENT_GEN_AI_USER_MESSAGE = "gen_ai.user.message"
27
+ EVENT_GEN_AI_ASSISTANT_MESSAGE = "gen_ai.assistant.message"
28
+ EVENT_GEN_AI_TOOL_MESSAGE = "gen_ai.tool.message"
29
+ EVENT_GEN_AI_CHOICE = "gen_ai.choice"
30
+
31
+ LIVEKIT_RESPAN_TOOL_DEFINITIONS_ATTR = "lk.respan.function_tools"
32
+
@@ -0,0 +1,252 @@
1
+ """LiveKit Agents instrumentation plugin for Respan."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import functools
6
+ import importlib
7
+ import logging
8
+ import time
9
+ from typing import Any, Callable
10
+
11
+ from opentelemetry import trace
12
+
13
+ from respan_instrumentation_livekit._constants import (
14
+ LIVEKIT_INSTRUMENTATION_NAME,
15
+ LIVEKIT_RESPAN_TOOL_DEFINITIONS_ATTR,
16
+ )
17
+ from respan_instrumentation_livekit._otel_emitter import emit_livekit_tool_span
18
+ from respan_instrumentation_livekit._processor import LiveKitSpanProcessor
19
+ from respan_instrumentation_livekit._serialization import get_value, safe_json
20
+ from respan_instrumentation_livekit._translator import normalize_livekit_tools
21
+ from respan_tracing.core.tracer import RespanTracer
22
+
23
+ logger = logging.getLogger(__name__)
24
+
25
+ _ORIGINAL_UTILS_EXECUTE_FUNCTION_CALL: Callable[..., Any] | None = None
26
+ _ORIGINAL_EXPORTED_EXECUTE_FUNCTION_CALL: Callable[..., Any] | None = None
27
+ _ORIGINAL_LLM_STREAM_MAIN_TASK: Callable[..., Any] | None = None
28
+ _PATCHED_UTILS_MODULE: Any = None
29
+ _PATCHED_LLM_MODULE: Any = None
30
+ _PATCHED_LLM_STREAM_CLASS: Any = None
31
+ _ACTIVE_INSTANCES = 0
32
+
33
+
34
+ def _active_span_processors() -> tuple[Any, tuple[Any, ...] | None]:
35
+ tracer_provider = trace.get_tracer_provider()
36
+ active_span_processor = getattr(tracer_provider, "_active_span_processor", None)
37
+ processors = (
38
+ getattr(active_span_processor, "_span_processors", None)
39
+ if active_span_processor is not None
40
+ else None
41
+ )
42
+ return active_span_processor, processors
43
+
44
+
45
+ def _register_processor(processor: LiveKitSpanProcessor) -> None:
46
+ tracer_provider = trace.get_tracer_provider()
47
+ active_span_processor, processors = _active_span_processors()
48
+ if active_span_processor is not None and processors is not None:
49
+ remaining_processors = tuple(
50
+ existing for existing in processors if existing is not processor
51
+ )
52
+ active_span_processor._span_processors = (processor, *remaining_processors)
53
+ return
54
+
55
+ if hasattr(tracer_provider, "add_span_processor"):
56
+ tracer_provider.add_span_processor(processor)
57
+
58
+
59
+ def _unregister_processor(processor: LiveKitSpanProcessor) -> None:
60
+ active_span_processor, processors = _active_span_processors()
61
+ if active_span_processor is None or processors is None:
62
+ return
63
+ active_span_processor._span_processors = tuple(
64
+ existing for existing in processors if existing is not processor
65
+ )
66
+
67
+
68
+ def _patch_execute_function_call(utils_module: Any, llm_module: Any) -> None:
69
+ global _ORIGINAL_UTILS_EXECUTE_FUNCTION_CALL
70
+ global _ORIGINAL_EXPORTED_EXECUTE_FUNCTION_CALL
71
+ global _PATCHED_UTILS_MODULE
72
+ global _PATCHED_LLM_MODULE
73
+
74
+ if _ORIGINAL_UTILS_EXECUTE_FUNCTION_CALL is not None:
75
+ return
76
+
77
+ original = getattr(utils_module, "execute_function_call")
78
+ exported_original = getattr(llm_module, "execute_function_call", None)
79
+
80
+ @functools.wraps(original)
81
+ async def wrapped_execute_function_call(*args: Any, **kwargs: Any) -> Any:
82
+ start_time_ns = time.time_ns()
83
+ result = await original(*args, **kwargs)
84
+
85
+ tool_call = args[0] if args else kwargs.get("tool_call")
86
+ tool_name = (
87
+ get_value(get_value(result, "fnc_call"), "name")
88
+ or get_value(tool_call, "name")
89
+ or "livekit.tool"
90
+ )
91
+ arguments = (
92
+ get_value(get_value(result, "fnc_call"), "arguments")
93
+ or get_value(tool_call, "arguments")
94
+ or {}
95
+ )
96
+ call_id = (
97
+ get_value(get_value(result, "fnc_call"), "call_id")
98
+ or get_value(tool_call, "call_id")
99
+ )
100
+ raw_exception = get_value(result, "raw_exception")
101
+ fnc_call_out = get_value(result, "fnc_call_out")
102
+ output = get_value(result, "raw_output")
103
+ if output is None and fnc_call_out is not None:
104
+ output = get_value(fnc_call_out, "output")
105
+
106
+ emit_livekit_tool_span(
107
+ tool_name=str(tool_name),
108
+ arguments=arguments,
109
+ output=output,
110
+ call_id=str(call_id) if call_id else None,
111
+ start_time_ns=start_time_ns,
112
+ error=raw_exception if isinstance(raw_exception, BaseException) else None,
113
+ )
114
+ return result
115
+
116
+ _ORIGINAL_UTILS_EXECUTE_FUNCTION_CALL = original
117
+ _ORIGINAL_EXPORTED_EXECUTE_FUNCTION_CALL = exported_original
118
+ _PATCHED_UTILS_MODULE = utils_module
119
+ _PATCHED_LLM_MODULE = llm_module
120
+ setattr(utils_module, "execute_function_call", wrapped_execute_function_call)
121
+ if exported_original is not None:
122
+ setattr(llm_module, "execute_function_call", wrapped_execute_function_call)
123
+
124
+
125
+ def _restore_execute_function_call() -> None:
126
+ global _ORIGINAL_UTILS_EXECUTE_FUNCTION_CALL
127
+ global _ORIGINAL_EXPORTED_EXECUTE_FUNCTION_CALL
128
+ global _PATCHED_UTILS_MODULE
129
+ global _PATCHED_LLM_MODULE
130
+
131
+ if _PATCHED_UTILS_MODULE is not None and _ORIGINAL_UTILS_EXECUTE_FUNCTION_CALL:
132
+ setattr(
133
+ _PATCHED_UTILS_MODULE,
134
+ "execute_function_call",
135
+ _ORIGINAL_UTILS_EXECUTE_FUNCTION_CALL,
136
+ )
137
+ if _PATCHED_LLM_MODULE is not None and _ORIGINAL_EXPORTED_EXECUTE_FUNCTION_CALL:
138
+ setattr(
139
+ _PATCHED_LLM_MODULE,
140
+ "execute_function_call",
141
+ _ORIGINAL_EXPORTED_EXECUTE_FUNCTION_CALL,
142
+ )
143
+
144
+ _ORIGINAL_UTILS_EXECUTE_FUNCTION_CALL = None
145
+ _ORIGINAL_EXPORTED_EXECUTE_FUNCTION_CALL = None
146
+ _PATCHED_UTILS_MODULE = None
147
+ _PATCHED_LLM_MODULE = None
148
+
149
+
150
+ def _patch_llm_stream_main_task(llm_stream_class: Any) -> None:
151
+ global _ORIGINAL_LLM_STREAM_MAIN_TASK
152
+ global _PATCHED_LLM_STREAM_CLASS
153
+
154
+ if _ORIGINAL_LLM_STREAM_MAIN_TASK is not None:
155
+ return
156
+
157
+ original = getattr(llm_stream_class, "_main_task")
158
+
159
+ @functools.wraps(original)
160
+ async def wrapped_main_task(self: Any, *args: Any, **kwargs: Any) -> Any:
161
+ current_span = trace.get_current_span()
162
+ tool_definitions = normalize_livekit_tools(getattr(self, "_tools", None))
163
+ if tool_definitions:
164
+ try:
165
+ current_span.set_attribute(
166
+ LIVEKIT_RESPAN_TOOL_DEFINITIONS_ATTR,
167
+ safe_json(tool_definitions),
168
+ )
169
+ except Exception:
170
+ logger.debug("Failed to attach LiveKit tool definitions", exc_info=True)
171
+ return await original(self, *args, **kwargs)
172
+
173
+ _ORIGINAL_LLM_STREAM_MAIN_TASK = original
174
+ _PATCHED_LLM_STREAM_CLASS = llm_stream_class
175
+ setattr(llm_stream_class, "_main_task", wrapped_main_task)
176
+
177
+
178
+ def _restore_llm_stream_main_task() -> None:
179
+ global _ORIGINAL_LLM_STREAM_MAIN_TASK
180
+ global _PATCHED_LLM_STREAM_CLASS
181
+
182
+ if _PATCHED_LLM_STREAM_CLASS is not None and _ORIGINAL_LLM_STREAM_MAIN_TASK:
183
+ setattr(_PATCHED_LLM_STREAM_CLASS, "_main_task", _ORIGINAL_LLM_STREAM_MAIN_TASK)
184
+ _ORIGINAL_LLM_STREAM_MAIN_TASK = None
185
+ _PATCHED_LLM_STREAM_CLASS = None
186
+
187
+
188
+ class LiveKitInstrumentor:
189
+ """Respan instrumentor for LiveKit Agents."""
190
+
191
+ name = LIVEKIT_INSTRUMENTATION_NAME
192
+
193
+ def __init__(self) -> None:
194
+ self._processor = LiveKitSpanProcessor()
195
+ self._is_instrumented = False
196
+
197
+ @staticmethod
198
+ def _is_respan_tracing_enabled() -> bool:
199
+ tracer = getattr(RespanTracer, "_instance", None)
200
+ if tracer is None:
201
+ return True
202
+ return bool(getattr(tracer, "is_enabled", True))
203
+
204
+ def activate(self) -> None:
205
+ """Register LiveKit span translation and tool execution hooks."""
206
+ global _ACTIVE_INSTANCES
207
+
208
+ if self._is_instrumented:
209
+ return
210
+
211
+ if not self._is_respan_tracing_enabled():
212
+ logger.info("LiveKit instrumentation skipped because Respan tracing is disabled")
213
+ return
214
+
215
+ try:
216
+ livekit_telemetry = importlib.import_module("livekit.agents.telemetry")
217
+ livekit_llm = importlib.import_module("livekit.agents.llm")
218
+ livekit_llm_utils = importlib.import_module("livekit.agents.llm.utils")
219
+ except ImportError as exc:
220
+ logger.warning(
221
+ "Failed to activate LiveKit instrumentation - missing dependency: %s",
222
+ exc,
223
+ )
224
+ return
225
+
226
+ set_tracer_provider = getattr(livekit_telemetry, "set_tracer_provider", None)
227
+ if callable(set_tracer_provider):
228
+ set_tracer_provider(trace.get_tracer_provider())
229
+
230
+ _register_processor(self._processor)
231
+ _patch_execute_function_call(livekit_llm_utils, livekit_llm)
232
+ _patch_llm_stream_main_task(getattr(livekit_llm, "LLMStream"))
233
+
234
+ _ACTIVE_INSTANCES += 1
235
+ self._is_instrumented = True
236
+ logger.info("LiveKit instrumentation activated")
237
+
238
+ def deactivate(self) -> None:
239
+ """Restore LiveKit hooks and remove the span processor."""
240
+ global _ACTIVE_INSTANCES
241
+
242
+ if not self._is_instrumented:
243
+ return
244
+
245
+ _unregister_processor(self._processor)
246
+ _ACTIVE_INSTANCES = max(0, _ACTIVE_INSTANCES - 1)
247
+ if _ACTIVE_INSTANCES == 0:
248
+ _restore_execute_function_call()
249
+ _restore_llm_stream_main_task()
250
+
251
+ self._is_instrumented = False
252
+ logger.info("LiveKit instrumentation deactivated")
@@ -0,0 +1,139 @@
1
+ """Emit LiveKit tool executions as Respan OTEL spans."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import logging
6
+ import time
7
+ from typing import Any
8
+
9
+ from opentelemetry import trace
10
+ from opentelemetry.semconv_ai import SpanAttributes
11
+
12
+ from respan_instrumentation_livekit._translator import build_tool_span_attrs
13
+ from respan_sdk.constants.span_attributes import (
14
+ RESPAN_SPAN_CUSTOM_ID,
15
+ RESPAN_TRACE_GROUP_ID,
16
+ )
17
+ from respan_sdk.utils.data_processing.id_processing import (
18
+ format_span_id,
19
+ format_trace_id,
20
+ )
21
+ from respan_tracing.utils.span_factory import (
22
+ build_readable_span,
23
+ inject_span,
24
+ read_propagated_attributes,
25
+ )
26
+
27
+ logger = logging.getLogger(__name__)
28
+
29
+ _TOOL_PARENT_CONTEXTS: dict[tuple[str | None, str], tuple[str, str]] = {}
30
+ _MAX_TOOL_PARENT_CONTEXTS = 2048
31
+
32
+
33
+ def _tool_parent_key(
34
+ call_id: str,
35
+ custom_identifier: str | None,
36
+ ) -> tuple[str | None, str]:
37
+ return custom_identifier, call_id
38
+
39
+
40
+ def register_livekit_tool_parent_context(
41
+ *,
42
+ call_id: str,
43
+ trace_id: str,
44
+ parent_id: str,
45
+ custom_identifier: str | None = None,
46
+ ) -> None:
47
+ """Remember the LiveKit LLM span that announced a future tool call."""
48
+ if len(_TOOL_PARENT_CONTEXTS) >= _MAX_TOOL_PARENT_CONTEXTS:
49
+ _TOOL_PARENT_CONTEXTS.clear()
50
+ _TOOL_PARENT_CONTEXTS[_tool_parent_key(call_id, custom_identifier)] = (
51
+ trace_id,
52
+ parent_id,
53
+ )
54
+
55
+
56
+ def _pop_livekit_tool_parent_context(
57
+ call_id: str | None,
58
+ custom_identifier: str | None,
59
+ ) -> tuple[str | None, str | None]:
60
+ if not call_id:
61
+ return None, None
62
+ key = _tool_parent_key(call_id, custom_identifier)
63
+ parent = _TOOL_PARENT_CONTEXTS.pop(key, None)
64
+ if parent is not None:
65
+ return parent
66
+
67
+ fallback_key = _tool_parent_key(call_id, None)
68
+ if fallback_key == key:
69
+ return None, None
70
+ return _TOOL_PARENT_CONTEXTS.pop(fallback_key, (None, None))
71
+
72
+
73
+ def _tool_span_name(tool_name: str, workflow_name: object | None) -> str:
74
+ if workflow_name:
75
+ return f"{workflow_name}.{tool_name}"
76
+ return tool_name
77
+
78
+
79
+ def _current_trace_parent_ids() -> tuple[str | None, str | None]:
80
+ try:
81
+ current_span = trace.get_current_span()
82
+ span_context = current_span.get_span_context()
83
+ except Exception:
84
+ return None, None
85
+
86
+ trace_id = getattr(span_context, "trace_id", 0) or 0
87
+ span_id = getattr(span_context, "span_id", 0) or 0
88
+ if trace_id == 0 or span_id == 0:
89
+ return None, None
90
+ return format_trace_id(trace_id=trace_id), format_span_id(span_id=span_id)
91
+
92
+
93
+ def emit_livekit_tool_span(
94
+ *,
95
+ tool_name: str,
96
+ arguments: Any,
97
+ output: Any,
98
+ call_id: str | None,
99
+ start_time_ns: int,
100
+ error: BaseException | None = None,
101
+ ) -> None:
102
+ """Build and inject a canonical Respan tool span for a LiveKit tool call."""
103
+ try:
104
+ attrs = build_tool_span_attrs(
105
+ tool_name=tool_name,
106
+ arguments=arguments,
107
+ output={"error": str(error)} if error is not None else output,
108
+ call_id=call_id,
109
+ )
110
+ if error is not None:
111
+ attrs.setdefault("error.message", str(error))
112
+ attrs.setdefault("status_code", 500)
113
+
114
+ propagated_attrs = read_propagated_attributes()
115
+ workflow_name = propagated_attrs.get(RESPAN_TRACE_GROUP_ID)
116
+ if workflow_name:
117
+ attrs.setdefault(SpanAttributes.TRACELOOP_WORKFLOW_NAME, str(workflow_name))
118
+ span_name = _tool_span_name(tool_name=tool_name, workflow_name=workflow_name)
119
+
120
+ trace_id, parent_id = _pop_livekit_tool_parent_context(
121
+ call_id=str(call_id) if call_id else None,
122
+ custom_identifier=propagated_attrs.get(RESPAN_SPAN_CUSTOM_ID),
123
+ )
124
+ if not trace_id or not parent_id:
125
+ trace_id, parent_id = _current_trace_parent_ids()
126
+
127
+ span = build_readable_span(
128
+ name=span_name,
129
+ trace_id=trace_id,
130
+ parent_id=parent_id,
131
+ start_time_ns=start_time_ns,
132
+ end_time_ns=time.time_ns(),
133
+ attributes=attrs,
134
+ status_code=500 if error is not None else 200,
135
+ error_message=str(error) if error is not None else None,
136
+ )
137
+ inject_span(span=span)
138
+ except Exception:
139
+ logger.debug("Failed to emit LiveKit tool span", exc_info=True)
@@ -0,0 +1,138 @@
1
+ """Span processor that normalizes LiveKit native LLM spans."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import json
6
+ from typing import Any
7
+
8
+ from opentelemetry.sdk.trace import ReadableSpan, SpanProcessor
9
+ from opentelemetry.semconv_ai import SpanAttributes
10
+
11
+ from respan_instrumentation_livekit._constants import (
12
+ ATTR_LLM_METRICS,
13
+ LIVEKIT_RESPAN_TOOL_DEFINITIONS_ATTR,
14
+ LIVEKIT_SCOPE_NAME,
15
+ )
16
+ from respan_instrumentation_livekit._otel_emitter import (
17
+ register_livekit_tool_parent_context,
18
+ )
19
+ from respan_instrumentation_livekit._translator import (
20
+ build_livekit_llm_attrs,
21
+ is_livekit_llm_span,
22
+ )
23
+ from respan_sdk.constants.span_attributes import (
24
+ RESPAN_SPAN_CUSTOM_ID,
25
+ RESPAN_TRACE_GROUP_ID,
26
+ )
27
+ from respan_sdk.utils.data_processing.id_processing import (
28
+ format_span_id,
29
+ format_trace_id,
30
+ )
31
+
32
+
33
+ def _mutable_attrs(span: ReadableSpan) -> dict[str, Any] | None:
34
+ attrs = getattr(span, "_attributes", None)
35
+ if attrs is None:
36
+ return None
37
+ return dict(attrs)
38
+
39
+
40
+ def _span_context_ids(span: ReadableSpan) -> tuple[str | None, str | None]:
41
+ context = getattr(span, "context", None)
42
+ if context is None and hasattr(span, "get_span_context"):
43
+ context = span.get_span_context()
44
+ trace_id = getattr(context, "trace_id", 0) or 0
45
+ span_id = getattr(context, "span_id", 0) or 0
46
+ if trace_id == 0 or span_id == 0:
47
+ return None, None
48
+ return format_trace_id(trace_id=trace_id), format_span_id(span_id=span_id)
49
+
50
+
51
+ def _tool_call_ids(attrs: dict[str, Any]) -> list[str]:
52
+ value = attrs.get(f"{SpanAttributes.LLM_COMPLETIONS}.0.tool_calls")
53
+ if not value:
54
+ return []
55
+ try:
56
+ parsed = json.loads(value) if isinstance(value, str) else value
57
+ except Exception:
58
+ return []
59
+ if not isinstance(parsed, list):
60
+ return []
61
+
62
+ call_ids: list[str] = []
63
+ for tool_call in parsed:
64
+ if not isinstance(tool_call, dict):
65
+ continue
66
+ call_id = tool_call.get("id") or tool_call.get("call_id")
67
+ if call_id:
68
+ call_ids.append(str(call_id))
69
+ return call_ids
70
+
71
+
72
+ def _register_tool_parent_contexts(span: ReadableSpan, attrs: dict[str, Any]) -> None:
73
+ trace_id, parent_id = _span_context_ids(span)
74
+ if not trace_id or not parent_id:
75
+ return
76
+ custom_identifier = attrs.get(RESPAN_SPAN_CUSTOM_ID)
77
+ for call_id in _tool_call_ids(attrs):
78
+ register_livekit_tool_parent_context(
79
+ call_id=call_id,
80
+ trace_id=trace_id,
81
+ parent_id=parent_id,
82
+ custom_identifier=str(custom_identifier) if custom_identifier else None,
83
+ )
84
+
85
+
86
+ def _workflow_span_name(attrs: dict[str, Any]) -> str | None:
87
+ workflow_name = attrs.get(RESPAN_TRACE_GROUP_ID) or attrs.get(
88
+ SpanAttributes.TRACELOOP_WORKFLOW_NAME
89
+ )
90
+ return str(workflow_name) if workflow_name else None
91
+
92
+
93
+ def _rename_span_to_workflow(span: ReadableSpan, attrs: dict[str, Any]) -> None:
94
+ workflow_span_name = _workflow_span_name(attrs)
95
+ if workflow_span_name:
96
+ span._name = workflow_span_name
97
+
98
+
99
+ def _scope_name(span: ReadableSpan) -> str | None:
100
+ scope = getattr(span, "instrumentation_scope", None)
101
+ return getattr(scope, "name", None)
102
+
103
+
104
+ class LiveKitSpanProcessor(SpanProcessor):
105
+ """Translate LiveKit ``llm_request`` spans before Respan export."""
106
+
107
+ def on_start(self, span: Any, parent_context: Any = None) -> None:
108
+ return None
109
+
110
+ def on_end(self, span: ReadableSpan) -> None:
111
+ attrs = _mutable_attrs(span)
112
+ if attrs is None:
113
+ return
114
+ scope_name = _scope_name(span)
115
+ if (
116
+ scope_name not in (None, LIVEKIT_SCOPE_NAME)
117
+ and ATTR_LLM_METRICS not in attrs
118
+ and LIVEKIT_RESPAN_TOOL_DEFINITIONS_ATTR not in attrs
119
+ ):
120
+ return
121
+ if not is_livekit_llm_span(span_name=span.name, attrs=attrs):
122
+ return
123
+
124
+ translated = build_livekit_llm_attrs(
125
+ span_name=span.name,
126
+ attrs=attrs,
127
+ events=tuple(getattr(span, "events", ()) or ()),
128
+ )
129
+ attrs.update(translated)
130
+ _rename_span_to_workflow(span=span, attrs=attrs)
131
+ _register_tool_parent_contexts(span=span, attrs=attrs)
132
+ span._attributes = attrs
133
+
134
+ def shutdown(self) -> None:
135
+ return None
136
+
137
+ def force_flush(self, timeout_millis: int = 30000) -> bool:
138
+ return True
@@ -0,0 +1,63 @@
1
+ """Serialization helpers for LiveKit instrumentation."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import json
6
+ from collections.abc import Mapping
7
+ from typing import Any
8
+
9
+ from respan_sdk.utils.serialization import serialize_value
10
+
11
+
12
+ def safe_json(value: Any) -> str:
13
+ """Serialize arbitrary LiveKit values into an OTEL-safe JSON string."""
14
+ try:
15
+ return json.dumps(
16
+ serialize_value(value=value),
17
+ default=str,
18
+ separators=(",", ":"),
19
+ )
20
+ except Exception:
21
+ return json.dumps(str(value), separators=(",", ":"))
22
+
23
+
24
+ def to_mapping(value: Any) -> Mapping[str, Any] | None:
25
+ if isinstance(value, Mapping):
26
+ return value
27
+
28
+ for method_name in ("model_dump", "to_dict", "dict"):
29
+ method = getattr(value, method_name, None)
30
+ if callable(method):
31
+ try:
32
+ converted = method()
33
+ except Exception:
34
+ continue
35
+ if isinstance(converted, Mapping):
36
+ return converted
37
+
38
+ value_dict = getattr(value, "__dict__", None)
39
+ if isinstance(value_dict, Mapping):
40
+ return value_dict
41
+ return None
42
+
43
+
44
+ def get_value(value: Any, key: str, default: Any = None) -> Any:
45
+ mapping = to_mapping(value)
46
+ if mapping is not None:
47
+ return mapping.get(key, default)
48
+ return getattr(value, key, default)
49
+
50
+
51
+ def json_string_or_value(value: Any) -> Any:
52
+ if value is None or isinstance(value, (str, int, float, bool)):
53
+ return value
54
+ return safe_json(value)
55
+
56
+
57
+ def parse_jsonish(value: Any) -> Any:
58
+ if not isinstance(value, str):
59
+ return value
60
+ try:
61
+ return json.loads(value)
62
+ except Exception:
63
+ return value
@@ -0,0 +1,374 @@
1
+ """Translate LiveKit native OTEL span data into Respan span fields."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import json
6
+ from collections.abc import Mapping, Sequence
7
+ from typing import Any
8
+
9
+ from opentelemetry.semconv._incubating.attributes import (
10
+ gen_ai_attributes as GenAIAttributes,
11
+ )
12
+ from opentelemetry.semconv_ai import LLMRequestTypeValues, SpanAttributes
13
+
14
+ from respan_instrumentation_livekit._constants import (
15
+ ASSISTANT_ROLE,
16
+ ATTR_LLM_METRICS,
17
+ ATTR_PROVIDER_REQUEST_IDS,
18
+ EVENT_GEN_AI_ASSISTANT_MESSAGE,
19
+ EVENT_GEN_AI_CHOICE,
20
+ EVENT_GEN_AI_SYSTEM_MESSAGE,
21
+ EVENT_GEN_AI_TOOL_MESSAGE,
22
+ EVENT_GEN_AI_USER_MESSAGE,
23
+ FUNCTION_KEY,
24
+ FUNCTION_TOOL_TYPE,
25
+ ID_KEY,
26
+ LIVEKIT_CHAT_SPAN_NAME,
27
+ LIVEKIT_LLM_REQUEST_SPAN_NAME,
28
+ LIVEKIT_RESPAN_TOOL_DEFINITIONS_ATTR,
29
+ NAME_KEY,
30
+ ROLE_KEY,
31
+ TOOL_ROLE,
32
+ TYPE_KEY,
33
+ USER_ROLE,
34
+ )
35
+ from respan_instrumentation_livekit._serialization import (
36
+ get_value,
37
+ parse_jsonish,
38
+ safe_json,
39
+ )
40
+ from respan_sdk.constants.llm_logging import LOG_TYPE_CHAT, LOG_TYPE_TOOL, LogMethodChoices
41
+ from respan_sdk.constants.span_attributes import (
42
+ RESPAN_LOG_METHOD,
43
+ RESPAN_LOG_TYPE,
44
+ RESPAN_METADATA,
45
+ RESPAN_TRACE_GROUP_ID,
46
+ )
47
+
48
+ _PROMPT_EVENT_ROLES = {
49
+ EVENT_GEN_AI_SYSTEM_MESSAGE: "system",
50
+ EVENT_GEN_AI_USER_MESSAGE: USER_ROLE,
51
+ EVENT_GEN_AI_ASSISTANT_MESSAGE: ASSISTANT_ROLE,
52
+ EVENT_GEN_AI_TOOL_MESSAGE: TOOL_ROLE,
53
+ }
54
+
55
+
56
+ def _event_name(event: Any) -> str | None:
57
+ return getattr(event, "name", None)
58
+
59
+
60
+ def _event_attrs(event: Any) -> Mapping[str, Any]:
61
+ attrs = getattr(event, "attributes", None)
62
+ return attrs if isinstance(attrs, Mapping) else {}
63
+
64
+
65
+ def _content_to_str(value: Any) -> str:
66
+ if value is None:
67
+ return ""
68
+ if isinstance(value, str):
69
+ return value
70
+ return safe_json(value)
71
+
72
+
73
+ def _tool_calls_from_event(value: Any) -> list[dict[str, Any]]:
74
+ if value is None:
75
+ return []
76
+ if isinstance(value, (str, bytes, bytearray)):
77
+ value = [value.decode() if isinstance(value, bytes) else value]
78
+ elif isinstance(value, Mapping):
79
+ value = [value]
80
+ elif not isinstance(value, Sequence):
81
+ value = [value]
82
+
83
+ tool_calls: list[dict[str, Any]] = []
84
+ for item in value:
85
+ parsed = parse_jsonish(item)
86
+ if not isinstance(parsed, Mapping):
87
+ continue
88
+ function = parsed.get(FUNCTION_KEY)
89
+ if not isinstance(function, Mapping):
90
+ continue
91
+ function_name = function.get(NAME_KEY)
92
+ if not function_name:
93
+ continue
94
+ normalized = {
95
+ TYPE_KEY: str(parsed.get(TYPE_KEY) or FUNCTION_TOOL_TYPE),
96
+ FUNCTION_KEY: {
97
+ NAME_KEY: str(function_name),
98
+ "arguments": (
99
+ function.get("arguments")
100
+ if isinstance(function.get("arguments"), str)
101
+ else safe_json(function.get("arguments") or {})
102
+ ),
103
+ },
104
+ }
105
+ call_id = parsed.get(ID_KEY)
106
+ if call_id:
107
+ normalized[ID_KEY] = str(call_id)
108
+ tool_calls.append(normalized)
109
+ return tool_calls
110
+
111
+
112
+ def _metrics(attrs: Mapping[str, Any]) -> Mapping[str, Any]:
113
+ value = attrs.get(ATTR_LLM_METRICS)
114
+ if not isinstance(value, str):
115
+ return {}
116
+ try:
117
+ loaded = json.loads(value)
118
+ except Exception:
119
+ return {}
120
+ return loaded if isinstance(loaded, Mapping) else {}
121
+
122
+
123
+ def _int_value(value: Any) -> int | None:
124
+ if isinstance(value, bool):
125
+ return None
126
+ if isinstance(value, int):
127
+ return value
128
+ if isinstance(value, float) and value.is_integer():
129
+ return int(value)
130
+ return None
131
+
132
+
133
+ def _provider_name(attrs: Mapping[str, Any]) -> str:
134
+ provider = attrs.get(GenAIAttributes.GEN_AI_PROVIDER_NAME) or attrs.get(
135
+ SpanAttributes.LLM_SYSTEM
136
+ )
137
+ if not provider:
138
+ return "livekit"
139
+ provider_name = str(provider).lower()
140
+ if provider_name == "unknown":
141
+ return "livekit"
142
+ return provider_name
143
+
144
+
145
+ def _apply_prompt_events(
146
+ translated: dict[str, Any],
147
+ events: Sequence[Any],
148
+ ) -> list[dict[str, Any]]:
149
+ messages: list[dict[str, Any]] = []
150
+
151
+ for event in events:
152
+ event_name = _event_name(event)
153
+ role = _PROMPT_EVENT_ROLES.get(event_name)
154
+ if role is None:
155
+ continue
156
+ attrs = _event_attrs(event)
157
+ message: dict[str, Any] = {ROLE_KEY: str(attrs.get(ROLE_KEY) or role)}
158
+ if event_name == EVENT_GEN_AI_TOOL_MESSAGE:
159
+ message[ROLE_KEY] = TOOL_ROLE
160
+
161
+ content = attrs.get("content")
162
+ if content is not None:
163
+ message["content"] = _content_to_str(content)
164
+
165
+ tool_calls = _tool_calls_from_event(attrs.get("tool_calls"))
166
+ if tool_calls:
167
+ message["tool_calls"] = tool_calls
168
+
169
+ if role == TOOL_ROLE and attrs.get(NAME_KEY):
170
+ message[NAME_KEY] = str(attrs[NAME_KEY])
171
+ messages.append(message)
172
+
173
+ for index, message in enumerate(messages):
174
+ prefix = f"{SpanAttributes.LLM_PROMPTS}.{index}"
175
+ translated[f"{prefix}.role"] = str(message.get(ROLE_KEY) or USER_ROLE)
176
+ if "content" in message:
177
+ translated[f"{prefix}.content"] = _content_to_str(message["content"])
178
+ if message.get("tool_calls"):
179
+ translated[f"{prefix}.tool_calls"] = safe_json(message["tool_calls"])
180
+
181
+ return messages
182
+
183
+
184
+ def _apply_completion_event(
185
+ translated: dict[str, Any],
186
+ events: Sequence[Any],
187
+ ) -> dict[str, Any]:
188
+ completion: dict[str, Any] = {}
189
+ for event in events:
190
+ if _event_name(event) != EVENT_GEN_AI_CHOICE:
191
+ continue
192
+ attrs = _event_attrs(event)
193
+ content = attrs.get("content")
194
+ if content is not None:
195
+ completion["content"] = _content_to_str(content)
196
+ tool_calls = _tool_calls_from_event(attrs.get("tool_calls"))
197
+ if tool_calls:
198
+ completion["tool_calls"] = tool_calls
199
+
200
+ if completion:
201
+ prefix = f"{SpanAttributes.LLM_COMPLETIONS}.0"
202
+ translated[f"{prefix}.role"] = ASSISTANT_ROLE
203
+ if "content" in completion:
204
+ translated[f"{prefix}.content"] = completion["content"]
205
+ if completion.get("tool_calls"):
206
+ translated[f"{prefix}.tool_calls"] = safe_json(completion["tool_calls"])
207
+ return completion
208
+
209
+
210
+ def _apply_usage(translated: dict[str, Any], attrs: Mapping[str, Any]) -> None:
211
+ metrics = _metrics(attrs)
212
+ input_tokens = _int_value(
213
+ attrs.get(GenAIAttributes.GEN_AI_USAGE_INPUT_TOKENS, metrics.get("prompt_tokens"))
214
+ )
215
+ output_tokens = _int_value(
216
+ attrs.get(
217
+ GenAIAttributes.GEN_AI_USAGE_OUTPUT_TOKENS,
218
+ metrics.get("completion_tokens"),
219
+ )
220
+ )
221
+ total_tokens = _int_value(metrics.get("total_tokens"))
222
+ if total_tokens is None and (input_tokens is not None or output_tokens is not None):
223
+ total_tokens = (input_tokens or 0) + (output_tokens or 0)
224
+
225
+ if input_tokens is not None:
226
+ translated[GenAIAttributes.GEN_AI_USAGE_INPUT_TOKENS] = input_tokens
227
+ translated[SpanAttributes.LLM_USAGE_PROMPT_TOKENS] = input_tokens
228
+ if output_tokens is not None:
229
+ translated[GenAIAttributes.GEN_AI_USAGE_OUTPUT_TOKENS] = output_tokens
230
+ translated[SpanAttributes.LLM_USAGE_COMPLETION_TOKENS] = output_tokens
231
+ if total_tokens is not None:
232
+ translated[SpanAttributes.LLM_USAGE_TOTAL_TOKENS] = total_tokens
233
+
234
+ cached_tokens = _int_value(
235
+ metrics.get("prompt_cached_tokens")
236
+ or metrics.get("cache_read_tokens")
237
+ or metrics.get("cache_read_input_tokens")
238
+ )
239
+ cache_read_attr = getattr(SpanAttributes, "LLM_USAGE_CACHE_READ_INPUT_TOKENS", None)
240
+ if cached_tokens is not None and cache_read_attr:
241
+ translated[cache_read_attr] = cached_tokens
242
+
243
+
244
+ def _apply_livekit_metadata(translated: dict[str, Any], attrs: Mapping[str, Any]) -> None:
245
+ metrics = attrs.get(ATTR_LLM_METRICS)
246
+ if isinstance(metrics, str) and metrics:
247
+ translated[f"{RESPAN_METADATA}.livekit_llm_metrics"] = metrics
248
+
249
+ provider_request_ids = attrs.get(ATTR_PROVIDER_REQUEST_IDS)
250
+ if provider_request_ids:
251
+ translated[f"{RESPAN_METADATA}.livekit_provider_request_ids"] = (
252
+ provider_request_ids
253
+ if isinstance(provider_request_ids, str)
254
+ else safe_json(provider_request_ids)
255
+ )
256
+
257
+
258
+ def _apply_tool_definitions(translated: dict[str, Any], attrs: Mapping[str, Any]) -> None:
259
+ value = attrs.get(LIVEKIT_RESPAN_TOOL_DEFINITIONS_ATTR)
260
+ parsed = parse_jsonish(value)
261
+ if parsed:
262
+ translated[SpanAttributes.LLM_REQUEST_FUNCTIONS] = (
263
+ parsed if isinstance(parsed, str) else safe_json(parsed)
264
+ )
265
+
266
+
267
+ def is_livekit_llm_span(span_name: str, attrs: Mapping[str, Any]) -> bool:
268
+ return attrs.get(GenAIAttributes.GEN_AI_OPERATION_NAME) == "chat" and (
269
+ span_name == LIVEKIT_LLM_REQUEST_SPAN_NAME
270
+ or attrs.get(ATTR_LLM_METRICS) is not None
271
+ or attrs.get(LIVEKIT_RESPAN_TOOL_DEFINITIONS_ATTR) is not None
272
+ )
273
+
274
+
275
+ def build_livekit_llm_attrs(
276
+ *,
277
+ span_name: str,
278
+ attrs: Mapping[str, Any],
279
+ events: Sequence[Any],
280
+ ) -> dict[str, Any]:
281
+ """Build canonical Respan chat attributes from a LiveKit LLM span."""
282
+ translated: dict[str, Any] = {
283
+ RESPAN_LOG_METHOD: LogMethodChoices.TRACING_INTEGRATION.value,
284
+ RESPAN_LOG_TYPE: LOG_TYPE_CHAT,
285
+ SpanAttributes.LLM_SYSTEM: _provider_name(attrs),
286
+ SpanAttributes.LLM_REQUEST_TYPE: LLMRequestTypeValues.CHAT.value,
287
+ SpanAttributes.TRACELOOP_ENTITY_NAME: LIVEKIT_CHAT_SPAN_NAME,
288
+ SpanAttributes.TRACELOOP_ENTITY_PATH: LIVEKIT_CHAT_SPAN_NAME,
289
+ }
290
+
291
+ model = attrs.get(GenAIAttributes.GEN_AI_REQUEST_MODEL) or attrs.get(
292
+ SpanAttributes.LLM_REQUEST_MODEL
293
+ )
294
+ if model:
295
+ translated[SpanAttributes.LLM_REQUEST_MODEL] = str(model)
296
+
297
+ workflow_name = attrs.get(RESPAN_TRACE_GROUP_ID)
298
+ if workflow_name:
299
+ translated[SpanAttributes.TRACELOOP_WORKFLOW_NAME] = str(workflow_name)
300
+
301
+ messages = _apply_prompt_events(translated=translated, events=events)
302
+ completion = _apply_completion_event(translated=translated, events=events)
303
+ _apply_usage(translated=translated, attrs=attrs)
304
+ _apply_tool_definitions(translated=translated, attrs=attrs)
305
+ _apply_livekit_metadata(translated=translated, attrs=attrs)
306
+
307
+ if messages:
308
+ translated[SpanAttributes.TRACELOOP_ENTITY_INPUT] = safe_json(messages)
309
+ if completion:
310
+ translated[SpanAttributes.TRACELOOP_ENTITY_OUTPUT] = safe_json(completion)
311
+
312
+ return translated
313
+
314
+
315
+ def normalize_livekit_tools(tools: Any) -> list[dict[str, Any]]:
316
+ """Normalize LiveKit function tools into OpenAI-compatible tool schemas."""
317
+ if not tools:
318
+ return []
319
+ if not isinstance(tools, Sequence) or isinstance(tools, (str, bytes, bytearray)):
320
+ tools = [tools]
321
+
322
+ try:
323
+ from livekit.agents.llm.tool_context import ToolContext
324
+
325
+ parsed = ToolContext(tools).parse_function_tools("openai")
326
+ if isinstance(parsed, list):
327
+ return [tool for tool in parsed if isinstance(tool, dict)]
328
+ except Exception:
329
+ pass
330
+
331
+ normalized: list[dict[str, Any]] = []
332
+ for tool in tools:
333
+ info = get_value(tool, "info")
334
+ raw_schema = get_value(info, "raw_schema")
335
+ if isinstance(raw_schema, Mapping) and raw_schema.get(NAME_KEY):
336
+ normalized.append({TYPE_KEY: FUNCTION_TOOL_TYPE, FUNCTION_KEY: dict(raw_schema)})
337
+ continue
338
+
339
+ name = get_value(info, NAME_KEY) or get_value(tool, ID_KEY)
340
+ if not name:
341
+ continue
342
+ function: dict[str, Any] = {
343
+ NAME_KEY: str(name),
344
+ "parameters": {"type": "object", "properties": {}},
345
+ }
346
+ description = get_value(info, "description")
347
+ if description:
348
+ function["description"] = str(description)
349
+ normalized.append({TYPE_KEY: FUNCTION_TOOL_TYPE, FUNCTION_KEY: function})
350
+ return normalized
351
+
352
+
353
+ def build_tool_span_attrs(
354
+ *,
355
+ tool_name: str,
356
+ arguments: Any,
357
+ output: Any,
358
+ call_id: str | None = None,
359
+ ) -> dict[str, Any]:
360
+ attrs: dict[str, Any] = {
361
+ RESPAN_LOG_TYPE: LOG_TYPE_TOOL,
362
+ SpanAttributes.TRACELOOP_ENTITY_NAME: tool_name,
363
+ SpanAttributes.TRACELOOP_ENTITY_PATH: tool_name,
364
+ SpanAttributes.TRACELOOP_ENTITY_INPUT: safe_json(
365
+ {
366
+ NAME_KEY: tool_name,
367
+ "arguments": parse_jsonish(arguments),
368
+ }
369
+ ),
370
+ SpanAttributes.TRACELOOP_ENTITY_OUTPUT: safe_json(output),
371
+ }
372
+ if call_id:
373
+ attrs[f"{RESPAN_METADATA}.livekit_tool_call_id"] = str(call_id)
374
+ return attrs