langfuse

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Langfuse Skill

Langfuse 技能

Debug your AI systems through Langfuse observability.

Triggers: langfuse, traces, debug AI, find exceptions, set up langfuse, what went wrong, why is it slow, datasets, evaluation sets

通过Langfuse可观测性工具调试你的AI系统。

触发词： langfuse、traces、调试AI、排查异常、设置langfuse、哪里出问题了、为什么这么慢、数据集、评估集

Setup

安装配置

Step 1: Get credentials from https://cloud.langfuse.com → Settings → API Keys

If self-hosted, use your instance URL for

LANGFUSE_HOST

and create keys there.

Step 2: Install MCP (pick one):

bash

undefined

步骤1： 从https://cloud.langfuse.com → 设置 → API密钥获取凭证

如果是自托管部署，请将你的实例URL作为

LANGFUSE_HOST

，并在该实例中创建密钥。

步骤2： 安装MCP（选择其中一种方式）：

bash

undefined

Claude Code (project-scoped, shared via .mcp.json)

Claude Code（项目级范围，通过.mcp.json共享）

claude mcp add
--scope project
--env LANGFUSE_PUBLIC_KEY=pk-...
--env LANGFUSE_SECRET_KEY=sk-...
--env LANGFUSE_HOST=https://cloud.langfuse.com
langfuse -- uvx --python 3.11 langfuse-mcp

Codex CLI (user-scoped, stored in ~/.codex/config.toml)

Codex CLI（用户级范围，存储在~/.codex/config.toml）

codex mcp add langfuse
--env LANGFUSE_PUBLIC_KEY=pk-...
--env LANGFUSE_SECRET_KEY=sk-...
--env LANGFUSE_HOST=https://cloud.langfuse.com
-- uvx --python 3.11 langfuse-mcp


**Step 3:** Restart CLI, verify with `/mcp` (Claude) or `codex mcp list` (Codex)

**Step 4:** Test: `fetch_traces(age=60)`

codex mcp add langfuse
--env LANGFUSE_PUBLIC_KEY=pk-...
--env LANGFUSE_SECRET_KEY=sk-...
--env LANGFUSE_HOST=https://cloud.langfuse.com
-- uvx --python 3.11 langfuse-mcp


**步骤3：** 重启CLI，通过`/mcp`（Claude）或`codex mcp list`（Codex）验证安装。

**步骤4：** 测试：`fetch_traces(age=60)`

Read-Only Mode

只读模式

For safer observability without risk of modifying prompts or datasets, enable read-only mode:

bash

undefined

为了更安全的可观测性，避免修改提示词或数据集的风险，可启用只读模式：

bash

undefined

CLI flag

CLI 标志

langfuse-mcp --read-only

Or environment variable

或环境变量

LANGFUSE_MCP_READ_ONLY=true


This disables write tools: `create_text_prompt`, `create_chat_prompt`, `update_prompt_labels`, `create_dataset`, `create_dataset_item`, `delete_dataset_item`.

For manual `.mcp.json` setup or troubleshooting, see `references/setup.md`.

---

LANGFUSE_MCP_READ_ONLY=true


这会禁用写入类工具：`create_text_prompt`、`create_chat_prompt`、`update_prompt_labels`、`create_dataset`、`create_dataset_item`、`delete_dataset_item`。

如需手动配置`.mcp.json`或排查问题，请查看`references/setup.md`。

---

Playbooks

操作指南

"Where are the errors?"

「错误在哪里？」

find_exceptions(age=1440, group_by="file")

→ Shows error counts by file. Pick the worst offender.

find_exceptions_in_file(filepath="src/ai/chat.py", age=1440)

→ Lists specific exceptions. Grab a trace_id.

get_exception_details(trace_id="...")

→ Full stacktrace and context.

find_exceptions(age=1440, group_by="file")

→ 按文件展示错误数量。选择错误最严重的文件。

find_exceptions_in_file(filepath="src/ai/chat.py", age=1440)

→ 列出具体异常信息。记录对应的trace_id。

get_exception_details(trace_id="...")

→ 查看完整堆栈跟踪和上下文信息。

"What happened in this interaction?"

「这次交互发生了什么？」

fetch_traces(age=60, user_id="...")

→ Find the trace. Note the trace_id.

If you don't know the user_id, start with:

fetch_traces(age=60)

fetch_trace(trace_id="...", include_observations=true)

→ See all LLM calls in the trace.

fetch_observation(observation_id="...")

→ Inspect a specific generation's input/output.

fetch_traces(age=60, user_id="...")

→ 找到对应的追踪记录。记录trace_id。

如果不知道user_id，先执行：

fetch_traces(age=60)

fetch_trace(trace_id="...", include_observations=true)

→ 查看该追踪记录中的所有LLM调用。

fetch_observation(observation_id="...")

→ 检查特定生成结果的输入/输出。

"Why is it slow?"

「为什么这么慢？」

fetch_observations(age=60, type="GENERATION")

→ Find recent LLM calls. Look for high latency.

fetch_observation(observation_id="...")

→ Check token counts, model, timing.

