Langfuse 是开源 LLM 工程平台，专注于 trace 调试、prompt 迭代和质量评估。通过 OpenRouter Broadcast，每次 LLM 请求都会作为 trace 发送到 Langfuse，包含完整的输入/输出、token 用量、费用和延迟。配置需要 Langfuse 项目的 Secret Key 和 Public Key（在 Settings > API Keys 获取）。支持多区域和自托管实例（通过 Base URL 配置）。通过 trace_id、span_name、generation_name、parent_span_id 字段可构建多层级的 trace 层级结构，user 和 session_id 映射到 Langfuse 的用户级和会话级分析。

Langfuse 是开源 LLM 工程平台，帮助开发者追踪、评估和调试 LLM 应用。通过 OpenRouter Broadcast，每次 API 请求都会作为 trace 自动发送到 Langfuse，无需在应用中集成 Langfuse SDK。

配置步骤

第一步：创建 Langfuse API Key

1. 登录 Langfuse 账号
2. 进入项目 Settings > API Keys
3. 创建新的 API Key Pair
4. 复制 Secret Key 和 Public Key（两者都需要）

第二步：在 OpenRouter 开启 Broadcast

前往 Settings > Observability，打开 Enable Broadcast 开关。

第三步：配置 Langfuse

点击 Langfuse 旁边的编辑图标，填写：

字段	填写内容
Secret Key	Langfuse Secret Key
Public Key	Langfuse Public Key
Base URL（可选）	默认 https://us.cloud.langfuse.com；EU 区域用 https://eu.cloud.langfuse.com；自托管实例填写你的域名

第四步：测试并保存

点击 Test Connection 验证配置，测试通过后自动保存。

第五步：查看 LLM Trace

通过 OpenRouter 发送 API 请求，在 Langfuse 的 Traces 视图中查看追踪数据，包括完整的层级 span 结构。

元数据映射

Langfuse 支持丰富的 trace 层级结构，通过 trace 字段可精细控制：

键	Langfuse 映射	说明
trace_id	Trace ID	将多个请求归入同一 trace，追踪多步骤工作流
trace_name	Trace Name	trace 列表中显示的自定义名称
span_name	Span Name	中间 span 的名称，建立层级结构
generation_name	Generation Name	LLM 生成观测（observation）的名称
parent_span_id	Parent Observation ID	链接到已有 span，实现 trace 嵌套

其他字段映射：

• user → Langfuse User ID（用于用户级分析）
• session_id → Langfuse Session ID（用于会话分组）
• trace 中的自定义键 → trace 元数据（可用于过滤和分析）

示例：多步骤文档处理工作流

{
  "model": "openai/gpt-4o",
  "messages": [{ "role": "user", "content": "Summarize this document..." }],
  "user": "user_12345",
  "session_id": "session_abc",
  "trace": {
    "trace_id": "workflow_12345",
    "trace_name": "Document Processing Pipeline",
    "span_name": "Summarization Step",
    "generation_name": "Generate Summary",
    "environment": "production",
    "pipeline_version": "2.1.0"
  }
}

上例会在 Langfuse 中创建如下层级 trace 结构：

Document Processing Pipeline (trace)
  └── Summarization Step (span)
        └── Generate Summary (generation)

Privacy Mode

当为此目的地开启 Privacy Mode 时，prompt 和 completion 内容会从 trace 中排除。其他 trace 数据（token 用量、费用、时间、模型信息）仍正常发送。

常见问题

Q: Langfuse 和 PostHog 都有 LLM 追踪，选哪个？

A: 工程团队优先选 Langfuse：它专注于 prompt 调试、版本对比（prompt 版本管理）、评估（Evals）和质量打分，有专门的 LLM 调试工具链。产品团队优先选 PostHog：它将 LLM 用量与用户行为漏斗、A/B 测试、留存分析结合。两者定位不同，可同时配置，各司其职。

Q: 如何在 Langfuse 中追踪多轮对话？

A: 为同一对话的所有请求传入相同的 session_id，Langfuse 会自动将它们归入同一 Session 视图。如果需要将多个相关请求归为一条 trace，使用相同的 trace_id。

Q: 如何使用自托管的 Langfuse 实例？

A: 在 Base URL 字段填入你的自托管 Langfuse 域名（如 https://langfuse.your-domain.com），其余配置与云端版相同。确保你的服务器可以从 OpenRouter 的出站 IP 接收到 OTLP 请求。