Langfuse 监控集成

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

一、功能概述

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

LLM 调用追踪 — 记录每次 API 请求的模型、Provider、输入/输出、Token 用量
工具执行追踪 — 记录每个工具调用的名称、输入、输出、耗时和错误
多 Agent 追踪 — 主 Agent 和子 Agent 各自独立的 Trace 链路
数据脱敏 — 自动遮蔽敏感信息（API Key、文件内容、Shell 输出等）

二、启用方式

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`	请求超时（秒）

四、架构

4.1 模块结构

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

4.2 追踪层级

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

4.3 数据流

query.ts  ──→  createTrace()           # 每个 query turn 创建根 trace
  │
  ├── claude.ts  ──→  recordLLMObservation()   # API 调用完成后记录 LLM 观察
  │
  ├── toolExecution.ts  ──→  recordToolObservation()  # 每个工具执行记录
  │
  └── query.ts  ──→  endTrace()         # turn 结束时关闭 trace

runAgent.ts  ──→  createSubagentTrace()  # 子 Agent 有独立 trace

五、追踪详情

5.1 主 Agent Trace

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

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

5.2 子 Agent Trace

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

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

5.3 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`

5.4 工具执行

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

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

六、数据脱敏

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

6.1 全局脱敏（`sanitizeGlobal`）

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

6.2 工具输入脱敏（`sanitizeToolInput`）

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

6.3 工具输出脱敏（`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]

八、生命周期

初始化 — initLangfuse() 在 src/entrypoints/init.ts 启动时调用，创建 LangfuseSpanProcessor 和 BasicTracerProvider
运行时 — 各追踪函数通过 isLangfuseEnabled() 检查，未配置时直接返回 null/跳过
关闭 — 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 创建

开始

对话是如何运转的

工具：AI 的双手

上下文工程

多 Agent 协作

可扩展性

安全与权限

揭秘：隐藏功能与内部机制

隐藏功能详解

基础设施与依赖

Langfuse monitoring

Langfuse 监控集成

一、功能概述

二、启用方式

通过 settings.json 配置（推荐）

其他可选参数

四、架构

4.1 模块结构

4.2 追踪层级

4.3 数据流

五、追踪详情

5.1 主 Agent Trace

5.2 子 Agent Trace

5.3 LLM Generation

5.4 工具执行

六、数据脱敏

6.1 全局脱敏（`sanitizeGlobal`）

6.2 工具输入脱敏（`sanitizeToolInput`）

6.3 工具输出脱敏（`sanitizeToolOutput`）

七、消息格式转换

八、生命周期

九、自部署 Langfuse

十、相关文件

​Langfuse 监控集成

​一、功能概述

​二、启用方式

​通过 settings.json 配置（推荐）

​其他可选参数

​四、架构

​4.1 模块结构

​4.2 追踪层级

​4.3 数据流

​五、追踪详情

​5.1 主 Agent Trace

​5.2 子 Agent Trace

​5.3 LLM Generation

​5.4 工具执行

​六、数据脱敏

​6.1 全局脱敏（sanitizeGlobal）

​6.2 工具输入脱敏（sanitizeToolInput）

​6.3 工具输出脱敏（sanitizeToolOutput）

​七、消息格式转换

​八、生命周期

​九、自部署 Langfuse

​十、相关文件

Langfuse 监控集成

一、功能概述

二、启用方式

通过 settings.json 配置（推荐）

其他可选参数

四、架构

4.1 模块结构

4.2 追踪层级

4.3 数据流

五、追踪详情

5.1 主 Agent Trace

5.2 子 Agent Trace

5.3 LLM Generation

5.4 工具执行

六、数据脱敏

6.1 全局脱敏（`sanitizeGlobal`）

6.2 工具输入脱敏（`sanitizeToolInput`）

6.3 工具输出脱敏（`sanitizeToolOutput`）

七、消息格式转换

八、生命周期

九、自部署 Langfuse

十、相关文件