Flue OpenTelemetry集成教程Agent全链路追踪【免费下载链接】flueThe sandbox agent framework.项目地址: https://gitcode.com/GitHub_Trending/flue1/flueFlue 是开源的沙箱化 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 APIpnpm 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 的每个执行边界都对应一个语义清晰的 spanFlue 边界OpenTelemetry 表示说明提示词 / 技能调用invoke_agent agent内部 spanAgent 一次完整工作的根 span委派的子任务invoke_agent agent任务 span子 Agent 独立成链模型推理chat 模型名客户端 span只计推理时间含 Token 用量工具执行execute_tool 名称内部 span与模型输出通过gen_ai.tool.call.id关联调用方 shell 执行flue.operation shell内部 span程序化 shell 活动上下文压缩flue.compaction内部 span携带子 chat 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指标用途gen_ai.client.operation.duration每次模型调用的耗时分布gen_ai.client.token.usage输入/输出 Token 用量输入含缓存读写 Tokengen_ai.invoke_agent.durationAgent 完整调用耗时gen_ai.execute_tool.duration工具执行耗时成本归因小贴士指标维度刻意排除了各类执行 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是否移除了预期内容。关于追踪传播两点需要知道traceparent/tracestate会在直连 Agent 接收请求时被验证并持久化重启后恢复的执行能延续原链路——这对排查跨重启的长任务尤其有用。dispatch(...)目前不传播追踪上下文跨请求派发的链路暂不自动串联。另外Flue 坚持不编造数据的原则当前不输出首块延迟time-to-first-chunk等无法权威获取的指标Agent 创建、规划、embedding 等尚无真实边界的操作也不会虚构 span——你看到的每一条 span 都对应真实执行。常见问题 FAQQflue/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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考