К основному содержанию
скилл CX Codex

langsmith-trace-analyzer — скилл для Claude Code: анализ трасс

Скилл langsmith-trace-analyzer для Claude Code скачивает и разбирает трассы LangSmith. Он включается при отладке агентов и оценке результатов по логам запусков.

MIT ★ 106 обновлён 2026-11-11

Установить в Claude Code · Через Skills CLI (Vercel) Все способы и платформы ↓
npx skills add soba-labs/langchain-agent-skills --skill langsmith-trace-analyzer -a claude-code
Открыть на GitHub

Что делает 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-code

2Вручную: положить файлы

~/.claude/skills/langsmith-trace-analyzer/SKILL.md

Папка скилла целиком; для одного проекта — .claude/skills/langsmith-trace-analyzer/

По шагам, с командами для каждой платформы: Как установить скилл в 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

Похожие скиллы

Все скиллы по теме «ИИ и ML» →
langsmith-experiment-diagnosis langchain-ai Скилл langsmith-experiment-diagnosis для Claude Code и Codex разбирает результаты экспериментов в LangSmith через официальную CLI. Находит примеры с низкими оценками эвалюаторов и показывает причины ошибок. CX Codex +1 184установок langsmith-fetch langchain-ai Загружает трейсы LangSmith в агент — для отладки поведения, просмотра истории разговора и анализа вызовов инструментов. Запускается командой uv run langsmith-fetch с ключом LANGSMITH_API_KEY из .env. CX Codex +1 1 300установок langsmith akillness Маршрутизирует работу с LangSmith в одной цепочке — до SDK. Трассировка вызовов, офлайн-эвалюация, очереди ревью, синхронизация промптов в LLM-приложениях и агентах. CX Codex +1 328установок LangSmith Traced OpenAI Agent a2a MCP-сервер LangSmith Traced OpenAI Agent запускает цепочку LangChain через Gemini на Vertex AI и по желанию отправляет трассировки в LangSmith. CX Codex +1 4 178установок observability-langsmith Orchestra Research Скилл observability-langsmith для Claude Code отслеживает вызовы LLM и оценивает ответы на тестовых наборах. Проверяет качество AI-функций. CX Codex +1 56установок arize-migrate-langsmith arize Скилл arize-migrate-langsmith для Claude Code переносит исторические трейсы, датасеты и промпты из LangSmith в Arize AX. Запускается при смене платформы наблюдаемости LLM. CX Codex +1 416установок

Из того же набора9

langsmith-deployment Помогает разворачивать и обслуживать агентные серверы в LangSmith Deployment. Подключается при настройке langgraph.json, создании ревизий или разборе проблем с запуском. CX Codex +1 ★ 106звёзд репо langgraph-testing-evaluation Скилл langgraph-testing-evaluation для Claude Code проверяет и оценивает агентов LangGraph и LangChain. Он подключается к задачам с тестами узлов, оценкой траекторий и сравнением версий агента. CX Codex +1 ★ 106звёзд репо langgraph-state-management Скилл langgraph-state-management для Claude Code помогает проектировать состояние приложений LangGraph и разбирать проблемы с его обновлением. Включается при работе со схемами, редьюсерами и сохранением состояния. CX Codex +1 ★ 106звёзд репо langgraph-project-setup Скилл langgraph-project-setup для Claude Code помогает создать и настроить проект LangGraph. Он включается при настройке структуры, langgraph.json, переменных среды и зависимостей. CX Codex +1 ★ 106звёзд репо langgraph-error-handling Скилл langgraph-error-handling для Claude Code помогает настраивать обработку ошибок в LangGraph. Подключается, когда нужно добавить повторы, восстановление через LLM или передачу решения человеку. CX Codex +1 ★ 106звёзд репо langgraph-agent-patterns Скилл langgraph-agent-patterns для Claude Code помогает собирать схемы координации агентов в приложениях на LangGraph. Он включается при выборе паттерна или отладке взаимодействия агентов. CX Codex +1 ★ 106звёзд репо deepagents-setup-configuration Скилл deepagents-setup-configuration для Claude Code создаёт и проверяет проекты Deep Agents на Python или JavaScript. Помогает настроить субагентов, память и подтверждение действий человеком. CX Codex +1 ★ 106звёзд репо deepagents-planning-todos Скилл deepagents-planning-todos для Claude Code помогает планировать задачи в Deep Agents через список дел write_todos. Он включается, когда нужно разбить работу на этапы, следить за прогрессом или выяснить, почему пункт не завершается. CX Codex +1 ★ 106звёзд репо

Спонсоры проекта

Компании, которые помогают держать аналитику открытой