Langfuse

这是什么

Langfuse 是一个开源的 LLM 可观测性平台，用于追踪、监控和调试 AI 应用的请求链路。 千手大师通过 OpenTelemetry (OTel) 桥接层把它接入查询流程，实现三类观测：

• LLM 调用追踪：记录每次 API 请求的模型、Provider、输入 / 输出与 Token 用量（含缓存读写拆分）。
• 工具执行追踪：记录每个工具调用的名称、输入、输出、耗时与错误标记。
• 多 Agent 追踪：主 Agent 与 AgentTool 启动的子 Agent 各自拥有独立 Trace。

启用开关由 isLangfuseEnabled() 判定：同时存在 LANGFUSE_PUBLIC_KEY 与 LANGFUSE_SECRET_KEY 时开启， 否则全部追踪函数直接返回 null 或跳过，等价于零开销。

生命周期在启动流程内完成：src/entrypoints/init.ts 启动时调用 initLangfuse() 创建 LangfuseSpanProcessor 与 BasicTracerProvider，并通过 registerCleanup(shutdownLangfuse) 在进程退出时强制 flush 并关闭。依赖库为 @langfuse/otel、@langfuse/tracing 与 @opentelemetry/sdk-trace-base。

前置条件

• 一个 Langfuse 实例：可以在自己的 Docker / Kubernetes 上自部署，也可以使用官方 Langfuse Cloud（https://cloud.langfuse.com，提供免费测试额度）。
• 一对 API 密钥：在实例的 Project Settings → API Keys 页面获取 Public Key（pk-...）与 Secret Key（sk-...）。 两个都要提供，只配置其一会保持 no-op。
• 服务地址：默认指向 Langfuse Cloud；自部署时需要把 LANGFUSE_BASE_URL 指向你的实例。
• 网络出口可达：运行环境需能访问所配置的 Langfuse 主机。

安装 / 启用

无需安装任何 CLI 插件，配置环境变量即可启用。

1. 获取 Public Key 与 Secret Key

   在 Langfuse 实例的 Project Settings → API Keys 页面创建密钥对，记录公钥与密钥。

2. 设置环境变量

   两个密钥必须同时存在。可在真实 shell 环境中导出，或写入用户级 ~/.claude/settings.json 的 env 字段（受信任源，启动早期注入）， 也可写入 ~/.claude.json。

   Terminal 复制

   LANGFUSE_PUBLIC_KEY=pk-xxx \
   LANGFUSE_SECRET_KEY=sk-xxx \
   LANGFUSE_BASE_URL=https://cloud.langfuse.com \
   qsdashi

3. 验证生效

   启动后会创建 Processor（debug 日志输出 [langfuse] Initialized with LangfuseSpanProcessor）， 每轮对话创建 Trace（[langfuse] Trace created: ...）， 在 Langfuse 面板即可看到对应 Track / Session。

配置

全部通过环境变量控制，均无对应的 CLI 子命令。

追踪层级与脱敏

数据流从一个根 Trace 展开，子节点为 LLM generation 与 tool span：

Trace (Agent Span)                  <- createTrace() / createSubagentTrace()
  ├── Generation (LLM 调用)         <- recordLLMObservation()
  ├── tools (批量工具 span)          <- createToolBatchSpan() / endToolBatchSpan()
  │     ├── Tool Observation        <- recordToolObservation()
  │     └── Tool Observation
  └── ...

主 Agent 每次 query() 调用（即用户一次对话 turn）创建一个 agent 类型的根 Span，名称为 agent-run 或 agent-run:<querySource>， 元数据含 provider、model、agentType: "main"， 并携带 Session ID 以支持按会话聚合。子 Agent 通过 createSubagentTrace() 创建独立 Trace，名称为 agent:<agentType>。

LLM generation 名称按 Provider 映射：

每个工具调用记录为 tool 类型的 Span，名称为工具名（如 FileEditTool、BashTool），元数据含 toolUseId 与 isError；失败时附加 level: ERROR。Trace 结束时若状态为 interrupted 或 error，会分别标记 WARNING / ERROR。

所有上传数据在发送前经 sanitize.ts 处理：

convert.ts 另将内部 Message 类型转换为 Langfuse 期望的 OpenAI 兼容格式： text → text part、thinking → thinking part、 tool_use → tool call、tool_result → tool 消息， 图片与文档退化为 [image] / [document: name] 占位标记。

常用命令与参数

Langfuse 集成没有独立的 CLI 子命令，启用与调参完全依赖环境变量。相关「参数」为追踪 命名的行为约定与关键调用函数：

实战示例

写入用户级 settings.json 长期生效（受信任源，启动早期注入）：

{
  "env": {
    "LANGFUSE_PUBLIC_KEY": "pk-xxx",
    "LANGFUSE_SECRET_KEY": "sk-xxx",
    "LANGFUSE_BASE_URL": "https://cloud.langfuse.com",
    "LANGFUSE_TRACING_ENVIRONMENT": "production"
  }
}

即时模式（每个 span 立即发送，适合调试，吞吐略低）：

LANGFUSE_EXPORT_MODE=immediate qsdashi

自部署 Langfuse（Docker 方式仅供参考，实际部署请对照 Langfuse 官方文档）：

docker run -d \
  --name langfuse \
  -p 3000:3000 \
  -e DATABASE_URL=postgresql://... \
  langfuse/langfuse:latest

# 随后把 LANGFUSE_BASE_URL 指向该实例
LANGFUSE_BASE_URL=http://localhost:3000 qsdashi

常见问题排错