instrumenting-with-mlflow-tracing — скилл MLflow для Claude Code и других агентов
Скилл instrumenting-with-mlflow-tracing добавляет или чинит MLflow tracing в Python и TypeScript: автологирование фреймворков, свои спаны, проверка сохранённых трейсов.
Apache-2.0 1 100 установок ★ 91 обновлён 2026-10-23
npx skills add mlflow/skills --skill instrumenting-with-mlflow-tracing -a claude-codeЧто делает instrumenting-with-mlflow-tracing
Скилл настраивает трассировку MLflow в приложении, чтобы потом использовать трейсы для расследования или оценки. Работает с Python и TypeScript, покрывает автологирование LangChain и других фреймворков, ручные спаны и настройку бэкенда.
Порядок такой: сначала проверяется, куда писать трейсы — Databricks, OSS или SageMaker. Для Databricks скилл читает отдельный референс по настройке UC и сам ищет доступный warehouse. Потом включается автологирование нужного фреймворка. LangGraph использует mlflow.langchain.autolog(), а не mlflow.langgraph.autolog() — это частая ошибка.
После запуска одного запроса скилл сохраняет trace ID сразу в процессе, через mlflow.get_last_active_trace_id() в Python. Потом сбрасывает буфер, ищет сохранённый трейс и проверяет, что это именно трейс приложения, а не телеметрия ассистента или скорера. На всю проверку отводится 60 секунд; если бэкенд недоступен, скилл останавливается и сообщает об этом, а не делает вид, что проверил.
Перед работой нужно проверить точку входа, язык, версию SDK, tracking URI и эксперимент. Явные destination приложения перекрывают переменные окружения — телеметрия ассистента может писать в другой эксперимент, поэтому скилл проверяет и это. В комплекте лежат референсы: production, advanced patterns, distributed tracing, feedback collection, root span previews, а также debug-agent и fix-agent-issue как опциональные задачи.
Какие задачи решает
- добавить MLflow tracing в приложение на Python или TypeScript
- включить автологирование LangChain, не оборачивая узлы повторно
- сохранить trace ID до того, как процесс завершится
- проверить, что трейс действительно записался в бэкенд
- не потерять явный destination приложения при настройке Databricks
Примеры запросов агенту
- Добавь MLflow tracing в этот Python-скрипт: он обрабатывает запрос через LangChain.
- Трейсы пишутся не в тот эксперимент. Разберись, куда они должны идти, и исправь настройку.
- Проверь, что трейс реально сохранился после последнего запроса, и покажи, какие спаны он содержит.
Как установить instrumenting-with-mlflow-tracing
1Через Skills CLI (Vercel)
npx skills add mlflow/skills --skill instrumenting-with-mlflow-tracing -a claude-code2Вручную: положить файлы
~/.claude/skills/instrumenting-with-mlflow-tracing/SKILL.mdПапка скилла целиком; для одного проекта — .claude/skills/instrumenting-with-mlflow-tracing/
1Через Skills CLI (Vercel)
npx skills add mlflow/skills --skill instrumenting-with-mlflow-tracing -a codex2Вручную: положить файлы
.agents/skills/instrumenting-with-mlflow-tracing/SKILL.mdДля всех проектов — ~/.agents/skills/
1Через Skills CLI (Vercel)
npx skills add mlflow/skills --skill instrumenting-with-mlflow-tracing -a cursor2Вручную: положить файлы
.cursor/skills/instrumenting-with-mlflow-tracing/SKILL.mdCursor читает и .agents/skills/, и .claude/skills/
1GitHub CLI
gh skill install mlflow/skills instrumenting-with-mlflow-tracing2Вручную: положить файлы
.github/skills/instrumenting-with-mlflow-tracing/SKILL.md1Через Skills CLI (Vercel)
npx skills add mlflow/skills --skill instrumenting-with-mlflow-tracing -a gemini-cli2Командой платформы
gemini skills install https://github.com/mlflow/skills --path instrumenting-with-mlflow-tracingВручную: положить файлы
.devin/skills/instrumenting-with-mlflow-tracing/SKILL.mdСтарый путь .windsurf/skills/ тоже читается
Через Skills CLI (Vercel)
npx skills add mlflow/skills --skill instrumenting-with-mlflow-tracing -a opencodeClaude.ai
Упакуйте папку в zip и загрузите в Settings → Capabilities → Skills
По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов
Вопросы об instrumenting-with-mlflow-tracing
Как установить instrumenting-with-mlflow-tracing в Claude Code?
Выполни npx skills add mlflow/skills --skill instrumenting-with-mlflow-tracing -a claude-code. Скилл появится в ~/.claude/skills/instrumenting-with-mlflow-tracing/SKILL.md.
Что делает этот скилл?
Добавляет или чинит MLflow tracing в приложениях на Python и TypeScript: настраивает бэкенд, включает автологирование фреймворков, добавляет ручные спаны и проверяет, что трейсы записались и доступны для чтения.
Чем автологирование LangGraph отличается от LangChain?
Для LangGraph вызывается mlflow.langchain.autolog(), а не mlflow.langgraph.autolog(). Скилл это учитывает, чтобы не включать неправильную интеграцию.
Исходный текст
SKILL.md · Apache-2.0
---
name: instrumenting-with-mlflow-tracing
description: Add or repair MLflow tracing in Python or TypeScript applications, including tracing required for evaluation. Covers framework autologging, custom spans, backend setup, and persisted trace verification.
---
# Instrument MLflow tracing
Reuse working tracing for investigation or evaluation.
## Prerequisites
- Check entry point, language/framework, SDK version, tracking URI, experiment, and deployment identity.
- Preserve destinations and providers. Explicit application destinations override inherited environment values; assistant telemetry may use another experiment.
- Read [Python](references/python.md) or [TypeScript](references/typescript.md) for the runtime.
## Step 1: Check the destination (Databricks only)
For OSS or SageMaker, keep the configured backend and proceed to Step 2.
- Read [UC setup](references/databricks.md) **before editing**; validate auth/workspace.
- Reuse the explicit destination; otherwise resolve schema choice before provisioning.
- Discover an accessible warehouse automatically. Default to UC; legacy storage requires an explicit request.
## Step 2: Enable framework tracing
- Enable the matching integration before execution. LangGraph uses `mlflow.langchain.autolog()`, not `mlflow.langgraph.autolog()`.
- Do not wrap automatically traced nodes, tools, or models again. Reserve manual spans for uncaptured work or an outer application boundary.
## Step 3: Capture application work
- Trace meaningful root, LLM, retrieval, tool, routing, and external I/O (files/queues).
Skip utility, configuration, and logging noise.
- Capture actual relevant inputs/outputs explicitly for manual spans; redact before export.
## Step 4: Run one request
- Run one representative request; record start/end epoch milliseconds.
- Save its trace ID immediately in-process: `mlflow.get_last_active_trace_id()` in Python; the active span's ID in TypeScript.
- Write/flush the trace ID to a file or captured stdout before readback; retain it if the process is cancelled.
Do not rerun to recover an ID.
<a id="verification"></a>
## Verification
- Fetch a **persisted application trace**, not a local span or old trace.
- Set a **60-second wall-clock process deadline** for readback, including flush, SDK retries, requests, and backoff.
Terminate at expiry unless the user explicitly requests deeper troubleshooting.
- Tool yields/thread-wait timeouts do not cancel calls. Without cancellation, report backend verification as unperformed.
- Flush once (`mlflow.flush_trace_async_logging()` / `await mlflow.flushTraces()`); fetch the saved ID.
- Without an ID, search once in the configured experiment with run-time bounds, `max_results=1`, and spans included.
- Every UC search needs `trace.timestamp_ms`; result limits do not bound scans. Python `search_traces()` has no `start_time` keyword.
For Python readback, adapt this recipe to the saved run values and enforce the deadline externally:
```python
mlflow.flush_trace_async_logging()
if trace_id:
trace = mlflow.get_trace(trace_id)
else:
traces = mlflow.search_traces(
locations=[experiment_id],
filter_string=(f"trace.timestamp_ms >= {run_start_ms} "
f"AND trace.timestamp_ms <= {run_end_ms}"),
max_results=1, return_type="list", include_spans=True,
)
trace = traces[0] if traces else None
assert trace is not None, "No persisted trace read back"
assert run_start_ms <= trace.info.request_time <= run_end_ms
assert trace.data.spans, "No spans captured"
```
- Inspect expected root/graph, model, retrieval, and tool spans and actual I/O. Confirm the application's request, not scorer or assistant telemetry.
- Check experiment/location from returned metadata, or the bound UC location if no experiment ID exists.
- Reuse returned spans; stop after success. Available `agent-evaluation/scripts/validate_tracing_runtime.py` may replace this check under the same deadline, not add another audit.
- Retry at most once after a concrete quick fix **within the original budget**.
- Stop on missing provider keys, auth/permission errors, warehouse timeouts, or `RESOURCE_EXHAUSTED`/429.
- No parallel searches, repeated agent runs, direct UC SQL, raw REST, alternate credentials, or warehouse fallbacks.
- Report operation/error, captured ID, successes, and unverified results. Request the missing prerequisite, not secrets.
- Keep instrumentation changes if backend verification is blocked; pause evaluation until tracing is verified.
Return the verified trace ID/link and observed spans. For Databricks use the [verified trace URL rules](references/databricks.md#link-to-the-verified-trace), not an experiment-only link. Do not label an unverified link as proof.
## References
- Deployment, async export, sampling: [production](references/production.md).
- Async/thread context, redaction, caught errors or links: [advanced patterns](references/advanced-patterns.md).
- Cross-service parent propagation: [distributed tracing](references/distributed-tracing.md).
- User ratings tied to traces: [feedback collection](references/feedback-collection.md).
- Unreadable non-chat root previews: [root span previews](references/root-span-previews.md).
- Explaining captured behavior: `debug-agent`; implementing a requested behavior fix: `fix-agent-issue`, carrying the trace evidence. These are optional follow-on tasks.
- Other integrations: [automatic tracing docs](https://mlflow.org/docs/latest/genai/tracing/app-instrumentation/automatic.md). Check installed signatures/types.
- Missing/moved topic: [llms.txt](https://mlflow.org/docs/latest/llms.txt). Docs unavailable: use local recipes and installed API introspection; stop if correctness remains uncertain.
© mlflow · Apache-2.0 · mlflow/skills