MLflow 追踪工具使用指南：AI应用调试与可观测性最佳实践

instrumenting-with-mlflow-tracing by mlflow/skills

121 周安装量

24 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/mlflow/skills --skill instrumenting-with-mlflow-tracing

AI/机器学习可观测性调试

🇨🇳中文介绍

MLflow 追踪工具使用指南

语言特定指南

根据用户的项目，加载相应的指南：

Python 项目：阅读 references/python.md
TypeScript/JavaScript 项目：阅读 references/typescript.md

如果不确定，请在项目中检查是否存在 package.json（TypeScript）或 requirements.txt/pyproject.toml（Python）。

追踪内容

追踪以下操作（具有较高的调试/可观测价值）：

操作类型	示例	追踪原因

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

相关 Skills

find-skills 技能搜索工具 - Vercel Labs 开源智能体技能包管理器

896,800 周安装

React 组合模式指南：Vercel 组件架构最佳实践，提升代码可维护性

120,000 周安装

AI Elements：基于shadcn/ui的AI原生应用组件库，快速构建对话界面

69,600 周安装

超能力技能使用指南：AI助手技能调用优先级与工作流程详解

52,100 周安装

跳过追踪以下内容（过于细粒度，会增加噪音）：

简单的数据转换（字典/列表操作）
字符串格式化、解析、验证
配置加载、环境设置
日志记录或指标发送
纯工具函数（数学运算、排序、筛选）

经验法则：追踪那些对你的应用程序调试和问题识别至关重要的操作。

在代码中添加追踪功能后，务必验证追踪是否正常工作。

计划评估你的智能体？ 在运行 agent-evaluation 之前，追踪功能必须正常工作。请先完成以下验证。

运行已添加追踪的代码 — 执行应用程序或智能体，确保至少触发一个被追踪的操作
确认追踪记录已生成 — 使用 mlflow.search_traces() 或 MlflowClient().search_traces() 检查追踪是否出现在实验中：

import mlflow

traces = mlflow.search_traces(experiment_ids=["<experiment_id>"])
print(f"Found {len(traces)} trace(s)")
assert len(traces) > 0, "No traces were logged — check tracking URI and experiment settings"
```

3. 报告结果 — 告知用户找到了多少条追踪记录，并确认追踪功能正常工作

记录用户对追踪的反馈，用于评估、调试和微调。这对于识别生产环境中的质量问题至关重要。

有关以下内容，请参阅 references/feedback-collection.md：

使用 mlflow.log_feedback() 记录用户评分和评论
捕获追踪 ID 以返回给客户端
LLM 作为评判者的自动化评估

有关以下内容，请参阅 references/production.md：

环境变量配置
低延迟应用程序的异步日志记录
采样配置（MLFLOW_TRACE_SAMPLING_RATIO）
轻量级 SDK（mlflow-tracing）
Docker/Kubernetes 部署

有关以下内容，请参阅 references/advanced-patterns.md：

异步函数追踪
支持上下文传播的多线程
使用跨度处理器进行 PII 数据脱敏

有关以下内容，请参阅 references/distributed-tracing.md：

跨服务传播追踪上下文
客户端/服务器头信息 API

🇺🇸English

MLflow Tracing Instrumentation Guide

Language-Specific Guides

Based on the user's project, load the appropriate guide:

Python projects : Read references/python.md
TypeScript/JavaScript projects : Read references/typescript.md

If unclear, check for package.json (TypeScript) or requirements.txt/pyproject.toml (Python) in the project.

What to Trace

Trace these operations (high debugging/observability value):

Operation Type	Examples	Why Trace
Root operations	Main entry points, top-level pipelines, workflow steps	End-to-end latency, input/output logging
LLM calls	Chat completions, embeddings	Token usage, latency, prompt/response inspection
Retrieval	Vector DB queries, document fetches, search	Relevance debugging, retrieval quality
Tool/function calls	API calls, database queries, web search	External dependency monitoring, error tracking
Agent decisions	Routing, planning, tool selection	Understand agent reasoning and choices
External services	HTTP APIs, file I/O, message queues	Dependency failures, timeout tracking

Skip tracing these (too granular, adds noise):

Simple data transformations (dict/list manipulation)
String formatting, parsing, validation
Configuration loading, environment setup
Logging or metric emission
Pure utility functions (math, sorting, filtering)

Rule of thumb : Trace operations that are important for debugging and identifying issues in your application.

Verification

After instrumenting the code, always verify that tracing is working.

Planning to evaluate your agent? Tracing must be working before you run agent-evaluation. Complete verification below first.

Run the instrumented code — execute the application or agent so that at least one traced operation fires
Confirm traces are logged — use mlflow.search_traces() or MlflowClient().search_traces() to check that traces appear in the experiment:

import mlflow

traces = mlflow.search_traces(experiment_ids=["<experiment_id>"])
print(f"Found {len(traces)} trace(s)")
assert len(traces) > 0, "No traces were logged — check tracking URI and experiment settings"

3. Report the result — tell the user how many traces were found and confirm tracing is working

Feedback Collection

Log user feedback on traces for evaluation, debugging, and fine-tuning. Essential for identifying quality issues in production.

See references/feedback-collection.md for:

Recording user ratings and comments with mlflow.log_feedback()
Capturing trace IDs to return to clients
LLM-as-judge automated evaluation

Reference Documentation

Production Deployment

See references/production.md for:

Environment variable configuration
Async logging for low-latency applications
Sampling configuration (MLFLOW_TRACE_SAMPLING_RATIO)
Lightweight SDK (mlflow-tracing)
Docker/Kubernetes deployment

Advanced Patterns

See references/advanced-patterns.md for:

Async function tracing
Multi-threading with context propagation
PII redaction with span processors

Distributed Tracing

See references/distributed-tracing.md for:

Propagating trace context across services
Client/server header APIs

Weekly Installs

Repository

mlflow/skills

GitHub Stars

First Seen

Feb 5, 2026

Security Audits

Gen Agent Trust HubPass SocketPass SnykPass

Installed on

gemini-cli85

github-copilot85

codex84

opencode83

kimi-cli82

amp82

AI 代码实施计划编写技能 | 自动化开发任务分解与 TDD 流程规划工具

50,900 周安装