tracespan 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.
- tracespan/__init__.py +84 -0
- tracespan/context.py +109 -0
- tracespan/instrumentation/__init__.py +13 -0
- tracespan/instrumentation/callbacks.py +274 -0
- tracespan/instrumentation/langchain.py +127 -0
- tracespan/instrumentation/patch.py +190 -0
- tracespan/models.py +289 -0
- tracespan/py.typed +0 -0
- tracespan/query.py +152 -0
- tracespan/serialization.py +84 -0
- tracespan/store/__init__.py +28 -0
- tracespan/store/base.py +93 -0
- tracespan/store/file.py +147 -0
- tracespan/store/mysql.py +83 -0
- tracespan/store/postgres.py +80 -0
- tracespan/store/sql.py +326 -0
- tracespan/store/sqlite.py +79 -0
- tracespan/tracer.py +409 -0
- tracespan-0.2.0.dist-info/METADATA +288 -0
- tracespan-0.2.0.dist-info/RECORD +23 -0
- tracespan-0.2.0.dist-info/WHEEL +5 -0
- tracespan-0.2.0.dist-info/licenses/LICENSE +201 -0
- tracespan-0.2.0.dist-info/top_level.txt +1 -0
tracespan/__init__.py
ADDED
|
@@ -0,0 +1,84 @@
|
|
|
1
|
+
"""tracespan —— 无侵入的 Agent 行为追踪库。
|
|
2
|
+
|
|
3
|
+
快速开始:
|
|
4
|
+
import tracespan as at
|
|
5
|
+
|
|
6
|
+
at.configure(db_path="traces.db") # 或 at.configure(dir="./traces")
|
|
7
|
+
at.instrument_langchain() # 一次接入,现有 agent.invoke 无需改动
|
|
8
|
+
|
|
9
|
+
with at.bind_run(user_id="u1", agent_id="cs", session_id="s1"):
|
|
10
|
+
agent.invoke({"messages": [...]}) # 自动产生 trace + span 树
|
|
11
|
+
|
|
12
|
+
q = at.query(at.get_tracer().store)
|
|
13
|
+
print(q.format_errors()) # 直接看到报错链路
|
|
14
|
+
"""
|
|
15
|
+
from .models import (
|
|
16
|
+
Span,
|
|
17
|
+
SpanFilter,
|
|
18
|
+
SpanKind,
|
|
19
|
+
Status,
|
|
20
|
+
Trace,
|
|
21
|
+
TraceFilter,
|
|
22
|
+
build_tree,
|
|
23
|
+
flatten_tree,
|
|
24
|
+
new_span_id,
|
|
25
|
+
new_trace_id,
|
|
26
|
+
)
|
|
27
|
+
from .serialization import dumps, loads, to_jsonable, utc_now
|
|
28
|
+
from .context import (
|
|
29
|
+
TraceContext,
|
|
30
|
+
bind_run,
|
|
31
|
+
current_context,
|
|
32
|
+
current_span_id,
|
|
33
|
+
current_trace_id,
|
|
34
|
+
)
|
|
35
|
+
from .store import (
|
|
36
|
+
FileTraceStore,
|
|
37
|
+
MySQLTraceStore,
|
|
38
|
+
PostgresTraceStore,
|
|
39
|
+
SQLiteTraceStore,
|
|
40
|
+
TraceStore,
|
|
41
|
+
)
|
|
42
|
+
from .tracer import (
|
|
43
|
+
Tracer,
|
|
44
|
+
configure,
|
|
45
|
+
get_tracer,
|
|
46
|
+
reset_tracer,
|
|
47
|
+
set_tracer,
|
|
48
|
+
traced,
|
|
49
|
+
)
|
|
50
|
+
from .query import TraceQuery, query
|
|
51
|
+
from .instrumentation import (
|
|
52
|
+
TracingCallbackHandler,
|
|
53
|
+
instrument,
|
|
54
|
+
instrument_langchain,
|
|
55
|
+
uninstrument,
|
|
56
|
+
uninstrument_all,
|
|
57
|
+
uninstrument_langchain,
|
|
58
|
+
)
|
|
59
|
+
|
|
60
|
+
from importlib.metadata import PackageNotFoundError, version as _pkg_version
|
|
61
|
+
|
|
62
|
+
try: # 安装后以包元数据为准,避免与 pyproject.toml 版本漂移
|
|
63
|
+
__version__ = _pkg_version("tracespan")
|
|
64
|
+
except PackageNotFoundError: # 源码目录直接运行时
|
|
65
|
+
__version__ = "0.2.0"
|
|
66
|
+
|
|
67
|
+
__all__ = [
|
|
68
|
+
# 模型
|
|
69
|
+
"Trace", "Span", "Status", "SpanKind", "TraceFilter", "SpanFilter",
|
|
70
|
+
"new_trace_id", "new_span_id", "build_tree", "flatten_tree",
|
|
71
|
+
# 序列化
|
|
72
|
+
"dumps", "loads", "to_jsonable", "utc_now",
|
|
73
|
+
# 上下文
|
|
74
|
+
"TraceContext", "bind_run", "current_context", "current_trace_id", "current_span_id",
|
|
75
|
+
# 存储
|
|
76
|
+
"TraceStore", "FileTraceStore", "SQLiteTraceStore", "MySQLTraceStore", "PostgresTraceStore",
|
|
77
|
+
# Tracer
|
|
78
|
+
"Tracer", "traced", "configure", "get_tracer", "set_tracer", "reset_tracer",
|
|
79
|
+
# 查询
|
|
80
|
+
"TraceQuery", "query",
|
|
81
|
+
# 无感接入
|
|
82
|
+
"instrument", "instrument_langchain", "uninstrument", "uninstrument_all", "uninstrument_langchain",
|
|
83
|
+
"TracingCallbackHandler",
|
|
84
|
+
]
|
tracespan/context.py
ADDED
|
@@ -0,0 +1,109 @@
|
|
|
1
|
+
"""上下文传播:用 ContextVar 保存当前 trace / span / 运行身份。
|
|
2
|
+
|
|
3
|
+
作用:
|
|
4
|
+
1. Tracer 自动为嵌套调用建立父子关系,无需手动传 parent_span_id。
|
|
5
|
+
2. bind_run() 让 user_id / agent_id / session_id 一次绑定,自动写入其下所有 trace/span。
|
|
6
|
+
3. 异步任务与线程各自持有独立上下文,互不串线。
|
|
7
|
+
"""
|
|
8
|
+
from __future__ import annotations
|
|
9
|
+
|
|
10
|
+
from contextvars import ContextVar, Token
|
|
11
|
+
from dataclasses import dataclass, field
|
|
12
|
+
from typing import Any
|
|
13
|
+
|
|
14
|
+
|
|
15
|
+
@dataclass
|
|
16
|
+
class TraceContext:
|
|
17
|
+
trace_id: str | None = None
|
|
18
|
+
span_id: str | None = None
|
|
19
|
+
user_id: str | None = None
|
|
20
|
+
agent_id: str | None = None
|
|
21
|
+
session_id: str | None = None
|
|
22
|
+
baggage: dict[str, Any] = field(default_factory=dict)
|
|
23
|
+
|
|
24
|
+
def child(self, **overrides: Any) -> "TraceContext":
|
|
25
|
+
"""基于当前上下文派生子上下文(baggage 浅拷贝)。"""
|
|
26
|
+
data = {
|
|
27
|
+
"trace_id": self.trace_id,
|
|
28
|
+
"span_id": self.span_id,
|
|
29
|
+
"user_id": self.user_id,
|
|
30
|
+
"agent_id": self.agent_id,
|
|
31
|
+
"session_id": self.session_id,
|
|
32
|
+
"baggage": dict(self.baggage),
|
|
33
|
+
}
|
|
34
|
+
data.update(overrides)
|
|
35
|
+
return TraceContext(**data)
|
|
36
|
+
|
|
37
|
+
|
|
38
|
+
_ctx: ContextVar[TraceContext | None] = ContextVar("tracespan_context", default=None)
|
|
39
|
+
|
|
40
|
+
|
|
41
|
+
def current_context() -> TraceContext | None:
|
|
42
|
+
return _ctx.get()
|
|
43
|
+
|
|
44
|
+
|
|
45
|
+
def set_context(ctx: TraceContext) -> Token[TraceContext | None]:
|
|
46
|
+
return _ctx.set(ctx)
|
|
47
|
+
|
|
48
|
+
|
|
49
|
+
def reset_context(token: Token[TraceContext | None]) -> None:
|
|
50
|
+
try:
|
|
51
|
+
_ctx.reset(token)
|
|
52
|
+
except ValueError:
|
|
53
|
+
pass # 跨线程 / 跨 loop 时 token 可能属于别的 context
|
|
54
|
+
|
|
55
|
+
|
|
56
|
+
def current_trace_id() -> str | None:
|
|
57
|
+
ctx = _ctx.get()
|
|
58
|
+
return ctx.trace_id if ctx else None
|
|
59
|
+
|
|
60
|
+
|
|
61
|
+
def current_span_id() -> str | None:
|
|
62
|
+
ctx = _ctx.get()
|
|
63
|
+
return ctx.span_id if ctx else None
|
|
64
|
+
|
|
65
|
+
|
|
66
|
+
def current_identity() -> tuple[str | None, str | None, str | None]:
|
|
67
|
+
ctx = _ctx.get()
|
|
68
|
+
if ctx is None:
|
|
69
|
+
return None, None, None
|
|
70
|
+
return ctx.user_id, ctx.agent_id, ctx.session_id
|
|
71
|
+
|
|
72
|
+
|
|
73
|
+
class bind_run:
|
|
74
|
+
"""绑定一次运行的用户 / agent / session 身份与自定义 baggage。
|
|
75
|
+
|
|
76
|
+
用法:
|
|
77
|
+
with bind_run(user_id="u-1", agent_id="cs", session_id="s-1", env="prod"):
|
|
78
|
+
agent.invoke(...) # 其下所有 trace/span 自动带上这些字段
|
|
79
|
+
"""
|
|
80
|
+
|
|
81
|
+
def __init__(
|
|
82
|
+
self,
|
|
83
|
+
*,
|
|
84
|
+
user_id: str | None = None,
|
|
85
|
+
agent_id: str | None = None,
|
|
86
|
+
session_id: str | None = None,
|
|
87
|
+
**baggage: Any,
|
|
88
|
+
) -> None:
|
|
89
|
+
self.overrides: dict[str, Any] = {
|
|
90
|
+
"user_id": user_id,
|
|
91
|
+
"agent_id": agent_id,
|
|
92
|
+
"session_id": session_id,
|
|
93
|
+
}
|
|
94
|
+
self.baggage = baggage
|
|
95
|
+
self._token: Token[TraceContext | None] | None = None
|
|
96
|
+
|
|
97
|
+
def __enter__(self) -> "bind_run":
|
|
98
|
+
base = _ctx.get() or TraceContext()
|
|
99
|
+
merged = dict(base.baggage)
|
|
100
|
+
merged.update(self.baggage)
|
|
101
|
+
overrides = {k: v for k, v in self.overrides.items() if v is not None}
|
|
102
|
+
overrides["baggage"] = merged
|
|
103
|
+
self._token = _ctx.set(base.child(**overrides))
|
|
104
|
+
return self
|
|
105
|
+
|
|
106
|
+
def __exit__(self, *exc: Any) -> bool:
|
|
107
|
+
if self._token is not None:
|
|
108
|
+
reset_context(self._token)
|
|
109
|
+
return False
|
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
"""无感接入工具:通用方法补丁 + 主流框架适配。"""
|
|
2
|
+
from .patch import instrument, uninstrument, uninstrument_all
|
|
3
|
+
from .langchain import instrument_langchain, uninstrument_langchain
|
|
4
|
+
from .callbacks import TracingCallbackHandler
|
|
5
|
+
|
|
6
|
+
__all__ = [
|
|
7
|
+
"instrument",
|
|
8
|
+
"uninstrument",
|
|
9
|
+
"uninstrument_all",
|
|
10
|
+
"instrument_langchain",
|
|
11
|
+
"uninstrument_langchain",
|
|
12
|
+
"TracingCallbackHandler",
|
|
13
|
+
]
|
|
@@ -0,0 +1,274 @@
|
|
|
1
|
+
"""LangChain / LangGraph 回调 -> tracespan span。
|
|
2
|
+
|
|
3
|
+
把 TracingCallbackHandler 注入 config["callbacks"] 后,deepagents / LangGraph
|
|
4
|
+
内部的 chain、llm、tool 调用会自动写成 span,并通过 parent_run_id 还原父子关系。
|
|
5
|
+
配合 instrument_langchain() 的 invoke 补丁,一次 agent.invoke 得到完整调用树。
|
|
6
|
+
"""
|
|
7
|
+
from __future__ import annotations
|
|
8
|
+
|
|
9
|
+
import logging
|
|
10
|
+
import threading
|
|
11
|
+
import time
|
|
12
|
+
from datetime import datetime
|
|
13
|
+
from typing import Any
|
|
14
|
+
from uuid import UUID
|
|
15
|
+
|
|
16
|
+
from langchain_core.callbacks import BaseCallbackHandler
|
|
17
|
+
|
|
18
|
+
from ..context import current_context
|
|
19
|
+
from ..models import SpanKind, Status
|
|
20
|
+
from ..serialization import to_jsonable
|
|
21
|
+
from ..tracer import Tracer, get_tracer
|
|
22
|
+
|
|
23
|
+
|
|
24
|
+
class TracingCallbackHandler(BaseCallbackHandler):
|
|
25
|
+
"""把 LangChain 回调事件写入 tracespan 的 span 表。
|
|
26
|
+
|
|
27
|
+
:param tracer: 指定 Tracer;不传则用全局 Tracer
|
|
28
|
+
"""
|
|
29
|
+
|
|
30
|
+
def __init__(self, tracer: Tracer | None = None) -> None:
|
|
31
|
+
self._tracer = tracer
|
|
32
|
+
self._span_by_run: dict[UUID, str | None] = {}
|
|
33
|
+
self._starts: dict[str, float] = {} # span_id -> perf_counter
|
|
34
|
+
self._skipped: set[UUID] = set()
|
|
35
|
+
self._lock = threading.RLock()
|
|
36
|
+
self._logger = logging.getLogger("tracespan.callbacks")
|
|
37
|
+
|
|
38
|
+
@property
|
|
39
|
+
def tracer(self) -> Tracer:
|
|
40
|
+
return self._tracer or get_tracer()
|
|
41
|
+
|
|
42
|
+
# ------------------------------------------------------------ 内部
|
|
43
|
+
@staticmethod
|
|
44
|
+
def _name(serialized: dict[str, Any] | None, fallback: str) -> str:
|
|
45
|
+
if not serialized:
|
|
46
|
+
return fallback
|
|
47
|
+
return str(serialized.get("name") or serialized.get("id") or fallback)
|
|
48
|
+
|
|
49
|
+
@staticmethod
|
|
50
|
+
def _chain_name(serialized: dict[str, Any] | None, metadata: dict[str, Any] | None) -> str:
|
|
51
|
+
node = (metadata or {}).get("langgraph_node")
|
|
52
|
+
return str(node) if node else TracingCallbackHandler._name(serialized, "chain")
|
|
53
|
+
|
|
54
|
+
@staticmethod
|
|
55
|
+
def _is_wrapper_chain(kind: str, tags: list[str] | None) -> bool:
|
|
56
|
+
"""折叠 LangGraph 1.x 只有 seq:step:* 没有 graph:step:* 的包装层。"""
|
|
57
|
+
if kind != "chain" or not tags:
|
|
58
|
+
return False
|
|
59
|
+
return any(t.startswith("seq:step:") for t in tags) and not any(
|
|
60
|
+
t.startswith("graph:step:") for t in tags
|
|
61
|
+
)
|
|
62
|
+
|
|
63
|
+
def _start(
|
|
64
|
+
self,
|
|
65
|
+
run_id: UUID,
|
|
66
|
+
parent_run_id: UUID | None,
|
|
67
|
+
*,
|
|
68
|
+
name: str,
|
|
69
|
+
kind: SpanKind,
|
|
70
|
+
inputs: Any,
|
|
71
|
+
params: dict[str, Any] | None = None,
|
|
72
|
+
tags: list[str] | None = None,
|
|
73
|
+
metadata: dict[str, Any] | None = None,
|
|
74
|
+
) -> None:
|
|
75
|
+
ctx = current_context()
|
|
76
|
+
if ctx is None or ctx.trace_id is None:
|
|
77
|
+
return # 没有 trace 上下文就不落 span,避免孤儿数据
|
|
78
|
+
with self._lock:
|
|
79
|
+
parent_span_id = (
|
|
80
|
+
self._span_by_run.get(parent_run_id) if parent_run_id else ctx.span_id
|
|
81
|
+
)
|
|
82
|
+
if parent_span_id is None and parent_run_id is not None:
|
|
83
|
+
parent_span_id = ctx.span_id
|
|
84
|
+
if self._is_wrapper_chain(kind.value, tags):
|
|
85
|
+
self._span_by_run[run_id] = parent_span_id
|
|
86
|
+
self._skipped.add(run_id)
|
|
87
|
+
return
|
|
88
|
+
|
|
89
|
+
p: dict[str, Any] = dict(params or {})
|
|
90
|
+
if tags:
|
|
91
|
+
p["tags"] = tags
|
|
92
|
+
if metadata:
|
|
93
|
+
p["metadata"] = to_jsonable(metadata)
|
|
94
|
+
try:
|
|
95
|
+
span = self.tracer.record_span(
|
|
96
|
+
ctx.trace_id,
|
|
97
|
+
name,
|
|
98
|
+
kind=kind,
|
|
99
|
+
parent_span_id=parent_span_id,
|
|
100
|
+
input=inputs,
|
|
101
|
+
params=p,
|
|
102
|
+
status=Status.RUNNING,
|
|
103
|
+
span_id=None,
|
|
104
|
+
)
|
|
105
|
+
except Exception: # noqa: BLE001 - 追踪不能影响业务
|
|
106
|
+
self._logger.debug("record_span start failed", exc_info=True)
|
|
107
|
+
return
|
|
108
|
+
with self._lock:
|
|
109
|
+
self._span_by_run[run_id] = span.span_id
|
|
110
|
+
self._starts[span.span_id] = time.perf_counter()
|
|
111
|
+
|
|
112
|
+
def _end(
|
|
113
|
+
self,
|
|
114
|
+
run_id: UUID,
|
|
115
|
+
*,
|
|
116
|
+
outputs: Any = None,
|
|
117
|
+
error: BaseException | None = None,
|
|
118
|
+
params_patch: dict[str, Any] | None = None,
|
|
119
|
+
) -> None:
|
|
120
|
+
with self._lock:
|
|
121
|
+
span_id = self._span_by_run.pop(run_id, None)
|
|
122
|
+
started = self._starts.pop(span_id, None) if span_id else None
|
|
123
|
+
skipped = run_id in self._skipped
|
|
124
|
+
self._skipped.discard(run_id)
|
|
125
|
+
if skipped or not span_id:
|
|
126
|
+
return
|
|
127
|
+
span = self.tracer.store.get_span(span_id)
|
|
128
|
+
if span is None:
|
|
129
|
+
return
|
|
130
|
+
try:
|
|
131
|
+
if error:
|
|
132
|
+
span.mark_error(f"{type(error).__name__}: {error}")
|
|
133
|
+
else:
|
|
134
|
+
span.mark_ok(outputs, params_patch)
|
|
135
|
+
span.end_time = datetime.now().astimezone().isoformat(timespec="milliseconds")
|
|
136
|
+
span.duration_ms = round((time.perf_counter() - started) * 1000, 3) if started else 0.0
|
|
137
|
+
self.tracer.store.save_span(span)
|
|
138
|
+
except Exception: # noqa: BLE001
|
|
139
|
+
self._logger.debug("record_span end failed", exc_info=True)
|
|
140
|
+
|
|
141
|
+
# ------------------------------------------------------------ chain
|
|
142
|
+
def on_chain_start(self, serialized, inputs, *, run_id, parent_run_id=None,
|
|
143
|
+
tags=None, metadata=None, **kwargs):
|
|
144
|
+
meta = metadata or {}
|
|
145
|
+
node_meta = {
|
|
146
|
+
k: to_jsonable(meta[k])
|
|
147
|
+
for k in ("langgraph_node", "langgraph_step", "langgraph_path", "langgraph_triggers")
|
|
148
|
+
if k in meta
|
|
149
|
+
}
|
|
150
|
+
self._start(
|
|
151
|
+
run_id, parent_run_id,
|
|
152
|
+
name=self._chain_name(serialized, metadata),
|
|
153
|
+
kind=SpanKind.CHAIN, inputs=inputs, params=node_meta or None,
|
|
154
|
+
tags=tags, metadata=metadata,
|
|
155
|
+
)
|
|
156
|
+
|
|
157
|
+
def on_chain_end(self, outputs, *, run_id, parent_run_id=None, **kwargs):
|
|
158
|
+
self._end(run_id, outputs=outputs)
|
|
159
|
+
|
|
160
|
+
def on_chain_error(self, error, *, run_id, parent_run_id=None, **kwargs):
|
|
161
|
+
self._end(run_id, error=error)
|
|
162
|
+
|
|
163
|
+
# -------------------------------------------------------------- llm
|
|
164
|
+
def _llm_start(self, run_id, parent_run_id, serialized, inputs, *,
|
|
165
|
+
tags, metadata, invocation_params, default_name):
|
|
166
|
+
inv = invocation_params or {}
|
|
167
|
+
serialized = serialized or {}
|
|
168
|
+
skwargs = serialized.get("kwargs") or {}
|
|
169
|
+
meta: dict[str, Any] = metadata or {}
|
|
170
|
+
sources = (meta, inv, skwargs)
|
|
171
|
+
|
|
172
|
+
def pick(*keys: str) -> Any:
|
|
173
|
+
for source in sources:
|
|
174
|
+
for key in keys:
|
|
175
|
+
if key in source and source[key] is not None:
|
|
176
|
+
return source[key]
|
|
177
|
+
return None
|
|
178
|
+
|
|
179
|
+
params = {
|
|
180
|
+
k: v for k, v in {
|
|
181
|
+
"model": pick("model", "model_name", "model_id", "ls_model_name"),
|
|
182
|
+
"temperature": pick("temperature", "ls_temperature"),
|
|
183
|
+
"max_tokens": pick("max_tokens", "ls_max_tokens"),
|
|
184
|
+
"top_p": pick("top_p", "ls_top_p"),
|
|
185
|
+
}.items() if v is not None
|
|
186
|
+
}
|
|
187
|
+
self._start(
|
|
188
|
+
run_id, parent_run_id,
|
|
189
|
+
name=self._name(serialized, default_name),
|
|
190
|
+
kind=SpanKind.LLM, inputs=inputs, params=params,
|
|
191
|
+
tags=tags, metadata=metadata,
|
|
192
|
+
)
|
|
193
|
+
|
|
194
|
+
def on_llm_start(self, serialized, prompts, *, run_id, parent_run_id=None,
|
|
195
|
+
tags=None, metadata=None, **kwargs):
|
|
196
|
+
self._llm_start(run_id, parent_run_id, serialized, prompts,
|
|
197
|
+
tags=tags, metadata=metadata,
|
|
198
|
+
invocation_params=kwargs.get("invocation_params"),
|
|
199
|
+
default_name="llm")
|
|
200
|
+
|
|
201
|
+
def on_chat_model_start(self, serialized, messages, *, run_id, parent_run_id=None,
|
|
202
|
+
tags=None, metadata=None, **kwargs):
|
|
203
|
+
self._llm_start(run_id, parent_run_id, serialized, messages,
|
|
204
|
+
tags=tags, metadata=metadata,
|
|
205
|
+
invocation_params=kwargs.get("invocation_params"),
|
|
206
|
+
default_name="chat_model")
|
|
207
|
+
|
|
208
|
+
def on_llm_end(self, response, *, run_id, parent_run_id=None, **kwargs):
|
|
209
|
+
patch: dict[str, Any] = {}
|
|
210
|
+
usage = _extract_usage(response)
|
|
211
|
+
if usage:
|
|
212
|
+
patch["usage"] = usage
|
|
213
|
+
self._end(run_id, outputs=_llm_output(response), params_patch=patch)
|
|
214
|
+
|
|
215
|
+
def on_llm_error(self, error, *, run_id, parent_run_id=None, **kwargs):
|
|
216
|
+
self._end(run_id, error=error)
|
|
217
|
+
|
|
218
|
+
# ------------------------------------------------------------- tool
|
|
219
|
+
def on_tool_start(self, serialized, input_str, *, run_id, parent_run_id=None,
|
|
220
|
+
tags=None, metadata=None, inputs=None, **kwargs):
|
|
221
|
+
name = self._name(serialized, "tool")
|
|
222
|
+
args = inputs if inputs is not None else _try_parse(input_str)
|
|
223
|
+
self._start(
|
|
224
|
+
run_id, parent_run_id,
|
|
225
|
+
name=name, kind=SpanKind.TOOL, inputs=input_str,
|
|
226
|
+
params={"tool_name": name, "args": to_jsonable(args or {})},
|
|
227
|
+
tags=tags, metadata=metadata,
|
|
228
|
+
)
|
|
229
|
+
|
|
230
|
+
def on_tool_end(self, output, *, run_id, parent_run_id=None, **kwargs):
|
|
231
|
+
self._end(run_id, outputs=output)
|
|
232
|
+
|
|
233
|
+
def on_tool_error(self, error, *, run_id, parent_run_id=None, **kwargs):
|
|
234
|
+
self._end(run_id, error=error)
|
|
235
|
+
|
|
236
|
+
|
|
237
|
+
# ------------------------------------------------------------------ 辅助
|
|
238
|
+
def _try_parse(text: str) -> dict[str, Any] | None:
|
|
239
|
+
import json
|
|
240
|
+
try:
|
|
241
|
+
value = json.loads(text)
|
|
242
|
+
return value if isinstance(value, dict) else {"input": value}
|
|
243
|
+
except (ValueError, TypeError):
|
|
244
|
+
return {"input": text} if text else None
|
|
245
|
+
|
|
246
|
+
|
|
247
|
+
def _extract_usage(response: Any) -> dict[str, Any]:
|
|
248
|
+
usage: dict[str, Any] = {}
|
|
249
|
+
for batch in getattr(response, "generations", None) or []:
|
|
250
|
+
gens = batch if isinstance(batch, (list, tuple)) else [batch]
|
|
251
|
+
for gen in gens:
|
|
252
|
+
msg = getattr(gen, "message", None)
|
|
253
|
+
meta = getattr(msg, "usage_metadata", None)
|
|
254
|
+
if isinstance(meta, dict):
|
|
255
|
+
usage.update({k: meta[k] for k in
|
|
256
|
+
("input_tokens", "output_tokens", "total_tokens") if k in meta})
|
|
257
|
+
break
|
|
258
|
+
return usage
|
|
259
|
+
|
|
260
|
+
|
|
261
|
+
def _llm_output(response: Any) -> dict[str, Any]:
|
|
262
|
+
generations = []
|
|
263
|
+
for batch in getattr(response, "generations", None) or []:
|
|
264
|
+
gens = batch if isinstance(batch, (list, tuple)) else [batch]
|
|
265
|
+
for gen in gens:
|
|
266
|
+
msg = getattr(gen, "message", None)
|
|
267
|
+
generations.append({
|
|
268
|
+
"text": getattr(msg, "content", None),
|
|
269
|
+
"tool_calls": to_jsonable(getattr(msg, "tool_calls", None)),
|
|
270
|
+
})
|
|
271
|
+
return {"generations": generations}
|
|
272
|
+
|
|
273
|
+
|
|
274
|
+
__all__ = ["TracingCallbackHandler"]
|
|
@@ -0,0 +1,127 @@
|
|
|
1
|
+
"""LangChain / LangGraph 无感接入。
|
|
2
|
+
|
|
3
|
+
只需在进程启动时调用一次 instrument_langchain(),
|
|
4
|
+
之后所有现有的 `agent.invoke(...)` / `await agent.ainvoke(...)` 调用
|
|
5
|
+
都会自动产生 trace/span,业务代码一行都不用改。
|
|
6
|
+
"""
|
|
7
|
+
from __future__ import annotations
|
|
8
|
+
|
|
9
|
+
from typing import Any, Callable
|
|
10
|
+
|
|
11
|
+
from ..models import SpanKind
|
|
12
|
+
from ..tracer import Tracer
|
|
13
|
+
from .callbacks import TracingCallbackHandler
|
|
14
|
+
from .patch import instrument, uninstrument
|
|
15
|
+
|
|
16
|
+
_LANGCHAIN_METHODS = ("invoke", "ainvoke")
|
|
17
|
+
_STREAM_METHODS = ("stream", "astream")
|
|
18
|
+
|
|
19
|
+
|
|
20
|
+
def _name(owner: Any) -> str:
|
|
21
|
+
name = getattr(owner, "name", None)
|
|
22
|
+
return str(name) if name else type(owner).__name__
|
|
23
|
+
|
|
24
|
+
|
|
25
|
+
def _run_params(owner: Any, args: tuple[Any, ...], kwargs: dict[str, Any]) -> dict[str, Any]:
|
|
26
|
+
"""从 LangChain RunnableConfig 中提取运行参数写入 params。"""
|
|
27
|
+
config = kwargs.get("config")
|
|
28
|
+
if config is None and len(args) > 1:
|
|
29
|
+
config = args[1]
|
|
30
|
+
cfg = dict(config or {})
|
|
31
|
+
configurable = dict(cfg.get("configurable") or {})
|
|
32
|
+
params: dict[str, Any] = {
|
|
33
|
+
"agent_name": getattr(owner, "name", None),
|
|
34
|
+
"thread_id": configurable.get("thread_id"),
|
|
35
|
+
"recursion_limit": cfg.get("recursion_limit"),
|
|
36
|
+
"tags": cfg.get("tags"),
|
|
37
|
+
"metadata": cfg.get("metadata"),
|
|
38
|
+
}
|
|
39
|
+
return {k: v for k, v in params.items() if v not in (None, [], {})}
|
|
40
|
+
|
|
41
|
+
|
|
42
|
+
def _candidate_classes() -> list[type]:
|
|
43
|
+
classes: list[type] = []
|
|
44
|
+
try:
|
|
45
|
+
from langchain_core.runnables import Runnable
|
|
46
|
+
|
|
47
|
+
classes.append(Runnable)
|
|
48
|
+
except ImportError:
|
|
49
|
+
pass
|
|
50
|
+
try:
|
|
51
|
+
from langgraph.pregel import Pregel
|
|
52
|
+
|
|
53
|
+
classes.append(Pregel)
|
|
54
|
+
except ImportError:
|
|
55
|
+
pass
|
|
56
|
+
try:
|
|
57
|
+
from langgraph.graph.state import CompiledStateGraph
|
|
58
|
+
|
|
59
|
+
classes.append(CompiledStateGraph)
|
|
60
|
+
except ImportError:
|
|
61
|
+
pass
|
|
62
|
+
# 去重(Pregel 与 CompiledStateGraph 可能存在继承关系,但类对象不同)
|
|
63
|
+
seen: set[int] = set()
|
|
64
|
+
return [c for c in classes if not (id(c) in seen or seen.add(id(c)))]
|
|
65
|
+
|
|
66
|
+
|
|
67
|
+
def instrument_langchain(
|
|
68
|
+
*,
|
|
69
|
+
tracer: Tracer | None = None,
|
|
70
|
+
patch_invoke: bool = True,
|
|
71
|
+
patch_stream: bool = False,
|
|
72
|
+
kind: SpanKind | str = SpanKind.AGENT,
|
|
73
|
+
name: Callable[[Any], str] | None = None,
|
|
74
|
+
inject_callbacks: bool = True,
|
|
75
|
+
) -> int:
|
|
76
|
+
"""给 LangChain / LangGraph 的 Runnable 方法打追踪补丁。
|
|
77
|
+
|
|
78
|
+
:param patch_stream: 是否同时包裹 stream/astream;默认关闭,避免与 invoke
|
|
79
|
+
在 LangGraph 内部相互调用时产生重复 span。
|
|
80
|
+
:param inject_callbacks: 是否自动把 TracingCallbackHandler 注入 config["callbacks"];
|
|
81
|
+
开启后 deepagents / LangGraph 内部的 chain/llm/tool
|
|
82
|
+
调用也会自动落成 span 树(默认开启)。
|
|
83
|
+
:return: 成功打上的补丁数量
|
|
84
|
+
"""
|
|
85
|
+
classes = _candidate_classes()
|
|
86
|
+
if not classes:
|
|
87
|
+
raise RuntimeError(
|
|
88
|
+
"未检测到 langchain-core / langgraph,请先安装或改用 tracespan.instrument() 手动接入"
|
|
89
|
+
)
|
|
90
|
+
|
|
91
|
+
resolved_kind = SpanKind(kind) if isinstance(kind, str) else kind
|
|
92
|
+
methods = list(_LANGCHAIN_METHODS) if patch_invoke else []
|
|
93
|
+
if patch_stream:
|
|
94
|
+
methods += list(_STREAM_METHODS)
|
|
95
|
+
|
|
96
|
+
def make_callback() -> TracingCallbackHandler:
|
|
97
|
+
return TracingCallbackHandler(tracer=tracer)
|
|
98
|
+
|
|
99
|
+
count = 0
|
|
100
|
+
for cls in classes:
|
|
101
|
+
for method in methods:
|
|
102
|
+
if not hasattr(cls, method):
|
|
103
|
+
continue
|
|
104
|
+
if instrument(
|
|
105
|
+
cls,
|
|
106
|
+
method,
|
|
107
|
+
name=name or _name,
|
|
108
|
+
kind=resolved_kind if method in _LANGCHAIN_METHODS else SpanKind.CUSTOM,
|
|
109
|
+
tracer=tracer,
|
|
110
|
+
params=_run_params,
|
|
111
|
+
inject_callbacks=make_callback if inject_callbacks else None,
|
|
112
|
+
):
|
|
113
|
+
count += 1
|
|
114
|
+
return count
|
|
115
|
+
|
|
116
|
+
|
|
117
|
+
def uninstrument_langchain() -> int:
|
|
118
|
+
"""还原 LangChain / LangGraph 的全部追踪补丁。"""
|
|
119
|
+
count = 0
|
|
120
|
+
for cls in _candidate_classes():
|
|
121
|
+
for method in (*_LANGCHAIN_METHODS, *_STREAM_METHODS):
|
|
122
|
+
if uninstrument(cls, method):
|
|
123
|
+
count += 1
|
|
124
|
+
return count
|
|
125
|
+
|
|
126
|
+
|
|
127
|
+
__all__ = ["instrument_langchain", "uninstrument_langchain"]
|