Langfuse and LLM Gateway Logs

What it does

When your agent uses it

• Inspecting a Langfuse trace or session to find where a run went wrong
• Comparing requests and context growth in local LLM gateway logs
• Checking token usage and prompt cache hit rates
• Looking up Langfuse SDK usage or API resources

Example prompts

• “List the latest Langfuse traces for this project and find the ones with errors.”
• “Analyze the gateway logs in logs/session-a and show how the context grows across requests.”
• “Why is our cache hit rate low? Break down the prompt in the last few requests.”
• “Create a daily report from Langfuse for yesterday's sessions.”

Requirements

• bun, to run langfuse-cli and the bundled scripts
• Langfuse API keys and host in a .env file for the remote route
• Local gateway log files for the offline route
• Pre-approved tools (allowed-tools): WebFetch(domain:langfuse.com), Bash(curl *langfuse.com/*), Bash(bunx langfuse-cli api --help *), Bash(bunx langfuse-cli api * --help *), Bash(bunx langfuse-cli api * list *), Bash(bunx langfuse-cli api * get *), Bash(bun .claude/skills/langfuse/scripts/analyze.ts *), Bash(bun .claude/skills/langfuse/scripts/trace-search.ts *), Bash(bun .claude/skills/langfuse/scripts/trace-tree.ts *), Bash(bun .claude/skills/langfuse/scripts/trace-tokens.ts *), Bash(bun .claude/skills/langfuse/scripts/trace-messages.ts *), Bash(bun .claude/skills/langfuse/scripts/prompt-breakdown.ts *), Bash(bun .claude/skills/langfuse/scripts/traces-list.ts *), Bash(bun .claude/skills/langfuse/scripts/session-analyze.ts *), Bash(bun .claude/skills/langfuse/scripts/daily-report.ts *), Bash(bun .claude/skills/langfuse/scripts/llm-log-query.mjs *), Bash(bun .claude/skills/langfuse/scripts/context-growth.mjs *)

Workflow steps

7 steps, taken from the step headings in SKILL.md.

1. 1Langfuse API via CLI
2. 2Data Retrieval Tools (脚本工具集)
3. 3Query Recipes（常见数据获取场景）
4. 4Data Retrieval Patterns（按目的选择工具）
5. 5Cost Analysis（详细版）
6. 6Langfuse Documentation
7. 7上下文 Diff 诊断（对比两次 LLM 调用的完整输入）

What it can do on your machine

Read from SKILL.md and the folder at commit d7ee444. It shows what the files ask for, not the result of running them.

• Tool permissions

  Pre-approves these tools, so the agent can use them without asking each time:

  • WebFetch(domain:langfuse.com)
  • Bash(curl *langfuse.com/*)
  • Bash(bunx langfuse-cli api --help *)
  • Bash(bunx langfuse-cli api * --help *)
  • Bash(bunx langfuse-cli api * list *)
  • Bash(bunx langfuse-cli api * get *)
  • Bash(bun .claude/skills/langfuse/scripts/analyze.ts *)
  • Bash(bun .claude/skills/langfuse/scripts/trace-search.ts *)
  • Bash(bun .claude/skills/langfuse/scripts/trace-tree.ts *)
  • Bash(bun .claude/skills/langfuse/scripts/trace-tokens.ts *)

  …and 7 more on the same allowed-tools line.

  From allowed-tools in the SKILL.md frontmatter.

• Runs code

  Ships 9 files in scripts/ (TypeScript and JavaScript, from the files we listed), which the agent can run.

  Shell commands in SKILL.md call:

  • bun
  • bunx
  • curl
  • jq

  From the folder's file list and the shell code blocks in SKILL.md.

• Network

  Hosts in commands or code, which the agent is likely to contact:

  • langfuse.com
  • cloud.langfuse.com

  From URLs in SKILL.md, links to its own repository left out.

• Credentials

  Names these keys or tokens, usually read from environment variables:

  • LANGFUSE_PUBLIC_KEY
  • LANGFUSE_SECRET_KEY

  From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Langfuse and LLM Gateway Logs loads about 4.3k tokens when it runs, and up to ~19k if it reads all its reference files. Until then it costs about 53 tokens; SKILL.md has 1,192 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it

~53

When it runs · the whole SKILL.md, loaded when a task matches

~4.3k

With references · SKILL.md plus every file in references/, read only if the agent opens them

~19k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

• NoteMentions a .env fileSKILL.md:40

  fuse REST API. Run via bunx (auto-loads `.env`):

• NoteMentions a .env fileSKILL.md:51

  bunx automatically loads `.env`. Ensure it contains:

• NoteMentions a .env fileSKILL.md:59

  re missing, ask the user to add them to `.env`. Do not ask to paste keys in chat.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); the scripts in this folder are not scanned.

SKILL.md

The full file from KonghaYao/peri at commit d7ee444, republished under its Apache-2.0 licence (© KonghaYao). 1,192 words, ~4,308 tokens.

name

langfuse

description

查询或操作 Langfuse traces、prompts、datasets、scores、sessions，查阅 Langfuse 文档与 SDK 用法；也用于分析本地 llm-gateway 请求/响应日志、查看 LLM 请求、追踪 session、对比上下文、排查 token 用量及缓存命中率。根据数据来源选择 Langfuse API 或本地网关日志脚本；本地分析无需 Langfuse 凭据。

allowed-tools

WebFetch(domain:langfuse.com), Bash(curl *langfuse.com/*), Bash(bunx langfuse-cli api --help *), Bash(bunx langfuse-cli api * --help *), Bash(bunx langfuse-cli api * list *), Bash(bunx langfuse-cli api * get *), Bash(bun .claude/skills/langfuse/scripts/analyze.ts *), Bash(bun .claude/skills/langfuse/scripts/trace-search.ts *), Bash(bun .claude/skills/langfuse/scripts/trace-tree.ts *), Bash(bun .claude/skills/langfuse/scripts/trace-tokens.ts *), Bash(bun .claude/skills/langfuse/scripts/trace-messages.ts *), Bash(bun .claude/skills/langfuse/scripts/prompt-breakdown.ts *), Bash(bun .claude/skills/langfuse/scripts/traces-list.ts *), Bash(bun .claude/skills/langfuse/scripts/session-analyze.ts *), Bash(bun .claude/skills/langfuse/scripts/daily-report.ts *), Bash(bun .claude/skills/langfuse/scripts/llm-log-query.mjs *), Bash(bun .claude/skills/langfuse/scripts/context-growth.mjs *)

bunx langfuse-cli api --help                              # 列出所有 resources
bunx langfuse-cli api <resource> --help                     # List actions for a resource
bunx langfuse-cli api <resource> <action> --help            # Show args for an action
bunx langfuse-cli api <resource> <action> [options]         # Execute

LANGFUSE_PUBLIC_KEY=pk-lf-...
LANGFUSE_SECRET_KEY=sk-lf-...
LANGFUSE_HOST=https://cloud.langfuse.com  # Required

bun .claude/skills/langfuse/scripts/trace-search.ts [选项]

# 示例
bun .claude/skills/langfuse/scripts/trace-search.ts --days 7 --tag production                # 最近 7 天带 production tag 的 trace
bun .claude/skills/langfuse/scripts/trace-search.ts --session sess_abc --csv > session.csv   # 导出 session 为 CSV
bun .claude/skills/langfuse/scripts/trace-search.ts --model claude-sonnet --status error     # 查询特定模型的错误 trace
bun .claude/skills/langfuse/scripts/trace-search.ts --from 2026-07-01T00:00:00Z --summary   # 只看汇总统计
bun .claude/skills/langfuse/scripts/trace-search.ts --days 30 --json > report.json           # 导出 JSON
bun .claude/skills/langfuse/scripts/trace-search.ts --user user_123 --limit 100              # 按用户过滤
bun .claude/skills/langfuse/scripts/trace-search.ts --order latency.desc --limit 10          # 按延迟排序，找最慢的

bun .claude/skills/langfuse/scripts/analyze.ts [N]              # Overview + trace table + flags
bun .claude/skills/langfuse/scripts/analyze.ts --tools [N]      # Tool call analysis
bun .claude/skills/langfuse/scripts/analyze.ts --growth [N]     # Context growth trend
bun .claude/skills/langfuse/scripts/analyze.ts --report [N]     # Full report (all 7 sections)
bun .claude/skills/langfuse/scripts/analyze.ts --trace-id <id>  # Single trace detail

# 支持时间/元数据过滤
bun .claude/skills/langfuse/scripts/analyze.ts 20 --days 7 --user user_123 --report         # 某用户最近 7 天的完整报告

bun .claude/skills/langfuse/scripts/session-analyze.ts --session <id> [选项]

# 选项
--limit <N>    最多拉取 trace 数（默认 100）
--detail       显示每个 trace 的逐轮 token 流
--csv          导出 CSV（每个 LLM 调用一行）

# 输出内容
# - Session 总体指标（traces, tokens, cost, time span）
# - Trace 时间线表格
# - 累积 token 增长趋势
# - 工具使用频率统计
# - 异常检测

bun .claude/skills/langfuse/scripts/daily-report.ts [选项]

bun .claude/skills/langfuse/scripts/daily-report.ts                           # 今天的日报
bun .claude/skills/langfuse/scripts/daily-report.ts --days 7                  # 最近 7 天周报
bun .claude/skills/langfuse/scripts/daily-report.ts --days 30 --tag prod      # 按 tag 过滤的月报
bun .claude/skills/langfuse/scripts/daily-report.ts --model claude-sonnet     # 按模型过滤
bun .claude/skills/langfuse/scripts/daily-report.ts --detail                  # 显示所有 trace 详情

# 输出内容
# - Key Metrics（traces, sessions, errors, tokens, cost）
# - By Model 分布
# - Top Users（按输入 token）
# - Top Traces（按输入 token）
# - 异常 trace 列表

# Token 流 + 缓存异常
bun .claude/skills/langfuse/scripts/trace-tokens.ts <traceId>
bun .claude/skills/langfuse/scripts/trace-tokens.ts --index 1 --days 7        # 用 --index 从过滤结果中选 trace

# 消息组成 + diff
bun .claude/skills/langfuse/scripts/trace-messages.ts <traceId> [--detail]
bun .claude/skills/langfuse/scripts/trace-messages.ts --index 3 --user user_123

# System prompt 段落拆解
bun .claude/skills/langfuse/scripts/prompt-breakdown.ts <traceId>
bun .claude/skills/langfuse/scripts/prompt-breakdown.ts --index 1 --days 7

# Trace 汇总列表
bun .claude/skills/langfuse/scripts/traces-list.ts [N] [过滤选项]

bun .claude/skills/langfuse/scripts/trace-tree.ts <traceId>

bunx langfuse-cli api prompts list
bunx langfuse-cli api prompts get --name <name>
bunx langfuse-cli api prompts create --name <name> --type chat --prompt '[...]'

## Cost Reflection

### Metrics
- Traces analyzed: N
- Total input: X tokens (Y% cache hit)
- Total output: Z tokens
- Avg LLM calls per trace: M

### Findings
1. [Pattern with specific trace example]
2. [Another pattern]

### Recommendations
1. [Actionable optimization] — estimated savings: ~X tokens/trace
2. [Another recommendation]

curl -s https://langfuse.com/llms.txt

curl -s "https://langfuse.com/docs/observability/overview.md"

curl -s "https://langfuse.com/api/search-docs?query=How+do+I+trace+LangGraph+agents"

# 列出 session 的所有 trace
bunx langfuse-cli api traces list --session-id <session_id> --json | jq '.body.data[].id'

# 列出 trace 下所有 GENERATION observation
curl -s -u "$LANGFUSE_PUBLIC_KEY:$LANGFUSE_SECRET_KEY" \
  "$LANGFUSE_HOST/api/public/observations?traceId=<trace_id>&limit=100" \
  | jq '[.data[] | select(.type == "GENERATION") | {id, inputTokens: .usageDetails.input}]'

curl -s -u "$LANGFUSE_PUBLIC_KEY:$LANGFUSE_SECRET_KEY" \
  "$LANGFUSE_HOST/api/public/observations/<obs_id>" \
  | jq '.input' > /tmp/input_a.json

curl -s -u "$LANGFUSE_PUBLIC_KEY:$LANGFUSE_SECRET_KEY" \
  "$LANGFUSE_HOST/api/public/observations/<obs_id>" \
  | jq '.input' > /tmp/input_b.json

diff /tmp/input_a.json /tmp/input_b.json

© KonghaYao, Apache-2.0. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

SKILL.md and 22 other files (scripts, references) in .claude/skills/langfuse of KonghaYao/peri.

• SKILL.md
• references/cli.md
• references/error-analysis.md
• references/instrumentation.md
• references/judge-calibration.md
• references/local-gateway-logs.md
• references/prompt-migration.md
• references/sdk-upgrade.md
• references/skill-feedback.md
• references/user-feedback.md
• scripts/analyze.ts
• scripts/context-growth.mjs
• scripts/daily-report.ts
• scripts/lib.test.ts
• scripts/lib.ts
• scripts/llm-log-query.mjs
• scripts/prompt-breakdown.ts
• scripts/session-analyze.ts
• scripts/trace-messages.ts
• … and 4 more

Open the folder on GitHubat commit d7ee444