企业官网建设流程全解析

Flue + OpenTelemetry集成教程：Agent全链路追踪

【免费下载链接】flueThe sandbox agent framework.项目地址: https://gitcode.com/GitHub_Trending/flue1/flue

Flue 是开源的沙箱化 Agent 框架，通过@flue/opentelemetry集成包，你可以把 Flue Agent 的每次运行——模型调用、工具执行、子任务委派——自动投影成标准的 OpenTelemetry GenAI 追踪、指标和日志，实现真正的Agent 全链路追踪。本教程将用 3 个步骤完成接入，并教你读懂追踪数据、脱敏敏感内容。

为什么 Agent 需要 OpenTelemetry 全链路追踪？

🤔 Agent 和传统 Web 服务不同：一次用户请求背后可能是多轮模型推理、多次工具调用、甚至子 Agent 委派。出问题时，你很难回答这些问题：

• Agent 到底调了几次模型？每次耗时多少？
• 哪个工具卡住了整个流程？
• Token 花在了哪一步？成本如何归因？

Flue 的解决方案分两层：运行时把所有活动（模型轮次、工具调用、日志、用量）以类型化事件流发出，而@flue/opentelemetry把这些事件投影成遵循OpenTelemetry GenAI 语义约定的 span 与指标，直接送进你已有的任何 OTel 后端（Jaeger、Grafana Tempo、Datadog 等），无需私有格式。

最快接入方法：3 步完成 OpenTelemetry 集成

第 1 步：安装集成包与 OpenTelemetry API

pnpm add @flue/opentelemetry @opentelemetry/api

第 2 步：先配置好你自己的 OTel SDK 与导出器（采样、凭据、部署目标都由应用侧掌控，集成包不越界）。

第 3 步：在src/app.ts中注册一次探针

import { createOpenTelemetryInstrumentation } from '@flue/opentelemetry'; import { instrument } from '@flue/runtime'; const instrumentation = createOpenTelemetryInstrumentation(); const disposeInstrumentation = instrument(instrumentation);

注册完成后，所有 Agent 的运行时活动都会自动变成带层级关系的 GenAI span。生成的 Node 应用会在活动排空后自动清理注册，无需手动管理生命周期。

实现细节可参考：packages/opentelemetry/src/index.ts，探针与执行拦截器的配对逻辑让 span 能精确包裹正在运行的 Agent、模型流、工具与任务。

读懂追踪数据：Agent 的 6 种 Span 长什么样

这是全链路追踪中最实用的一张对照表，Flue 的每个执行边界都对应一个语义清晰的 span：

几个值得注意的追踪关联字段：

• gen_ai.conversation.id：对应持久化的 Flue 会话身份，可用于跨请求串联整个会话的链路。
• gen_ai.provider.name：语义化的模型提供方名称，方便按 provider 维度聚合。
• flue.*属性：标准字段覆盖不到的 Flue 关联信息（如操作 ID）都以文档化的flue.*前缀保留，不会污染gen_ai.*命名空间。

免费获得 Token 用量与耗时指标 📊

除了 Traces，探针还会自动发出 4 个标准指标（实现见 packages/opentelemetry/src/metrics.ts）：

💡成本归因小贴士：指标维度刻意排除了各类执行 ID，只保留 Agent、工具、provider、模型名等低基数维度，直接适合做成本看板聚合。

日志（Logs）是可选的：只有显式注入 Logger 后，失败推理才会发出标准的gen_ai.client.operation.exception事件（WARN/13 级别）。没有 Logger 也不影响 Traces 和 Metrics 正常工作。

保护敏感内容：默认捕获与两步脱敏

⚠️ 一个重要设计：内容捕获默认开启——模型消息、系统指令、工具参数/结果、异常堆栈都会作为 span 属性导出。这是刻意为之：显式调用instrument(...)本身即视为"知情同意"。如果你的后端不适合存储会话数据，用以下任一开关管控：

// 方式一：完全关闭内容 createOpenTelemetryInstrumentation({ content: false }); // 方式二：按策略脱敏（推荐） createOpenTelemetryInstrumentation({ content: { transform(content, scope) { if (scope.contentType === 'exception_stacktrace') return undefined; // 丢弃堆栈 return redactSecrets(content); // 脱敏密钥、PII 等 }, }, });

此外还有内建的字节预算保护：每个 span 的内容共享 56 KiB 的池子，超出部分自动截断并留下[flue:truncated, …]标记——在追踪后端搜索[flue]就能快速定位被截断的 payload。

验证与排查：确认链路追踪真正生效

用内存导出器做断言测试是最可靠的验证方式：在测试中挂一个 in-memory exporter，校验 span 层级、名称、类型、状态与属性，以及你的脱敏策略是否真的生效（content: false或transform是否移除了预期内容）。

关于追踪传播，两点需要知道：

1. traceparent/tracestate会在直连 Agent 接收请求时被验证并持久化，重启后恢复的执行能延续原链路——这对排查跨重启的长任务尤其有用。
2. dispatch(...)目前不传播追踪上下文，跨请求派发的链路暂不自动串联。

另外，Flue 坚持"不编造数据"的原则：当前不输出首块延迟（time-to-first-chunk）等无法权威获取的指标，Agent 创建、规划、embedding 等尚无真实边界的操作也不会虚构 span——你看到的每一条 span 都对应真实执行。

常见问题 FAQ

Q：@flue/opentelemetry能帮我配置 SDK 和导出器吗？不能。它只负责把 Flue 运行时活动投影为 GenAI 语义数据，SDK、导出器、采样策略、部署配置全部由你掌控，保持标准 OTel 生态的开放性。

Q：和 Cloudflare Workers Traces 是什么关系？如果部署在 Cloudflare，平台自带 Agent 形状的 span（同样的 GenAI 命名）；而本集成让你把完整链路导出到任何标准 OTel 后端，两者互不冲突。

Q：如何升级到本包？旧 APIcreateOpenTelemetryObserver()已被createOpenTelemetryInstrumentation()取代，迁移说明见 packages/opentelemetry/README.md。

总结

Flue + OpenTelemetry 的组合，让 Agent 从"黑盒"变成可观测的工程组件：3 行代码注册探针，即获得符合 GenAI 语义约定的全链路 Traces、4 个成本/耗时指标和可选的结构化日志。完整文档见 apps/docs/src/content/docs/ecosystem/tooling/opentelemetry.md 与可观测性指南 apps/docs/src/content/docs/guide/observability.md。想要动手体验，可克隆仓库git clone https://gitcode.com/GitHub_Trending/flue1/flue后参考examples/下的示例应用。现在，给你的 Agent 装上"全链路追踪"，让每一次推理都有迹可循吧 🚀

【免费下载链接】flueThe sandbox agent framework.项目地址: https://gitcode.com/GitHub_Trending/flue1/flue