​

Langfuse 监控集成

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

​

一、功能概述

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

​

二、启用方式

​

通过 settings.json 配置（推荐）

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

​

其他可选参数

​

四、架构

​

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

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

​

5.2 子 Agent Trace

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

​

5.3 LLM Generation

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

​

5.4 工具执行

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

​

六、数据脱敏

​

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）

​

七、消息格式转换

• 输入: 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

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

​

十、相关文件