集成已合并不等于运行时已启用

更新于 2026-09-22

**「代码已接入」（integration merged）和「运行时已启用」（runtime enabled）是两个状态，很多集成被设计成配置为空时静默关闭。** 于是仓库里、CI 里、本地 `.env.local` 里都能看到它「接上了」，生产上却一行数据都没有，而且不报任何错。

实测形态：Langfuse 项目零数据

  • 代码侧：langfuse.ts 已用 OTel SpanProcessor 埋点，PR 已合入，看起来「接了」。
  • 运行侧：Production Agent / Worker 容器的 env 里没有 LANGFUSE_PUBLIC_KEY / LANGFUSE_SECRET_KEY / LANGFUSE_BASE_URL。
  • 设计侧：部署说明明确写「两个 key 都为空时静默关闭 tracing」→ 走到 noop 空实现。
  • 本地侧：.env.local 里有一套真实 key，所以本地测试「能 trace」，进一步加深「已经接好了」的错觉。

要启用不需要改代码，只需把 key 注入容器环境并重建。问题从来不是代码没接，而是没人核对运行时到底拿到了什么配置。

一条配套判据：观测链路独立于业务链路

模型调用：  Agent ──→ gemini-relay ──→ Google
Langfuse：  Agent ──────────────────→ cloud.langfuse.com

tracing 在 Agent 进程内埋点后直传 Langfuse，不经过模型 relay。所以「走不走中转」和「trace 能不能用」是两个独立问题；排查时先把业务链路和观测链路分开，不要用一个的现象去解释另一个。

同理，trace 里看不到 prompt/正文不是坏了：redactLangfuseData 把 prompt/content/input/output 打码成 [REDACTED]，是有意设计——看得到结构与指标（model、usage、cost、turn 状态），看不到对话原文。

可迁移的判断

  • 验证一个集成是否生效，要查运行进程实际拿到的配置（容器 env / 启动参数）和外部系统里是否有数据，而不是查代码、文档、CI 绿灯或本地环境。
  • 看到「静默关闭」「空值时 noop」这类设计，就要把「启用」当成一个必须单独验收的动作。
  • 空配置 + 静默降级 = 零错误信息的假成功。这类失败不会出现在日志里。

相关