fetch_observations(age=60, type="GENERATION")

→ 找到最近的LLM调用，查看高延迟的请求。

fetch_observation(observation_id="...")

→ 检查令牌数量、模型类型、耗时信息。

"What's this user experiencing?"

「这个用户的体验如何？」

get_user_sessions(user_id="...", age=1440)

→ List their sessions.

get_session_details(session_id="...")

→ See all traces in the session.

get_user_sessions(user_id="...", age=1440)

→ 列出该用户的所有会话。

get_session_details(session_id="...")

→ 查看该会话中的所有追踪记录。

"Manage datasets"

「管理数据集」

list_datasets()

→ See all datasets.

get_dataset(name="evaluation-set-v1")

→ Get dataset details.

list_dataset_items(dataset_name="evaluation-set-v1", page=1, limit=10)

→ Browse items in the dataset.

create_dataset(name="qa-test-cases", description="QA evaluation set")

→ Create a new dataset.

create_dataset_item(
  dataset_name="qa-test-cases",
  input={"question": "What is 2+2?"},
  expected_output={"answer": "4"}
)

→ Add test cases.

create_dataset_item(
  dataset_name="qa-test-cases",
  item_id="item_123",
  input={"question": "What is 3+3?"},
  expected_output={"answer": "6"}
)

→ Upsert: updates existing item by id or creates if missing.

list_datasets()

→ 查看所有数据集。

get_dataset(name="evaluation-set-v1")

→ 获取数据集详情。

list_dataset_items(dataset_name="evaluation-set-v1", page=1, limit=10)

→ 浏览数据集中的条目。

create_dataset(name="qa-test-cases", description="QA evaluation set")

→ 创建新数据集。

create_dataset_item(
  dataset_name="qa-test-cases",
  input={"question": "What is 2+2?"},
  expected_output={"answer": "4"}
)

→ 添加测试用例。

create_dataset_item(
  dataset_name="qa-test-cases",
  item_id="item_123",
  input={"question": "What is 3+3?"},
  expected_output={"answer": "6"}
)

→ 插入或更新：根据item_id更新现有条目，不存在则创建。

"Manage prompts"

「管理提示词」

list_prompts()

→ See all prompts with labels.

get_prompt(name="...", label="production")

→ Fetch current production version.

create_text_prompt(name="...", prompt="...", labels=["staging"])

→ Create new version in staging.

update_prompt_labels(name="...", version=N, labels=["production"])

→ Promote to production. (Rollback = re-apply label to older version)

list_prompts()

→ 查看所有带标签的提示词。

get_prompt(name="...", label="production")

→ 获取当前生产环境版本的提示词。

create_text_prompt(name="...", prompt="...", labels=["staging"])

→ 在预发布环境创建新版本。

update_prompt_labels(name="...", version=N, labels=["production"])

→ 升级到生产环境。（回滚操作 = 将标签重新应用到旧版本）

Quick Reference

快速参考

Task	Tool
List traces	`fetch_traces(age=N)`
Get trace details	`fetch_trace(trace_id="...", include_observations=true)`
List LLM calls	`fetch_observations(age=N, type="GENERATION")`
Get observation	`fetch_observation(observation_id="...")`
Error count	`get_error_count(age=N)`
Find exceptions	`find_exceptions(age=N, group_by="file")`
List sessions	`fetch_sessions(age=N)`
User sessions	`get_user_sessions(user_id="...", age=N)`
List prompts	`list_prompts()`
Get prompt	`get_prompt(name="...", label="production")`
List datasets	`list_datasets()`
Get dataset	`get_dataset(name="...")`
List dataset items	`list_dataset_items(dataset_name="...", limit=N)`
Create/update dataset item	`create_dataset_item(dataset_name="...", item_id="...")`

age

= minutes to look back (max 10080 = 7 days)

任务	工具
列出追踪记录	`fetch_traces(age=N)`
获取追踪详情	`fetch_trace(trace_id="...", include_observations=true)`
列出LLM调用	`fetch_observations(age=N, type="GENERATION")`
获取观测详情	`fetch_observation(observation_id="...")`
错误统计	`get_error_count(age=N)`
排查异常	`find_exceptions(age=N, group_by="file")`
列出会话	`fetch_sessions(age=N)`
用户会话	`get_user_sessions(user_id="...", age=N)`
列出提示词	`list_prompts()`
获取提示词	`get_prompt(name="...", label="production")`
列出数据集	`list_datasets()`
获取数据集	`get_dataset(name="...")`
列出数据集条目	`list_dataset_items(dataset_name="...", limit=N)`
创建/更新数据集条目	`create_dataset_item(dataset_name="...", item_id="...")`

age

= 回溯的分钟数（最大10080 = 7天）

References

参考资料

```
references/tool-reference.md
```
— Full parameter docs, filter semantics, response schemas
```
references/setup.md
```
— Manual setup, troubleshooting, advanced configuration

```
references/tool-reference.md
```
— 完整参数文档、过滤规则、响应格式
```
references/setup.md
```
— 手动配置、故障排查、高级设置