边缘安全加速平台 EO 可观测

平台默认零侵入采集 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 label
﻿
intent = 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 用量等）。
﻿

API	用途
`tracer.span(name, fn, attrs?)`	创建子 span 并执行 `fn`，自动管理生命周期与异常。
`tracer.startSpan(name, attrs?)`	创建 span，需手动调用 `end()`。
`tracer.setAttributes(attrs)`	为当前活跃 span 批量设置属性。

可观测

本页目录：

Agent 框架自动采集支持矩阵

采集范围

可观测数据

控制台可观测面板

Metrics 数据

Traces 数据

本地调试面板

手动插桩 `context.tracer`

API 概览

`span(name, fn, attrs?)`

参数

返回值

TS 示例：

`startSpan(name, attrs?)`

参数

返回值

TS 示例：

`setAttributes(attrs)`

参数

TS 示例：

使用约束

通用属性

框架	Python	Node
Claude Agent SDK	✓	✓
OpenAI Agents SDK	✓	✓
DeepAgents	✓	✓
LangGraph	✓	✓
CrewAI	✓	-

类别	内容
模型调用	模型名、输入 / 输出、token 用量等。
Agent 框架链路	Agent 决策、节点流转、子 Agent 委派。
工具调用	工具名、参数、返回值、耗时。

Parameter	Type	Required	Description
`name`	`string`	Yes	span 名称。
`fn`	`(span: Span) => Promise<T>`	Yes	在 span 上下文中执行的函数，参数 `span` 用于在块内追加属性。
`attrs`	`Record<string, string \| number \| boolean>`	No	span 创建时的初始属性。

属性	含义
`agent.run_id`	一次 handler 执行的唯一 ID，串联本次执行所有 span。
`agent.conversation_id`	会话 ID，用于跨 run 聚合。
`agent.route_path`	当前请求路由。
`llm.` / `gen_ai.` / `openinference.*`	OpenInference 标准 LLM 属性（模型、token 用量等）。