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.
- respan_instrumentation_livekit-0.1.0/PKG-INFO +66 -0
- respan_instrumentation_livekit-0.1.0/README.md +46 -0
- respan_instrumentation_livekit-0.1.0/pyproject.toml +29 -0
- respan_instrumentation_livekit-0.1.0/src/respan_instrumentation_livekit/__init__.py +5 -0
- respan_instrumentation_livekit-0.1.0/src/respan_instrumentation_livekit/_constants.py +32 -0
- respan_instrumentation_livekit-0.1.0/src/respan_instrumentation_livekit/_instrumentation.py +252 -0
- respan_instrumentation_livekit-0.1.0/src/respan_instrumentation_livekit/_otel_emitter.py +139 -0
- respan_instrumentation_livekit-0.1.0/src/respan_instrumentation_livekit/_processor.py +138 -0
- respan_instrumentation_livekit-0.1.0/src/respan_instrumentation_livekit/_serialization.py +63 -0
- respan_instrumentation_livekit-0.1.0/src/respan_instrumentation_livekit/_translator.py +374 -0
|
@@ -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,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
|