langsmith-trace-analyzer — скилл для Claude Code: анализ трасс
Скилл langsmith-trace-analyzer для Claude Code скачивает и разбирает трассы LangSmith. Он включается при отладке агентов и оценке результатов по логам запусков.
MIT ★ 106 обновлён 2026-11-11
npx skills add soba-labs/langchain-agent-skills --skill langsmith-trace-analyzer -a claude-codeЧто делает langsmith-trace-analyzer
Скилл выгружает трассы LangSmith в JSON, раскладывает их по исходам и строит отчёты для отладки. Трассы можно отбирать по проекту, фильтру и временному диапазону; анализатор сравнивает успешные и неуспешные запуски, считает сообщения, вызовы инструментов, токены и длительность, а также отмечает повторные вызовы и быстрые сбои.
В составе есть Python-скрипты для скачивания и анализа, а также TypeScript-скрипт для выгрузки. Для работы нужны пакеты langsmith и langsmith-fetch и ключ LANGSMITH_API_KEY. Трассы могут содержать пользовательские запросы и другие чувствительные данные: не добавляйте их в репозиторий без очистки.
Какие задачи решает
- найти трассы по проекту, метаданным или времени
- выгрузить запуски LangSmith в JSON
- разложить результаты по успешным, неуспешным и ошибочным
- сравнить метрики успешных и неуспешных запусков
- выявить повторные вызовы инструментов и быстрые сбои
Примеры запросов агенту
- Найди трассы проекта
my-projectза последние 24 часа и сохрани их в./traces. - Сравни успешные и неуспешные запуски из
./tracesи запиши отчёт вcomparison.md. - Разбери трассы в
./tracesи подготовь сводку в формате JSON.
Как установить langsmith-trace-analyzer
1Через Skills CLI (Vercel)
npx skills add soba-labs/langchain-agent-skills --skill langsmith-trace-analyzer -a claude-code2Вручную: положить файлы
~/.claude/skills/langsmith-trace-analyzer/SKILL.mdПапка скилла целиком; для одного проекта — .claude/skills/langsmith-trace-analyzer/
1Через Skills CLI (Vercel)
npx skills add soba-labs/langchain-agent-skills --skill langsmith-trace-analyzer -a codex2Вручную: положить файлы
.agents/skills/langsmith-trace-analyzer/SKILL.mdДля всех проектов — ~/.agents/skills/
1Через Skills CLI (Vercel)
npx skills add soba-labs/langchain-agent-skills --skill langsmith-trace-analyzer -a cursor2Вручную: положить файлы
.cursor/skills/langsmith-trace-analyzer/SKILL.mdCursor читает и .agents/skills/, и .claude/skills/
1GitHub CLI
gh skill install soba-labs/langchain-agent-skills skills/langsmith-trace-analyzer2Вручную: положить файлы
.github/skills/langsmith-trace-analyzer/SKILL.md1Через Skills CLI (Vercel)
npx skills add soba-labs/langchain-agent-skills --skill langsmith-trace-analyzer -a gemini-cli2Командой платформы
gemini skills install https://github.com/soba-labs/langchain-agent-skills --path skills/langsmith-trace-analyzerВручную: положить файлы
.devin/skills/langsmith-trace-analyzer/SKILL.mdСтарый путь .windsurf/skills/ тоже читается
Через Skills CLI (Vercel)
npx skills add soba-labs/langchain-agent-skills --skill langsmith-trace-analyzer -a opencodeClaude.ai
Упакуйте папку в zip и загрузите в Settings → Capabilities → Skills
По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов
Вопросы о langsmith-trace-analyzer
Как установить langsmith-trace-analyzer в Claude Code?
Выполни npx skills add soba-labs/langchain-agent-skills --skill langsmith-trace-analyzer -a claude-code. Файл скилла появится по пути ~/.claude/skills/langsmith-trace-analyzer/SKILL.md.
Что делает langsmith-trace-analyzer?
Скачивает и сортирует трассы LangSmith, затем формирует сводки и сравнения успешных и неуспешных запусков. Анализ включает сообщения, вызовы инструментов, токены и длительность.
Что нужно для работы langsmith-trace-analyzer?
Нужны пакеты langsmith и langsmith-fetch, а также ключ LANGSMITH_API_KEY. Команда установки пакетов: uv pip install langsmith langsmith-fetch.
Исходный текст
SKILL.md · MIT
---
name: langsmith-trace-analyzer
description: "Fetch, organize, and analyze LangSmith traces for debugging and evaluation. Use when you need to: query traces/runs by project, metadata, status, or time window; download traces to JSON; organize outcomes into passed/failed/error buckets; analyze token/message/tool-call patterns; compare passed vs failed behavior; or investigate benchmark and production failures."
---
# LangSmith Trace Analyzer
Use this skill to move from raw LangSmith traces to actionable debugging/evaluation insights.
## Quick Start
```bash
# Install dependencies
uv pip install langsmith langsmith-fetch
# Auth
export LANGSMITH_API_KEY=<your_langsmith_api_key>
```
### Fast workflow
1. Download traces with `scripts/download_traces.py` (or `scripts/download_traces.ts`).
2. Analyze downloaded JSON with `scripts/analyze_traces.py`.
3. Load targeted references only when needed:
- `references/filtering-querying.md` for query/filter syntax
- `references/analysis-patterns.md` for deeper diagnostics
- `references/benchmark-analysis.md` for benchmark-specific workflows
## Decision Guide
1. **Known trace IDs**
Use `langsmith-fetch trace <id>` directly, or `--trace-ids` in downloader scripts.
2. **Need to discover traces first**
Use LangSmith SDK `list_runs/listRuns` with filters, then download selected trace IDs.
3. **Need aggregate insights**
Run `analyze_traces.py` for summary stats, patterns, and passed-vs-failed comparisons.
## Core Workflows
### 1) Download and organize traces
Python:
```bash
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:
```bash
ts-node skills/langsmith-trace-analyzer/scripts/download_traces.ts \
--project "my-project" \
--filter "job_id=abc123" \
--last-hours 24 \
--limit 100 \
--output ./traces
```
Output layout:
```text
traces/
├── manifest.json
└── by-outcome/
├── passed/
├── failed/
└── error/
├── GraphRecursionError/
├── TimeoutError/
└── DaytonaError/
```
Notes:
- Python script supports `--organize/--no-organize`.
- Both scripts use SDK filtering plus `langsmith-fetch` for full trace payload export.
### 2) Analyze downloaded traces
```bash
# Markdown report
uv run skills/langsmith-trace-analyzer/scripts/analyze_traces.py ./traces --output report.md
# JSON output
uv run skills/langsmith-trace-analyzer/scripts/analyze_traces.py ./traces --json
# Compare passed vs failed (expects by-outcome folders)
uv run skills/langsmith-trace-analyzer/scripts/analyze_traces.py ./traces --compare --output comparison.md
```
The analyzer reports:
- message/tool-call/token/duration summaries
- top tool usage
- anomaly patterns (high message count, repeated tools, quick failures)
- passed-vs-failed metric deltas when comparison is enabled
### 3) Query traces correctly (SDK)
Use official LangSmith run filter syntax via `filter` and/or `start_time`:
```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,
)
```
For TypeScript:
```ts
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);
}
```
## Accuracy and Schema Notes
- LangSmith run fields are commonly top-level (`status`, `error`, `total_tokens`, `start_time`, `end_time`).
- Some exported traces also include nested metadata (`metadata` or `extra.metadata`) and/or `messages`.
- `analyze_traces.py` is resilient to multiple payload shapes, including raw array payloads.
- For full conversation content, prefer downloaded trace payloads over bare `list_runs` results.
## Troubleshooting
| Issue | Likely Cause | Action |
|---|---|---|
| `LANGSMITH_API_KEY` missing | Auth not configured | `export LANGSMITH_API_KEY=<your_langsmith_api_key>` |
| No runs returned | Wrong project/filter/time range | Verify project name and filter syntax |
| Empty/partial message arrays | Run schema differs or incomplete data | Use downloaded trace JSON and inspect `status/error` fields |
| JSON parse error on downloaded files | Bad/incomplete export | Re-download trace; use `--format raw` paths in scripts |
| Re-downloading same traces repeatedly | Existing files in nested folders | Use current scripts (they check existing files across output tree) |
## Safety for Open Source
- Do not commit downloaded trace artifacts (`manifest.json`, trace JSON dumps) unless sanitized.
- Trace payloads can contain user prompts, outputs, metadata, and other sensitive runtime data.
- Keep this skill repository focused on scripts/templates, not production trace exports.
## Resources
### scripts/
- `scripts/download_traces.py`: Python downloader + organizer
- `scripts/download_traces.ts`: TypeScript downloader + organizer
- `scripts/analyze_traces.py`: Offline analysis and reporting
### references/
- `references/filtering-querying.md`: LangSmith query/filter examples
- `references/analysis-patterns.md`: Diagnostic patterns and heuristics
- `references/benchmark-analysis.md`: Benchmark-oriented analysis
© soba-labs · MIT · soba-labs/langchain-agent-skills