instrumenting-with-mlflow-tracing — MLflow tracing skill for Claude Code, Cursor, Codex
instrumenting-with-mlflow-tracing sets up or repairs MLflow tracing in Python and TypeScript apps: framework autologging, custom spans, and persisted trace checks.
Apache-2.0 1,100 installs ★ 91 updated 2026-10-23
npx skills add mlflow/skills --skill instrumenting-with-mlflow-tracing -a claude-codeWhat instrumenting-with-mlflow-tracing does
This skill wires MLflow tracing into an application so the traces can be reused later for debugging or evaluation. It handles Python and TypeScript, autologging for LangChain and similar frameworks, manual spans, and backend configuration.
It starts by checking where traces should go: Databricks, OSS, or SageMaker. On Databricks it reads a separate UC setup reference and discovers an accessible warehouse on its own. Then it enables the right framework integration. LangGraph needs mlflow.langchain.autolog() — calling mlflow.langgraph.autolog() breaks silently.
After one representative request, the skill captures the trace ID in-process via mlflow.get_last_active_trace_id() in Python. It then flushes, fetches the saved trace, and confirms the spans belong to the application, not assistant telemetry or a scorer. The whole readback gets a 60-second deadline; if the backend is unreachable, the skill stops and says so instead of faking a verification.
The skill requires an entry point, language, SDK version, tracking URI, and experiment. Explicit app destinations override inherited environment values, so the assistant may write telemetry to a different experiment. It also ships references for production setup, async export, redaction, distributed tracing, feedback collection, and root span previews.
What it helps with
- add MLflow tracing to a Python or TypeScript app
- turn on LangChain autologging without double-wrapping nodes
- save the trace ID before the process exits
- confirm a trace actually persisted to the backend
- keep the explicit destination when configuring Databricks
Example prompts for the agent
- Add MLflow tracing to this Python script that handles a LangChain request.
- Traces are landing in the wrong experiment. Fix the destination and verify it.
- Check that the last request produced a persisted trace and list its spans.
How to install instrumenting-with-mlflow-tracing
1Skills CLI (Vercel)
npx skills add mlflow/skills --skill instrumenting-with-mlflow-tracing -a claude-code2Manually: put the files in place
~/.claude/skills/instrumenting-with-mlflow-tracing/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/instrumenting-with-mlflow-tracing/
1Skills CLI (Vercel)
npx skills add mlflow/skills --skill instrumenting-with-mlflow-tracing -a codex2Manually: put the files in place
.agents/skills/instrumenting-with-mlflow-tracing/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add mlflow/skills --skill instrumenting-with-mlflow-tracing -a cursor2Manually: put the files in place
.cursor/skills/instrumenting-with-mlflow-tracing/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install mlflow/skills instrumenting-with-mlflow-tracing2Manually: put the files in place
.github/skills/instrumenting-with-mlflow-tracing/SKILL.md1Skills CLI (Vercel)
npx skills add mlflow/skills --skill instrumenting-with-mlflow-tracing -a gemini-cli2Platform CLI
gemini skills install https://github.com/mlflow/skills --path instrumenting-with-mlflow-tracingManually: put the files in place
.devin/skills/instrumenting-with-mlflow-tracing/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add mlflow/skills --skill instrumenting-with-mlflow-tracing -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about instrumenting-with-mlflow-tracing
How do I install instrumenting-with-mlflow-tracing in Claude Code?
Run npx skills add mlflow/skills --skill instrumenting-with-mlflow-tracing -a claude-code. The skill lands in ~/.claude/skills/instrumenting-with-mlflow-tracing/SKILL.md.
What does this skill do?
It adds or repairs MLflow tracing in Python and TypeScript applications: backend setup, framework autologging, custom spans, and verification that traces persisted and are readable.
Why does LangGraph use the LangChain autolog call?
The LangGraph integration is enabled through mlflow.langchain.autolog(). The skill avoids mlflow.langgraph.autolog() because it is not the correct entry point.
Source text
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