cs-note/claude-code-best/docs/features/langfuse-monitoring.md

tags, create time

tags	create time
Langfuse 监控 OTel 追踪 可观测性	2026-06-09 22:30

Langfuse 监控集成

概述

Langfuse 是一个开源的 LLM 可观测性平台，用于追踪、监控和调试 AI 应用的请求链路。CCB 通过 OpenTelemetry (OTel) 桥接层将 Langfuse 集成到查询流程中，实现 LLM 调用追踪、工具执行追踪、多 Agent 追踪和数据脱敏。

[!info] 实现状态：已完成，通过环境变量启用 依赖：@langfuse/otel、@langfuse/tracing、@opentelemetry/sdk-trace-base

正文

启用方式

Langfuse 是开源项目，你可以 自部署（Docker / Kubernetes），也可以使用官方提供的 Langfuse Cloud 免费测试。注册后在 Project Settings -> API Keys 页面获取密钥。

核心只需要三个环境变量：

环境变量	说明
LANGFUSE_PUBLIC_KEY	Langfuse 公钥（必填）
LANGFUSE_SECRET_KEY	Langfuse 密钥（必填）
LANGFUSE_BASE_URL	服务地址，默认 https://cloud.langfuse.com；自部署时改为你的地址（必填）

未配置时所有追踪函数为 no-op，零开销。

通过 settings.json 配置（推荐）

在 .claude/settings.json 的 env 字段中添加，这样每次启动自动生效：

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

其他可选参数

环境变量	默认值	说明
LANGFUSE_TRACING_ENVIRONMENT	development	环境标签，用于 Langfuse 面板筛选
LANGFUSE_FLUSH_AT	20	批量发送的 span 数量阈值
LANGFUSE_FLUSH_INTERVAL	10	定时刷新间隔（秒）
LANGFUSE_EXPORT_MODE	batched	导出模式：batched（批量）或 immediate（即时）
LANGFUSE_TIMEOUT	5	请求超时（秒）

架构

模块结构

src/services/langfuse/
├── index.ts          # 统一导出
├── client.ts         # OTel Provider + LangfuseSpanProcessor 初始化
├── tracing.ts        # Trace/Span 创建、LLM 和工具观察记录
├── convert.ts        # 内部 Message 类型 -> Langfuse OpenAI 兼容格式转换
└── sanitize.ts       # 数据脱敏（敏感字段、文件路径、工具输出）

追踪层级

Trace (Agent Span)                    <- createTrace() / createSubagentTrace()
  ├── Generation (LLM 调用)           <- recordLLMObservation()
  ├── Tool Observation (工具调用)      <- recordToolObservation()
  ├── Tool Observation (工具调用)      <- recordToolObservation()
  └── ...

数据流

flowchart TD
    A["query.ts"] --> B["createTrace() 每个 query turn 创建根 trace"]
    B --> C["claude.ts -> recordLLMObservation() API 调用完成后记录 LLM 观察"]
    B --> D["toolExecution.ts -> recordToolObservation() 每个工具执行记录"]
    B --> E["query.ts -> endTrace() turn 结束时关闭 trace"]
    F["runAgent.ts"] --> G["createSubagentTrace() 子 Agent 有独立 trace"]

追踪详情

主 Agent Trace

每次 query() 调用（即用户一次对话 turn）创建一个类型为 agent 的根 Span：

• 名称: agent-run 或 agent-run:<querySource>
• 元数据: provider、model、agentType: "main"
• Session ID: 关联到 Langfuse 的 Session 功能，支持按会话聚合

子 Agent Trace

通过 AgentTool 启动的子 Agent 创建独立 Trace：

• 名称: agent:<agentType>
• 元数据: provider、model、agentType、agentId
• 独立于主 Trace，有自己的 Session 关联

LLM Generation

每次 API 调用记录为一个 generation 类型的 Span：

• 名称: 按 Provider 映射（如 ChatAnthropic、ChatOpenAI、ChatBedrockAnthropic 等）
• 记录内容: 输入消息、输出消息、Token 用量（input/output）
• 时间: 精确记录 startTime、endTime、completionStartTime（TTFT 指标）

Provider 名称映射：

Provider	Generation 名称
firstParty	ChatAnthropic
bedrock	ChatBedrockAnthropic
vertex	ChatVertexAnthropic
foundry	ChatFoundry
openai	ChatOpenAI
gemini	ChatGoogleGenerativeAI
grok	ChatXAI

工具执行

每个工具调用记录为一个 tool 类型的 Span：

• 名称: 工具名（如 FileEditTool、BashTool）
• 记录内容: 输入（经脱敏）、输出（经脱敏）、toolUseId
• 错误标记: isError 标志 + level: ERROR

数据脱敏

所有上传到 Langfuse 的数据都会经过脱敏处理（sanitize.ts），确保敏感信息不会泄露：

全局脱敏（sanitizeGlobal）

• Home 路径替换 — /Users/xxx -> ~
• 敏感字段遮蔽 — 匹配 api_key、token、secret、password、credential、auth_header 等关键字的字段值替换为 [REDACTED]

工具输入脱敏（sanitizeToolInput）

• 敏感字段遮蔽（同全局）
• file_path、path、directory 路径中的 Home 目录替换

工具输出脱敏（sanitizeToolOutput）

工具	脱敏策略
FileReadTool、FileWriteTool、FileEditTool	完全遮蔽，仅保留字符数：[file content redacted, N chars]
BashTool、PowerShellTool	截断至 500 字符
ConfigTool、MCPTool	完全遮蔽
其他工具	原样保留

消息格式转换

convert.ts 将 CCB 内部的 Message 类型转换为 Langfuse 期望的 OpenAI 兼容格式：

• 输入: UserMessage | AssistantMessage[] + 可选 system prompt -> { role, content }[]
• 输出: AssistantMessage[] -> { role: 'assistant', content }
• Content Block 映射:
  • text -> { type: 'text', text }
  • thinking / redacted_thinking -> { type: 'thinking', thinking }
  • tool_use -> { type: 'tool_use', id, name, input }
  • tool_result -> { type: 'tool_result', tool_use_id, content }
  • image / document -> 占位标记 [image] / [document: name]

生命周期

1. 初始化 — initLangfuse() 在 src/entrypoints/init.ts 启动时调用，创建 LangfuseSpanProcessor 和 BasicTracerProvider
2. 运行时 — 各追踪函数通过 isLangfuseEnabled() 检查，未配置时直接返回 null/跳过
3. 关闭 — shutdownLangfuse() 在进程退出时调用，强制 flush 并关闭 Processor

自部署 Langfuse

Langfuse 是开源项目，支持 Docker / Kubernetes 自部署：

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

自部署后，将 LANGFUSE_BASE_URL 指向你的实例地址即可。详见 Langfuse 自部署文档。

如果没有自部署需求，可以直接使用 Langfuse Cloud，提供免费额度可用于测试。

相关文件

文件	说明
src/services/langfuse/client.ts	OTel Provider 初始化、生命周期管理
src/services/langfuse/tracing.ts	Trace/Span 创建和观察记录
src/services/langfuse/convert.ts	Message 格式转换
src/services/langfuse/sanitize.ts	数据脱敏
src/services/langfuse/__tests__/langfuse.test.ts	测试（568 行）
src/query.ts	主查询流程中的 Trace 集成
src/services/tools/toolExecution.ts	工具执行中的观察记录
packages/builtin-tools/src/tools/AgentTool/runAgent.ts	子 Agent Trace 创建

关联笔记

• claude-code-best/docs/features/kairos