设置 Span 日志级别

Span 日志级别根据严重程度对每个 Span 进行分类，该模型参考了 Python 标准的 logging 模块。它们让您可以一目了然地扫描复杂的追踪信息：在默认阈值下，追踪显示保持不变；但调高 UI 中的最小日志级别过滤器可以隐藏干扰信息（如链式调用、输出解析等），使您仅能看到用户可见的操作，例如请求、响应和工具调用。

这五个级别与 Python 的 logging 模块共用名称

级别	典型用途
DEBUG	内部/辅助工作 — 链式步骤、解析器等。
INFO	用户可见的操作 — LLM 调用、工具调用。
WARNING	您希望在生产环境中看到的、可恢复的问题。
ERROR	故障。
CRITICAL	需要紧急处理的严重停止错误。

设置 Span 的级别

您可以在创建 Span 时传递一个级别。该关键字参数接受枚举值或其名称。

Python

python

import mlflow
from mlflow.entities import SpanLogLevel


@mlflow.trace(log_level=SpanLogLevel.INFO)
def answer(query: str) -> str:
    docs = retrieve(query)
    return llm.generate(query, docs)


@mlflow.trace(log_level="DEBUG")  # string form
def retrieve(query: str): ...

您也可以在 LiveSpan 创建后设置其级别

python

with mlflow.start_span("foo") as span:
    span.set_log_level("WARNING")

TypeScript

typescript

import * as mlflow from "@mlflow/core";
import { SpanLogLevel, SpanType } from "@mlflow/core";

await mlflow.withSpan(
  { name: "answer", spanType: SpanType.AGENT, logLevel: SpanLogLevel.INFO },
  async (root) => {
    await mlflow.withSpan(
      { name: "retrieve", spanType: SpanType.RETRIEVER, parent: root, logLevel: "DEBUG" },
      async () => { /* ... */ },
    );
  },
);

默认日志级别

每个 Span（无论是手动创建还是通过自动日志集成创建，如 mlflow.openai.autolog(), mlflow.langchain.autolog() 等）都会根据其类型被分配一个默认级别。这确保了详细程度过滤器无需任何手动标注即可开箱即用。默认值在 Span 构造函数中应用，可以通过显式传递 log_level 关键字参数进行覆盖。

Span 类型	默认值
LLM, CHAT_MODEL, TOOL, RETRIEVER, AGENT, EMBEDDING	INFO
其他所有类型（CHAIN, PARSER, RERANKER, MEMORY, WORKFLOW, TASK, EVALUATOR, UNKNOWN, 自定义类型）	DEBUG

因此，在 UI 的默认阈值（DEBUG）下，您可以看到所有内容；在 INFO 下，您可以看到用户可见的操作并隐藏链式调用的辅助部分；在 WARNING 及以上级别，您仅能看到显式标记为该级别或更高级别的 Span。

包含异常事件的 Span 会被提升至 ERROR 级别

当 Span 记录异常事件时，MLflow 会自动将其级别提升至 ERROR（除非它已经处于更高的严重级别）。异常事件可能源于：

• 由 @mlflow.trace 装饰器捕获的未处理异常
• 显式调用 span.record_exception(...)
• 追踪器级别的错误处理程序

这确保了即使在用户调高详细程度过滤器时，故障在追踪浏览器中依然可见。

在 UI 上应用日志级别过滤器

在 MLflow UI 中打开一个追踪，点击时间线树上方的 Filter（过滤）。弹出窗口中有一个 Minimum log level（最小日志级别） 滑块（带有一个解释规则的“?”工具提示）

• Debug（默认）— 显示所有 Span。
• Info — 隐藏 DEBUG 级别的 Span（大部分链式调用的辅助逻辑消失）。
• Warning / Error / Critical — 仅显示明确标记为该阈值或更高级别的 Span。

现有的 Show all parent spans（显示所有父 Span） 和 Show exceptions（显示异常） 开关依然生效：它们会覆盖级别过滤器，确保您不会丢失匹配子项或记录了异常的 Span 的上下文。

向后兼容性

某些 Span 可能没有 mlflow.spanLogLevel 属性。这种情况可能发生在引入 Span 日志级别之前记录的追踪中，或者是通过不分配级别的第三方追踪器生成的 Span。UI 会将这些 Span 视为 DEBUG，因此它们在默认阈值下保持可见。将阈值提高到 INFO 或更高级别会连同其他 DEBUG Span 一起隐藏它们。要使特定 Span 重新可见，您可以使用 set_log_level 显式设置其级别。

API 参考

• mlflow.entities.SpanLogLevel() — 级别枚举。
• mlflow.start_span() / mlflow.start_span_no_context() / mlflow.trace() — 接受 log_level 关键字参数的公共 API。