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

一、Agent 框架自动采集支持矩阵

底层基于 OpenInference instrumentation，在用户代码加载前注入。主流 LLM SDK 与 Agent 框架的调用自动产生 span，与 context.tracer 手动 span 共享同一 traceId、自然嵌套。

二、采集范围

三、可观测数据

平台提供 控制台、本地调试 两套面板，共用同一份 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 概览

注意：说明：

注意：Node / Python 命名映射：JS 用驼峰（startSpan / setAttributes），Python 用下划线（start_span / set_attributes），其余一致，下文每个 API 同时给出 Node 与 Python 示例。

八、span(name, fn, attrs?)

创建一个 span 并在其中执行 fn，fn 抛异常时自动记录异常 ，fn 内部产生的任何 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()，适用于跨异步边界的场景（如把任务丢进队列、在回调里结束）。

十三、参数

十四、返回值

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 打业务标签。

十七、参数

十八、TS 示例：

context.tracer.setAttributes({ 'user.id': context.request.body.userId, 'user.tier': 'premium', 'agent.scenario': 'customer_service',});// … 业务逻辑

Python 示例：

context.tracer.set_attributes({ "user.id": context.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、订单号），把动态值放属性里。

20、通用属性

下列属性自动 + 手动 span 共享，是控制台面板过滤与聚合的核心维度。