retrieving-mlflow-traces — Claude Code skill for MLflow trace search
retrieving-mlflow-traces fetches MLflow traces by ID or filters using CLI and Python API. Useful for hunting down failed traces or dissecting a slow run.
Apache-2.0 991 installs ★ 91 updated 2026-10-23
npx skills add mlflow/skills --skill retrieving-mlflow-traces -a claude-codeWhat retrieving-mlflow-traces does
This skill teaches the agent two retrieval paths: a direct fetch with mlflow traces get when a trace ID is known, and a broader query with mlflow traces search. Filtering covers status, tags, metadata, execution time, session, user, and assessment data.
Searches against Unity Catalog must include a time bound in the filter string: trace.timestamp_ms >= <start_time_ms>. A small result limit does not stop a scan across the full trace history. Python has no start_time argument on mlflow.search_traces(), so the time condition goes through filter_string.
There is also a setup verification mode with a 60-second wall-clock deadline and at most one retry after a quick fix. If readback fails, the agent reports what was verified, what was not, and what the user must do, such as adding an API key or fixing warehouse capacity.
What it helps with
- Fetch a trace by exact ID
- Filter traces with ERROR status
- Pull all traces from one session for debugging
- Find runs slower than a given threshold
- Verify that new instrumentation writes traces
Example prompts for the agent
- Get trace
tr-69f72a3772570019f2f91b75b8b5ded9 - Show failed traces in experiment 1
- Find all traces for session
session_abc123, ordered by time
How to install retrieving-mlflow-traces
1Skills CLI (Vercel)
npx skills add mlflow/skills --skill retrieving-mlflow-traces -a claude-code2Manually: put the files in place
~/.claude/skills/retrieving-mlflow-traces/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/retrieving-mlflow-traces/
1Skills CLI (Vercel)
npx skills add mlflow/skills --skill retrieving-mlflow-traces -a codex2Manually: put the files in place
.agents/skills/retrieving-mlflow-traces/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add mlflow/skills --skill retrieving-mlflow-traces -a cursor2Manually: put the files in place
.cursor/skills/retrieving-mlflow-traces/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install mlflow/skills retrieving-mlflow-traces2Manually: put the files in place
.github/skills/retrieving-mlflow-traces/SKILL.md1Skills CLI (Vercel)
npx skills add mlflow/skills --skill retrieving-mlflow-traces -a gemini-cli2Platform CLI
gemini skills install https://github.com/mlflow/skills --path retrieving-mlflow-tracesManually: put the files in place
.devin/skills/retrieving-mlflow-traces/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add mlflow/skills --skill retrieving-mlflow-traces -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 retrieving-mlflow-traces
How do I install retrieving-mlflow-traces in Claude Code?
Run npx skills add mlflow/skills --skill retrieving-mlflow-traces -a claude-code. The skill lands at ~/.claude/skills/retrieving-mlflow-traces/SKILL.md.
What does retrieving-mlflow-traces do?
Retrieves MLflow traces through CLI or Python API. It can search by ID, status, tags, metadata, execution time, and full text.
Why does the skill require a time bound for Unity Catalog searches?
Without trace.timestamp_ms >= <start_time_ms> the search scans the entire trace history, and a small result limit will not help. When the relevant period is unclear, the skill asks for it before running a broad search.
Source text
SKILL.md · Apache-2.0
--- name: retrieving-mlflow-traces description: Retrieves MLflow traces using CLI or Python API. Use when the user asks to get a trace by ID, find traces, filter traces by status/tags/metadata/execution time, query traces, or debug failed traces. Triggers on "get trace", "search traces", "find failed traces", "filter traces by", "traces slower than", "query MLflow traces". --- # Retrieving MLflow Traces ## Bound Unity Catalog Searches by Time When searching traces stored in Unity Catalog, include `trace.timestamp_ms >= <start_time_ms>` in the filter string, with an upper bound when known. This also applies when searching by experiment ID, run ID, session, or other filters: a small result limit does not prevent a scan across the full trace history. In Python, pass the time condition through `filter_string`; `mlflow.search_traces()` has no `start_time` argument. Use the time window requested by the user or established by the run or incident. For setup verification, record the time immediately before the instrumented run. Do not silently restrict historical investigations to the last hour. If the relevant period cannot be determined, ask for it before starting a broad UC search. The examples below demonstrate individual filters; combine them with the relevant time bounds for UC. ## Keep Setup Verification Brief For verifying newly added instrumentation, follow the verification workflow in `instrumenting-with-mlflow-tracing`. Enforce a 60-second wall-clock deadline for readback, cancelling the verification command at the deadline even if a call is still retrying internally: make one fetch by a known trace ID, or one time-bounded search with `--max-results 1` (Python: `max_results=1`). Retry at most once after a concrete, quick fix, within the same budget. Stop once one trace and its expected spans are confirmed. If readback is slow or fails, report what was verified, what remains unverified, and the observed blocker and required user action (such as configuring a missing API key, logging in, obtaining permission, or resolving warehouse availability/capacity). Do not start parallel searches or fall back to direct SQL, raw REST, alternate authentication, or repeated agent runs just to complete setup verification. A dedicated retrieval or debugging request can require broader investigation; preserve the user's scope. ## Single Fetch vs Search Choose the right approach based on what you have: | You have... | Use | Command | |-------------|-----|---------| | **Trace ID** | Single fetch | `mlflow traces get --trace-id <id>` | | **Session/user/filters** | Search | `mlflow traces search --experiment-id <id> --filter-string "..."` | **Single fetch** - Use when you have a specific trace ID (e.g., from UI, logs, or API response): ```bash mlflow traces get --trace-id tr-69f72a3772570019f2f91b75b8b5ded9 ``` **Search** - Use when you need to find traces by criteria (session, user, status, time range, etc.): ```bash mlflow traces search --experiment-id 1 --filter-string "metadata.\`mlflow.trace.session\` = 'session_abc'" ``` --- ## Trace Data Structure - **TraceInfo**: `trace_id`, `status` (OK/ERROR), `timestamp_ms`, `execution_time_ms`, `tags`, `metadata`, `assessments` (human feedback, evaluation results) - **Spans**: Tree of operations with `name`, `type`, `attributes`, `start_time`, `end_time` ## Workflow 1. **Check CLI usage** (required): `mlflow traces search --help` 2. **Build filter query** using syntax below 3. **Execute search** with appropriate flags 4. **Retrieve details** for specific traces if needed ## Prerequisite: Check CLI Usage ```bash mlflow traces search --help ``` Always run this first to get accurate flags for the installed MLflow version. ## Searching Traces The `mlflow traces search` command is used to search for traces in an MLflow experiment. ### By Run ID Filter traces associated with a specific MLflow run: ```bash # All traces for a run mlflow traces search --run-id <run_id> # Failed traces for a run mlflow traces search --run-id <run_id> --filter-string "trace.status = 'ERROR'" # Can combine with experiment-id mlflow traces search --experiment-id 1 --run-id <run_id> ``` ### By Session or User (Common for Debugging) When debugging an issue from the MLflow UI, filter by session or user ID to get all related traces: ```bash # All traces for a specific session (use backticks for special characters in key) mlflow traces search --experiment-id 1 --filter-string "metadata.\`mlflow.trace.session\` = 'session_abc123'" # All traces for a specific user mlflow traces search --experiment-id 1 --filter-string "metadata.\`mlflow.trace.user\` = 'user_456'" # Failed traces in a session (for root cause analysis) mlflow traces search --experiment-id 1 --filter-string "metadata.\`mlflow.trace.session\` = 'session_abc123' AND trace.status = 'ERROR'" # Session traces ordered by time (to see sequence of events) mlflow traces search --experiment-id 1 --filter-string "metadata.\`mlflow.trace.session\` = 'session_abc123'" --order-by "timestamp_ms ASC" ``` ### By Status ```bash mlflow traces search --experiment-id 1 --filter-string "trace.status = 'ERROR'" mlflow traces search --experiment-id 1 --filter-string "trace.status = 'OK'" ``` ### By Time Range ```bash # Timestamps are in milliseconds since epoch # Get current time in ms: $(date +%s)000 # Last hour: $(( $(date +%s)000 - 3600000 )) mlflow traces search --experiment-id 1 --filter-string "trace.timestamp_ms > $(( $(date +%s)000 - 3600000 ))" ``` ### By Execution Time (Slow Traces) ```bash # Traces slower than 1 second mlflow traces search --experiment-id 1 --filter-string "trace.execution_time_ms > 1000" ``` ### By Tags and Metadata ```bash # By tag mlflow traces search --experiment-id 1 --filter-string "tag.environment = 'production'" # By metadata mlflow traces search --experiment-id 1 --filter-string "metadata.user_id = 'user_123'" # Escape special characters in key names with backticks mlflow traces search --experiment-id 1 --filter-string "tag.\`model-name\` = 'gpt-4'" mlflow traces search --experiment-id 1 --filter-string "metadata.\`user.id\` = 'abc'" ``` ### By Assessment/Feedback ```bash mlflow traces search --experiment-id 1 --filter-string "feedback.rating = 'positive'" ``` ### Full Text Search ```bash mlflow traces search --experiment-id 1 --filter-string "trace.text LIKE '%error%'" ``` ### Pagination Control result count and iterate through pages: ```bash # Limit results per page mlflow traces search --experiment-id 1 --max-results 50 # Output includes "Next page token: <token>" if more results exist # Use --page-token to fetch next page mlflow traces search --experiment-id 1 --max-results 50 --page-token "eyJvZmZzZXQiOiA1MH0=" ``` ### Output Options ```bash # Output format (table or json) mlflow traces search --experiment-id 1 --output json # Include span details in output mlflow traces search --experiment-id 1 --include-spans # Order results mlflow traces search --experiment-id 1 --order-by "timestamp_ms DESC" ``` ## Retrieving Single Trace When you need to retrieve details about a specific trace, use the `mlflow traces get` command. ```bash mlflow traces get --trace-id <trace_id> ``` ## Filter Syntax For detailed syntax, fetch from documentation: ``` WebFetch( url: "https://mlflow.org/docs/latest/genai/tracing/search-traces.md", prompt: "Extract the filter syntax table showing supported fields, operators, and examples." ) ``` **Common filters:** - `trace.status`: OK, ERROR, IN_PROGRESS - `trace.execution_time_ms`, `trace.timestamp_ms`: numeric comparison - `metadata.\`mlflow.trace.session\``, `metadata.\`mlflow.trace.user\``: session/user filtering - `tag.<key>`, `metadata.<key>`: exact match or pattern - `span.name`, `span.type`: exact match or pattern - `feedback.<name>`, `expectation.<name>`: assessments **Pattern operators:** `LIKE`, `ILIKE` (case-insensitive), `RLIKE` (regex) ## Python API For `mlflow.search_traces()`, see: https://mlflow.org/docs/latest/genai/tracing/search-traces.md
© mlflow · Apache-2.0 · mlflow/skills