故障排查

Trace 没有上报

排查步骤：

1. 检查 transport 是否启用

   • host 是否为空？为空时 transport disabled，startRun() 返回 undefined

2. 检查 SDK 是否初始化

   • 观察日志中是否有 langfuse-transport.sdk-init
   • 没有出现说明没有 run 启动或 transport disabled

3. 检查 health check

   • 观察日志中 langfuse-transport.health-check / langfuse-transport.health-check-failed
   • 失败优先查 Langfuse 代理地址、网络连通性和鉴权头

4. 检查 span 是否 export

   • 观察日志中 langfuse-transport.span-export
   • 没有出现说明 observation 没有正常 end，或宿主事件没有流到 adapter

5. 检查 flush 是否完成

   • 观察日志中 observer.flush-ok / observer.flush-error
   • flush error 通常是 OTEL exporter 或代理失败

6. 检查进程退出

   • 是否调用了 observer.gate.waitAll()？
   • 进程太快退出会导致后台 exporter 来不及发送

Generation 没有输出

1. 确认 startGeneration() 是否在 appendText() 之前调用
2. 确认 appendText() 是否被调用
3. 确认写入的是 assistant 输出，不是用户原文
4. 确认 endGeneration() 是否调用

Tool Span 泄漏

日志中出现 span leaked: run ended before tool completed：

1. 确认 startTool() 有 id（callId）
2. 确认 endTool() / tool.end() 的 callId 与 startTool 一致
3. 工具报错时也要调用 endTool({ error: "..." })

Score 没写入

1. 确认 score() 在 startRun() 之后、endRun() 之前调用
2. 确认 score 的 dataType 和 value 类型一致：
   • CATEGORICAL → value 是 string
   • NUMERIC → value 是 number
   • BOOLEAN → value 是 boolean
3. 确认进程退出前调用了 gate.waitAll()

脱敏没生效

1. 内置规则：查看对应格式是否在覆盖范围内（见数据脱敏）
2. 自定义规则：确认 LANGFUSE_MASK_RULES 是合法 JSON 数组
3. 用 listExtraRules() 检查规则是否成功注册
4. 注意：metadata 不脱敏，这是当前设计

Transport 鉴权失败

直连模式：

• 确认 publicKey 和 secretKey 正确
• 确认 host URL 末尾没有多余的斜杠

代理模式：

• 确认 authHeaders 回调返回的 headers 正确
• 确认 session token 是否过期（authHeaders 每次 export 都会重新调用）
• 检查代理服务是否正常运行

常见错误信息

错误信息	原因	解决方案
startRun returned undefined	transport disabled	检查 host 是否为空
span leaked: run ended before tool completed	tool span 未关闭	确保 endTool() 被调用
langfuse-transport.health-check-failed	无法连接 Langfuse	检查网络和鉴权
observer.flush-error	OTEL 上报失败	检查 exporter 配置