vault backup: 2026-06-09 23:15:17
This commit is contained in:
@@ -1,20 +1,23 @@
|
||||
---
|
||||
tags: [Langfuse, 监控, OTel, 追踪, 可观测性]
|
||||
create time: 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 是一个开源的 LLM 可观测性平台，用于追踪、监控和调试 AI 应用的请求链路。CCB 通过 OpenTelemetry (OTel) 桥接层将 Langfuse 集成到查询流程中，实现：
|
||||
### 启用方式
|
||||
|
||||
- **LLM 调用追踪** — 记录每次 API 请求的模型、Provider、输入/输出、Token 用量
|
||||
- **工具执行追踪** — 记录每个工具调用的名称、输入、输出、耗时和错误
|
||||
- **多 Agent 追踪** — 主 Agent 和子 Agent 各自独立的 Trace 链路
|
||||
- **数据脱敏** — 自动遮蔽敏感信息（API Key、文件内容、Shell 输出等）
|
||||
|
||||
## 二、启用方式
|
||||
|
||||
Langfuse 是开源项目，你可以 **自部署**（Docker / Kubernetes），也可以使用官方提供的 **[Langfuse Cloud](https://cloud.langfuse.com)** 免费测试。注册后在 Project Settings → API Keys 页面获取密钥。
|
||||
Langfuse 是开源项目，你可以 **自部署**（Docker / Kubernetes），也可以使用官方提供的 **Langfuse Cloud** 免费测试。注册后在 Project Settings -> API Keys 页面获取密钥。
|
||||
|
||||
核心只需要三个环境变量：
|
||||
|
||||
@@ -26,7 +29,7 @@ Langfuse 是开源项目，你可以 **自部署**（Docker / Kubernetes），
|
||||
|
||||
未配置时所有追踪函数为 no-op，零开销。
|
||||
|
||||
### 通过 settings.json 配置（推荐）
|
||||
#### 通过 settings.json 配置（推荐）
|
||||
|
||||
在 `.claude/settings.json` 的 `env` 字段中添加，这样每次启动自动生效：
|
||||
|
||||
@@ -40,7 +43,7 @@ Langfuse 是开源项目，你可以 **自部署**（Docker / Kubernetes），
|
||||
}
|
||||
```
|
||||
|
||||
### 其他可选参数
|
||||
#### 其他可选参数
|
||||
|
||||
| 环境变量 | 默认值 | 说明 |
|
||||
|---------|--------|------|
|
||||
@@ -50,46 +53,43 @@ Langfuse 是开源项目，你可以 **自部署**（Docker / Kubernetes），
|
||||
| `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 兼容格式转换
|
||||
├── convert.ts # 内部 Message 类型 -> Langfuse OpenAI 兼容格式转换
|
||||
└── sanitize.ts # 数据脱敏（敏感字段、文件路径、工具输出）
|
||||
```
|
||||
|
||||
### 4.2 追踪层级
|
||||
#### 追踪层级
|
||||
|
||||
```
|
||||
Trace (Agent Span) ← createTrace() / createSubagentTrace()
|
||||
├── Generation (LLM 调用) ← recordLLMObservation()
|
||||
├── Tool Observation (工具调用) ← recordToolObservation()
|
||||
├── Tool Observation (工具调用) ← recordToolObservation()
|
||||
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
|
||||
```mermaid
|
||||
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"]
|
||||
```
|
||||
|
||||
## 五、追踪详情
|
||||
### 追踪详情
|
||||
|
||||
### 5.1 主 Agent Trace
|
||||
#### 主 Agent Trace
|
||||
|
||||
每次 `query()` 调用（即用户一次对话 turn）创建一个类型为 `agent` 的根 Span：
|
||||
|
||||
@@ -97,7 +97,7 @@ runAgent.ts ──→ createSubagentTrace() # 子 Agent 有独立 trace
|
||||
- **元数据**: `provider`、`model`、`agentType: "main"`
|
||||
- **Session ID**: 关联到 Langfuse 的 Session 功能，支持按会话聚合
|
||||
|
||||
### 5.2 子 Agent Trace
|
||||
#### 子 Agent Trace
|
||||
|
||||
通过 `AgentTool` 启动的子 Agent 创建独立 Trace：
|
||||
|
||||
@@ -105,7 +105,7 @@ runAgent.ts ──→ createSubagentTrace() # 子 Agent 有独立 trace
|
||||
- **元数据**: `provider`、`model`、`agentType`、`agentId`
|
||||
- 独立于主 Trace，有自己的 Session 关联
|
||||
|
||||
### 5.3 LLM Generation
|
||||
#### LLM Generation
|
||||
|
||||
每次 API 调用记录为一个 `generation` 类型的 Span：
|
||||
|
||||
@@ -125,7 +125,7 @@ Provider 名称映射：
|
||||
| `gemini` | `ChatGoogleGenerativeAI` |
|
||||
| `grok` | `ChatXAI` |
|
||||
|
||||
### 5.4 工具执行
|
||||
#### 工具执行
|
||||
|
||||
每个工具调用记录为一个 `tool` 类型的 Span：
|
||||
|
||||
@@ -133,21 +133,21 @@ Provider 名称映射：
|
||||
- **记录内容**: 输入（经脱敏）、输出（经脱敏）、`toolUseId`
|
||||
- **错误标记**: `isError` 标志 + `level: ERROR`
|
||||
|
||||
## 六、数据脱敏
|
||||
### 数据脱敏
|
||||
|
||||
所有上传到 Langfuse 的数据都会经过脱敏处理（`sanitize.ts`），确保敏感信息不会泄露：
|
||||
|
||||
### 6.1 全局脱敏（`sanitizeGlobal`）
|
||||
#### 全局脱敏（`sanitizeGlobal`）
|
||||
|
||||
- **Home 路径替换** — `/Users/xxx` → `~`
|
||||
- **Home 路径替换** — `/Users/xxx` -> `~`
|
||||
- **敏感字段遮蔽** — 匹配 `api_key`、`token`、`secret`、`password`、`credential`、`auth_header` 等关键字的字段值替换为 `[REDACTED]`
|
||||
|
||||
### 6.2 工具输入脱敏（`sanitizeToolInput`）
|
||||
#### 工具输入脱敏（`sanitizeToolInput`）
|
||||
|
||||
- 敏感字段遮蔽（同全局）
|
||||
- `file_path`、`path`、`directory` 路径中的 Home 目录替换
|
||||
|
||||
### 6.3 工具输出脱敏（`sanitizeToolOutput`）
|
||||
#### 工具输出脱敏（`sanitizeToolOutput`）
|
||||
|
||||
| 工具 | 脱敏策略 |
|
||||
|------|---------|
|
||||
@@ -156,26 +156,26 @@ Provider 名称映射：
|
||||
| `ConfigTool`、`MCPTool` | 完全遮蔽 |
|
||||
| 其他工具 | 原样保留 |
|
||||
|
||||
## 七、消息格式转换
|
||||
### 消息格式转换
|
||||
|
||||
`convert.ts` 将 CCB 内部的 Message 类型转换为 Langfuse 期望的 OpenAI 兼容格式：
|
||||
|
||||
- **输入**: `UserMessage | AssistantMessage[]` + 可选 system prompt → `{ role, content }[]`
|
||||
- **输出**: `AssistantMessage[]` → `{ role: 'assistant', content }`
|
||||
- **输入**: `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]`
|
||||
- `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
|
||||
|
||||
Langfuse 是开源项目，支持 Docker / Kubernetes 自部署：
|
||||
|
||||
@@ -191,7 +191,7 @@ docker run -d \
|
||||
|
||||
如果没有自部署需求，可以直接使用 [Langfuse Cloud](https://cloud.langfuse.com)，提供免费额度可用于测试。
|
||||
|
||||
## 十、相关文件
|
||||
### 相关文件
|
||||
|
||||
| 文件 | 说明 |
|
||||
|------|------|
|
||||
@@ -203,3 +203,7 @@ docker run -d \
|
||||
| `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]]
|
||||
|
||||
Reference in New Issue
Block a user