可观测
平台默认零侵入采集 Agent 框架、模型调用、工具等调用的全链路 trace，业务自定义指标用
context.tracer 手动上报。Agent 框架自动采集支持矩阵
底层基于 OpenInference instrumentation，在用户代码加载前注入。主流 LLM SDK 与 Agent 框架的调用自动产生 span，与
context.tracer 手动 span 共享同一 traceId、自然嵌套。框架 | Python | Node |
Claude Agent SDK | ✅ | ✅ |
OpenAI Agents SDK | ✅ | ✅ |
DeepAgents | ✅ | ✅ |
LangGraph | ✅ | ✅ |
CrewAI | ✅ | - |
采集范围
类别 | 内容 |
模型调用 | 模型名、输入 / 输出、token 用量 等 |
Agent 框架链路 | Agent 决策、节点流转、子 Agent 委派 |
工具调用 | 工具名、参数、返回值、耗时 |
可观测数据
平台提供 控制台、本地调试 两套面板，共用同一份 trace 数据契约——UI 布局、字段定义、过滤维度完全一致，差异仅在数据来源（本地仅当前 dev 进程、控制台聚合所有线上请求）。
控制台可观测面板
进入控制台 → 选择您的 Agent 项目 → 切换到 Agent 选项卡，在 Metrics、Traces 两个子页查看数据。
Metrics 数据
按时间窗口聚合的核心指标，可以查看 Agent 调用次数、模型调用次数、模型调用错误率、模型调用平均耗时、Token 总消耗、平均 Token/模型调用。
Traces 数据
每一次任务执行对应一棵 trace 树，可用于精确还原一次请求：
链路结构：从 root request span 开始，下挂 Agent 框架自动 span，层级嵌套关系一目了然。
LLM 调用详情：每个 LLM span 展开可看 prompt、completion、模型名、token 用量、耗时。
工具调用详情：Tool span 展开可看入参、返回值、耗时，便于排查"工具是不是被正确调用了"。
错误堆栈：被标记为 ERROR 的 span 直接展示 exception name、message 信息，跳过翻日志环节。
过滤与检索：支持按
run_id / conversation_id 过滤，定位某会话、某次执行的链路。
本地调试面板
edgeone makes dev 启动时会自动拉起本地调试面板（默认 http://localhost:8088/agent-metrics），无需额外配置：数据来源：仅采集当前 dev 进程产生的 trace，不与线上数据混合，调试隔离干净。
能力对齐：Metrics / Traces 两个子页与控制台完全一致，包括链路结构、LLM 详情、属性过滤。
几乎零延迟：trace 写入即可见——改一处代码、跑一次请求、立刻在面板看链路差异。
手动插桩 context.tracer
OpenInference 的 instrumentor 能覆盖主流 LLM SDK 和框架，但有些场景采集不到（如未支持的框架、自定义业务逻辑、内部服务调用）。这些场景可以用
context.tracer 手动补进行上报。API 概览
API | 用途 |
tracer.span(name, fn, attrs?) | 创建子 span 并执行 fn，自动管理生命周期与异常 |
tracer.startSpan(name, attrs?) | 创建 span，需手动调用 end() |
tracer.setAttributes(attrs) | 为当前活跃 span 批量设置属性 |
Node / Python 命名映射：JS 用驼峰（startSpan/setAttributes），Python 用下划线（start_span/set_attributes），其余一致，下文每个 API 同时给出 Node 与 Python 示例。
span(name, fn, attrs?)
创建一个 span 并在其中执行
fn，fn 抛异常时自动记录异常 ，fn 内部产生的任何 span（自动或手动）都会成为其子节点。参数
Parameter | Type | Required | Description |
name | string | Yes | span 名称 |
fn | (span: Span) => Promise<T> | Yes | 在 span 上下文中执行的函数，参数 span 用于在块内追加属性 |
attrs | Record<string, string | number | boolean> | No | span 创建时的初始属性 |
返回值
透传
fn 的返回值。TS 示例：
const intent = await context.tracer.span('classify_intent', async (span) => {const res = await openai.chat.completions.create({ /* ... */ });const label = res.choices[0].message.content.trim();span.setAttributes({ 'intent.label': label });return label;}, { 'agent.step': 'intent' });
Python 示例：
async def classify(span):res = await openai_client.chat.completions.create(...)label = res.choices[0].message.content.strip()span.set_attributes({"intent.label": label})return labelintent = await ctx.tracer.span("classify_intent", classify, {"agent.step": "intent"})
startSpan(name, attrs?)
创建 span ，需显式调用
span.end()，期间产生的其他 span 不会自动嵌套在其下，需要嵌套请用 span()，适用于跨异步边界的场景（如把任务丢进队列、在回调里结束）。参数
Parameter | Type | Required | Description |
name | string | Yes | span 名称 |
attrs | Record<string, string | number | boolean> | No | span 创建时的初始属性 |
返回值
Span — 同步返回 span 对象。调用方必须配对调用 span.end()，否则不会上报且常驻内存。TS 示例：
const span = context.tracer.startSpan('async_pipeline', { 'pipeline.stage': 'init' });try {await doStep1();await doStep2();} finally {span.end(); // 必须调用}
Python 示例：
span = ctx.tracer.start_span("async_pipeline", {"pipeline.stage": "init"})try:await do_step_1()await do_step_2()finally:span.end()
setAttributes(attrs)
为当前活跃 span 批量设置属性，可用于给平台自动创建的 span 打业务标签。
参数
Parameter | Type | Required | Description |
attrs | Record<string, string | number | boolean> | Yes | 要设置的属性键值对，复杂对象需自行 JSON 序列化 |
TS 示例：
context.tracer.setAttributes({'user.id': context.request.body.userId,'user.tier': 'premium','agent.scenario': 'customer_service',});// ... 业务逻辑
Python 示例：
context.tracer.set_attributes({"user.id": ctx.request.body.get("userId"),"user.tier": "premium","agent.scenario": "customer_service",})
在span()的fn内或startSpan()返回的 span 上追加属性，请直接调用span.setAttributes(...)。
使用约束
不要引用 import OpenTelemetry SDK，会破坏平台的自动上报与重复 instrument。
startSpan 创建的 span 必须配对 end()，否则不会上报且常驻内存。属性值仅支持
string / number / boolean；对象 / 数组需自行序列化为 JSON 字符串。span 名禁止使用高基数动态值（如 userId、订单号），把动态值放属性里。
通用属性
下列属性自动 + 手动 span 共享，是控制台面板过滤与聚合的核心维度。
属性 | 含义 |
agent.run_id | 一次 handler 执行的唯一 ID，串联本次执行所有 span |
agent.conversation_id | 会话 ID，用于跨 run 聚合 |
agent.route_path | 当前请求路由 |
llm.* / gen_ai.* / openinference.* | OpenInference 标准 LLM 属性（模型、token 用量等） |
