mlflow-trace-analysis — скилл для Claude Code: анализ MLflow-трейсов
Скилл mlflow-trace-analysis для Claude Code разбирает MLflow-трейсы и объясняет сбои агентов, ошибки и проблемы качества. Запускается для анализа отдельных трасс и многотуровых диалогов.
Apache-2.0 178 установок ★ 91 обновлён 2026-10-23
npx skills add mlflow/skills --skill mlflow-trace-analysis -a claude-codeЧто делает mlflow-trace-analysis
Скилл анализирует MLflow-трейсы, чтобы связать наблюдаемое поведение с конкретными спанами и их входами и выходами. Он разбирает ошибки, неожиданные ответы, качество, задержки и распространение сбоя между ходами диалога. Код приложения при диагностике не меняет.
Для анализа нужны ID трейса или сессии и настроенный backend. Скилл получает полный JSON командой mlflow traces get, изучает дерево спанов, обратную связь и события ошибок, затем сопоставляет данные с ожидаемым поведением. Если ID неизвестен, для поиска понадобится скилл mlflow-trace-retrieval либо руководство по поиску и справка установленного CLI.
Вывод разделяет наблюдаемые факты, возможные причины и недостающие свидетельства; гипотезу нельзя выдавать за подтверждённую причину. Повторный запуск приложения допускается только один раз через обычную инструментированную точку входа и только если это безопасно.
Какие задачи решает
- найти спан, в котором ответ агента впервые отклонился от ожидаемого
- объяснить ошибку по статусу, событиям исключения и данным спанов
- проследить, как сбой одного хода повлиял на последующие ответы
- отличить ошибку приложения от ошибки оценки обратной связи
- разобрать задержку с учётом вложенных и параллельных спанов
Примеры запросов агенту
- Разбери трейс
TRACE_IDи объясни, где ответ агента разошёлся с ожидаемым. - Проследи по сессии
SESSION_ID, как ошибка в одном ходе повлияла на следующие ответы. - Проверь обратную связь и спаны трейса
TRACE_ID; отдели подтверждённые причины от гипотез.
Как установить mlflow-trace-analysis
1Через Skills CLI (Vercel)
npx skills add mlflow/skills --skill mlflow-trace-analysis -a claude-code2Вручную: положить файлы
~/.claude/skills/mlflow-trace-analysis/SKILL.mdПапка скилла целиком; для одного проекта — .claude/skills/mlflow-trace-analysis/
1Через Skills CLI (Vercel)
npx skills add mlflow/skills --skill mlflow-trace-analysis -a codex2Вручную: положить файлы
.agents/skills/mlflow-trace-analysis/SKILL.mdДля всех проектов — ~/.agents/skills/
1Через Skills CLI (Vercel)
npx skills add mlflow/skills --skill mlflow-trace-analysis -a cursor2Вручную: положить файлы
.cursor/skills/mlflow-trace-analysis/SKILL.mdCursor читает и .agents/skills/, и .claude/skills/
1GitHub CLI
gh skill install mlflow/skills mlflow-trace-analysis2Вручную: положить файлы
.github/skills/mlflow-trace-analysis/SKILL.md1Через Skills CLI (Vercel)
npx skills add mlflow/skills --skill mlflow-trace-analysis -a gemini-cli2Командой платформы
gemini skills install https://github.com/mlflow/skills --path mlflow-trace-analysisВручную: положить файлы
.devin/skills/mlflow-trace-analysis/SKILL.mdСтарый путь .windsurf/skills/ тоже читается
Через Skills CLI (Vercel)
npx skills add mlflow/skills --skill mlflow-trace-analysis -a opencodeClaude.ai
Упакуйте папку в zip и загрузите в Settings → Capabilities → Skills
По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов
Вопросы о mlflow-trace-analysis
Как установить mlflow-trace-analysis в Claude Code?
Выполни npx skills add mlflow/skills --skill mlflow-trace-analysis -a claude-code. Файл скилла будет установлен по пути ~/.claude/skills/mlflow-trace-analysis/SKILL.md.
Что делает mlflow-trace-analysis?
Скилл анализирует MLflow-трейсы и многотуровые сессии: связывает входы и выходы спанов с ошибками, неожиданными ответами, качеством и задержками. Диагностика заканчивается рекомендациями и не меняет код.
Что нужно для работы mlflow-trace-analysis?
Нужны ID трейса или сессии и настроенный backend. Для поиска неизвестного ID используется mlflow-trace-retrieval либо руководство по поиску и справка установленного MLflow CLI.
Исходный текст
SKILL.md · Apache-2.0
---
name: mlflow-trace-analysis
description: Analyze MLflow traces, agent failures, and multi-turn chat sessions. Explain errors, unexpected output, quality issues, latency, or cross-turn propagation without editing application code.
---
# Analyze MLflow traces
Use the trace ID or session ID, configured backend, reported behavior and expected outcome. Reuse traces already fetched. For a multi-turn conversation, read [session analysis](references/session-analysis.md).
## Prerequisites
Before searching for an unknown trace ID, read [trace retrieval](../mlflow-trace-retrieval/SKILL.md) for filters, time bounds and pagination. Reuse an already fetched trace. If that skill is not installed, use the [search guide](https://mlflow.org/docs/latest/genai/tracing/search-traces.md) and installed CLI help.
Prefer existing evidence. Only when no usable trace exists, reproduce once through the normal instrumented entry point when safe; otherwise report the missing evidence. Record HUMAN feedback only when authorized and attached to an identified trace.
## Step 1: Fetch the trace
Fetch full JSON once to a file; large piped CLI output can be truncated by the execution tool. `get` needs no `--output` flag. Avoid `--extract-fields` for nested span diagnosis.
```bash
mlflow traces get --trace-id <TRACE_ID> > /tmp/trace.json
```
## Step 2: Inspect the span tree
Summarize state, assessments and parent links:
```bash
jq '{state: .info.state,
spans: [.data.spans[] | {span_id, parent_span_id, name, status}],
error_spans: [.data.spans[] | select(.status.code == "STATUS_CODE_ERROR") | .name],
assessments: .info.assessments}' /tmp/trace.json
```
## Step 3: Read feedback
Read feedback **source, value, top-level rationale, validity and scope** before forming a hypothesis. HUMAN feedback describes the reported experience; corroborate it with spans. LLM_JUDGE/CODE feedback may be wrong or misconfigured. `feedback.error` means scoring failed, not that the application failed; exclude errored/overridden judgments from quality conclusions. Genuine zero/false values remain valid. Expectations are desired-output labels, not scores.
## Step 4: Follow inputs and outputs
Follow actual inputs and outputs from root to the first divergence, then downstream effects. Raw MLflow span I/O is usually serialized JSON in `attributes["mlflow.spanInputs"]` / `attributes["mlflow.spanOutputs"]`; parse it before interpreting it. If the root is an empty wrapper, inspect descendants. For other OTel sources or versions, inspect raw keys instead of assuming this schema.
## Step 5: Check errors and performance
Check exception events and status messages. `OK` means execution success, not correct output; `STATUS_CODE_UNSET` is not itself an error. For performance, distinguish enclosing wrappers, overlapping child work and uninstrumented gaps; repeated names alone do not prove retries. Inspect recorded token usage rather than inventing cost or assuming a token spike proves injection.
## Step 6: Check the source
Correlate the decisive span's observed data with relevant source/configuration when available. Function names are clues; autologged names follow framework conventions. Separate observed facts, plausible causes and missing evidence. Do not edit code, create scorers or run an evaluation for diagnosis alone.
See the [refund-policy evidence table](references/session-analysis.md#worked-example-refund-policy-propagation) for a retrieval miss, unsupported answer and later propagation.
## Verification
Report observed versus expected behavior, trace and decisive span IDs, the evidence chain, confidence and the smallest likely remedy. Confirm claims against actual span I/O and feedback semantics, not previews alone. If evidence is missing, say what would resolve the uncertainty; do not promote a hypothesis to a confirmed root cause.
## References
- Fields, units, CLI versus SDK representation, OTel attributes or assessment interpretation: [trace structure](references/trace-structure.md).
- Bounded batches, recurring failures or component bottlenecks: [cross-trace analysis](references/cross-trace-analysis.md).
- Multi-turn propagation: [session analysis](references/session-analysis.md).
- A user-requested implementation: pass diagnosis and trace ID to `mlflow-agent-improvement` when installed; investigation itself stops at evidence and recommendations.
© mlflow · Apache-2.0 · mlflow/skills