langsmith-trace-analyzer

用途

LangSmith Trace Analyzer 用于将原始的 LangSmith 追踪数据转化为可操作的调试与评估洞察。当你需要按项目、元数据、状态或时间查询追踪/运行记录，并对结果进行整理和分析时，可以使用该技能。

主要能力

下载与整理追踪：通过 scripts/download_traces.py（Python）或 scripts/download_traces.ts（TypeScript）下载追踪数据，支持按项目、过滤器、时间范围、数量限制等参数筛选。Python 脚本支持 --organize/--no-organize，可将结果按结果类型归类到 by-outcome/ 下的 passed/、failed/、error/ 等目录，并生成 manifest.json。
离线分析：通过 scripts/analyze_traces.py 分析已下载的 JSON 数据，可输出 Markdown 报告或 JSON 结果。分析内容包括消息/工具调用/token/耗时汇总、工具使用排行、异常模式（如消息数过高、工具重复调用、快速失败），以及在启用对比时给出通过组与失败组的指标差异。
查询与过滤：使用 LangSmith SDK 的 list_runs/listRuns 配合官方过滤语法（filter 和/或 start_time）来发现追踪，再下载选定的 trace ID。
参考文档：提供 references/filtering-querying.md（查询/过滤语法）、references/analysis-patterns.md（诊断模式与启发式）、references/benchmark-analysis.md（基准分析工作流），按需加载。

使用方式

安装依赖并配置认证：

uv pip install langsmith langsmith-fetch
export LANGSMITH_API_KEY=<your_langsmith_api_key>

下载追踪（Python 示例）：

uv run skills/langsmith-trace-analyzer/scripts/download_traces.py \
  --project "my-project" \
  --filter "job_id=abc123" \
  --last-hours 24 \
  --limit 100 \
  --output ./traces \
  --organize

TypeScript 示例：

ts-node skills/langsmith-trace-analyzer/scripts/download_traces.ts \
  --project "my-project" \
  --filter "job_id=abc123" \
  --last-hours 24 \
  --limit 100 \
  --output ./traces

分析已下载的追踪：

# Markdown 报告
uv run skills/langsmith-trace-analyzer/scripts/analyze_traces.py ./traces --output report.md

# JSON 输出
uv run skills/langsmith-trace-analyzer/scripts/analyze_traces.py ./traces --json

# 对比通过组与失败组（需要 by-outcome 目录结构）
uv run skills/langsmith-trace-analyzer/scripts/analyze_traces.py ./traces --compare --output comparison.md

使用 SDK 查询追踪（Python 示例）：

from datetime import datetime, timedelta, timezone
from langsmith import Client

client = Client()

start = datetime.now(timezone.utc) - timedelta(hours=24)
filter_query = 'and(eq(metadata_key, "job_id"), eq(metadata_value, "abc123"))'

runs = client.list_runs(
    project_name="my-project",
    is_root=True,
    start_time=start,
    filter=filter_query,
)

TypeScript 示例：

import { Client } from "langsmith";

const client = new Client();
for await (const run of client.listRuns({
  projectName: "my-project",
  isRoot: true,
  filter: 'and(eq(metadata_key, "job_id"), eq(metadata_value, "abc123"))',
})) {
  console.log(run.id, run.status);
}

决策指南

已知 trace ID：直接使用 langsmith-fetch trace <id>，或在下载脚本中使用 --trace-ids。
需要先发现追踪：使用 LangSmith SDK 的 list_runs/listRuns 配合过滤器，再下载选定的 trace ID。
需要聚合洞察：运行 analyze_traces.py 获取汇总统计、模式和通过组与失败组对比。

适用场景

调试 LangChain 智能体运行中的失败或异常。
对评估结果进行通过组与失败组的指标对比。
进行基准分析（参考 references/benchmark-analysis.md）。
需要按元数据（如 job_id）或时间范围筛选并批量下载追踪数据。

限制与注意事项

需要有效的 LANGSMITH_API_KEY 才能访问 LangSmith 数据。
分析脚本对多种载荷结构具有容错性，但完整对话内容建议使用下载的追踪载荷而非仅 list_runs 结果。
追踪载荷可能包含用户提示、输出、元数据等敏感运行时数据，请勿在未脱敏的情况下提交下载的追踪产物（如 manifest.json、trace JSON 转储）。
常见问题：缺少 API Key 需配置认证；无运行返回时检查项目名、过滤语法和时间范围；消息数组为空或不完整可能因运行模式差异或数据不完整，应使用下载的追踪 JSON 并检查 status/error 字段；JSON 解析错误可能因导出不完整，需重新下载或使用脚本的 --format raw 路径；重复下载相同追踪时，当前脚本会检查输出树中已存在的文件。

技能介绍

用途

主要能力

使用方式

决策指南

适用场景

限制与注意事项