给 Agent 排查问题时,最烦的就是不知道哪一步慢、哪一步的输入传错了。LLM 调用链是嵌套的:一个 compute 里套 add 和 multiply,add 又可能再调别的。光看最后结果,中间哪一环出了问题根本看不出来。
MLflow 的 tracing 就是为这个做的。它用一个装饰器把每次调用记成一个 span,输入、输出、耗时、父子关系全留痕。我装了一遍,先装的轻量版,后来换成完整版。两个都踩了坑。
先说我一开始的假设。我以为轻量版和完整版只是体积差一点,功能一样。这个假设是错的。往下看你就知道错在哪。
轻量版装得飞快,但查不了
本机是 macOS arm64,Python 3.13.12。我先用 uv 建了个 venv,装的 mlflow-tracing,官方文档说它比完整版小 95%。
uv venv mlflow-venv --python 3.13
UV_HTTP_TIMEOUT=120 uv pip install --python mlflow-venv/bin/python mlflow-tracing --index-url https://pypi.tuna.tsinghua.edu.cn/simple
装完查版本,mlflow-tracing 3.18.0。它没带 torch、scikit 这些大家伙,几秒就装好了。体积小是真的。
然后我就踩了第一个坑。我用 @mlflow.trace 装饰器跑了个嵌套函数,跑通了,结果也对。可我想把 trace 查出来,mlflow.get_trace 直接报错。
ModuleNotFoundError: No module named 'sqlparse'
我不死心,补装 sqlparse 再试。pip install sqlparse 之后 import 通了,可 mlflow.get_last_active_trace_id 还是返回 None。这不是缺包的问题。
我查了它的代码路径。轻量版这个包设计成把 trace 发给远端 MLflow 或 Databricks,本地查询那条链路根本没打包,本地文件存储的依赖 sqlparse 也没装。装饰器跑了,trace 却拿不到,因为它不维护本地活动 trace 的上下文。
这是第一个教训。别看到 tracing 三个字就以为能本地查。
@mlflow.trace 装饰器怎么记 span
完整版装好后,我写了个最小例子。核心就一个装饰器,套上它就把调用记成 span。
import mlflow
import time
@mlflow.trace(name="add_numbers")
def add(a, b):
time.sleep(0.04)
return a + b
@mlflow.trace(name="multiply")
def mul(x, y):
time.sleep(0.02)
return x * y
@mlflow.trace(name="compute")
def compute(a, b, c):
s = add(a, b)
return mul(s, c)
compute(3, 4, 5)
三个函数都套了装饰器。compute 调 add 和 mul,嵌套关系是自动识别的,不用手动传 parent。我跑了三遍,每次 result 都是 35,也就是 3 加 4 得 7,再乘 5。
search_traces 回溯输入输出和耗时
跑完之后回溯,一行 mlflow.search_traces() 就把 trace 捞出来,返回一个 pandas DataFrame。
import mlflow
df = mlflow.search_traces()
row = df.iloc[0]
print(row["execution_duration"], row["state"], len(row["spans"]))
我在这里又踩了个小坑。第一遍我跑完立刻 search_traces,只回来 2 行,可我明明跑了 3 遍。后来加了个 time.sleep(1.0) 等它把异步日志队列 flush 掉,才拿全。日志里那句 Flushing the async trace logging queue before program exit 就是证据。
本机跑出来的 execution_duration 是 107 毫秒,state 是 OK,spans 是 3 个。三个 span 就是 compute、add_numbers、multiply,父子关系靠 parent_span_id 连起来。
我实测了 add 这个 span。它有两个字段 start_time_unix_nano 和 end_time_unix_nano,都是纳秒时间戳,本机相减是 73.24 毫秒,跟我代码里 sleep 0.04 秒加执行开销对得上。所以能精确到单次调用,不是整个 trace 的总时长。
每个 span 记的就是这几样。name 是函数名,parent_span_id 管层级,两个纳秒时间戳算耗时,attributes 里存输入输出。LLM 调用的话,attributes 还会带 prompt、response、token 用量,这些在 DataFrame 的 spans 列里能翻出来。
还有一个点值得提。MLflow 的 tracing 底层是 OpenTelemetry,官方说支持 GenAI Semantic Conventions,导出和摄取都不锁厂商。这意味着你埋的点能导出到别的 OTel 后端,不会绑死在 MLflow 上。
除了手动装饰器,它还有一行自动埋点。mlflow.openai.autolog() 或者 mlflow.langchain.autolog(),调一下就能把框架里的 LLM 调用全记下来,官方说支持 60 多个框架。我这次用的是手动装饰器,因为我的例子没真调 LLM,只是模拟嵌套。已经用现成框架的项目,自动埋点省事得多。
本地查 trace 也不用起服务。完整版默认把 trace 写进当前目录的 mlruns 文件夹,里面是 SQLite 和 trace 数据文件。我跑 search_traces 时,日志里那句 Creating initial MLflow database tables 就是它在建本地库。要发远端,用 mlflow.set_tracking_uri 指过去就行。
轻量版和完整版怎么选
给个判断。你要在本地调试 Agent,看每一步的输入输出和耗时,装完整版 mlflow,配本地文件存储,search_traces 直接查。缺点是体积大,装下来带上 sqlalchemy、starlette 一堆依赖。
你要在生产给线上应用埋点,把 trace 发到统一的 MLflow 或 Databricks 后端,就装轻量版。它小,但本地查不了,我踩的 sqlparse 那个坑就是它。
一句话。MLflow tracing 值不值得上,看你的 Agent 是不是已经多到肉眼看不过来。还在写单文件 demo,print 就够了。开始有嵌套调用、有多个工具、有真实用户了,这一行埋点比你在每个函数里手写 logger 划算得多。