mlflow.tracing

注意

mlflow.tracing 命名空间仅包含一些用于管理跟踪的实用函数。MLflow Tracing 的主要入口点是 Tracing Fluent APIs，它们直接在 mlflow 命名空间下定义，或者是低级的 Tracing Client APIs

mlflow.tracing.configure(span_processors: list[typing.Callable[[ForwardRef('LiveSpan')], NoneType]] | None = None) → mlflow.tracing.config.TracingConfigContext[source]

注意

实验性：此功能可能在将来的发布中更改或在不另行通知的情况下被移除。

配置 MLflow 跟踪。可以作为函数或上下文管理器使用。

仅更新显式提供的参数，其余保持不变。

Parameters

span_processors – 在导出之前处理 span 的函数列表。 这有助于从 span 中筛选/屏蔽特定属性以防止记录敏感数据或减少 span 的大小。 每个函数必须接受一个类型为 LiveSpan 的单个参数，并且不应返回任何值。当提供多个函数时，它们会按提供的顺序依次应用。

Returns

用于临时配置更改的上下文管理器。

当作为函数使用时，配置更改会持续生效。 当作为上下文管理器使用时，退出时更改会被还原。

Return type

TracingConfigContext

示例

def pii_filter(span):
    """Example PII filter that masks sensitive data in span attributes."""
    # Mask sensitive inputs
    if inputs := span.inputs:
        for key, value in inputs.items():
            if "password" in key.lower() or "token" in key.lower():
                span.set_inputs({**inputs, key: "[REDACTED]"})

    # Mask sensitive outputs
    if outputs := span.outputs:
        if isinstance(outputs, dict):
            for key in outputs:
                if "secret" in key.lower():
                    outputs[key] = "[REDACTED]"
            span.set_outputs(outputs)

    # Mask sensitive attributes
    for attr_key in list(span.attributes.keys()):
        if "api_key" in attr_key.lower():
            span.set_attribute(attr_key, "[REDACTED]")

# Permanent configuration change
mlflow.tracing.configure(span_processors=[pii_filter])

# Temporary configuration change
with mlflow.tracing.configure(span_processors=[pii_filter]):
    # PII filtering enabled only in this block
    pass
mlflow.tracing.disable()[source]

禁用跟踪。

注意

此函数将OpenTelemetry设置为使用NoOpTracerProvider，并实际禁用所有追踪操作。

示例：

import mlflow


@mlflow.trace
def f():
    return 0


# Tracing is enabled by default
f()
assert len(mlflow.search_traces()) == 1

# Disable tracing
mlflow.tracing.disable()
f()
assert len(mlflow.search_traces()) == 1
mlflow.tracing.disable_notebook_display()[source]

禁用在笔记本输出单元格中显示 MLflow Trace UI。调用 mlflow.tracing.enable_notebook_display() 可重新启用显示。

mlflow.tracing.enable()[source]

启用跟踪。

示例：

import mlflow


@mlflow.trace
def f():
    return 0


# Tracing is enabled by default
f()
assert len(mlflow.search_traces()) == 1

# Disable tracing
mlflow.tracing.disable()
f()
assert len(mlflow.search_traces()) == 1

# Re-enable tracing
mlflow.tracing.enable()
f()
assert len(mlflow.search_traces()) == 2
mlflow.tracing.enable_notebook_display()[source]

在笔记本输出单元中启用 MLflow Trace UI。该显示默认开启，当执行以下任一操作时将显示 Trace UI：

要禁用，请调用 mlflow.tracing.disable_notebook_display()。

mlflow.tracing.reset()[source]

重置指示 MLflow 跟踪器提供程序是否已初始化的标志。这可确保在下一次执行跟踪操作时重新初始化跟踪器提供程序。

mlflow.tracing.set_destination(destination: mlflow.tracing.destination.TraceDestination)[source]

注意

实验性：此功能可能在将来的发布中更改或在不另行通知的情况下被移除。

设置一个自定义的 span 目的地，MLflow 将向其导出跟踪。

由此函数指定的目标将优先于其他配置，例如 tracking URI、OTLP environment variables。

默认情况下，指定的目标是全局生效的。要在多线程应用中为每个线程设置不同的目标，请将环境变量 ‘MLFLOW_ENABLE_THREAD_LOCAL_TRACING_DESTINATION’ 设置为 ‘true’,

要重置目标，请调用 mlflow.tracing.reset() 函数。

Parameters

destination – 一个 TraceDestination 对象，用于指定跟踪数据的目的地。

示例

import mlflow
from mlflow.tracing.destination import MlflowExperiment

# Setting the destination to an MLflow experiment with ID "123"
mlflow.tracing.set_destination(MlflowExperiment(experiment_id="123"))

# Reset the destination (to an active experiment as default)
mlflow.tracing.reset()
mlflow.tracing.set_span_chat_tools(span: LiveSpan, tools: list[ChatTool])[source]

在指定的 span 上设置 mlflow.chat.tools 属性。该属性在用户界面中使用，也被消费跟踪数据的下游应用程序使用，例如 MLflow evaluate。

Parameters

  • span – 要向其添加属性的 LiveSpan

  • tools – 一个标准化聊天工具定义的列表（详情请参考spec）

示例：

import mlflow
from mlflow.tracing import set_span_chat_tools

tools = [
    {
        "type": "function",
        "function": {
            "name": "add",
            "description": "Add two numbers",
            "parameters": {
                "type": "object",
                "properties": {
                    "a": {"type": "number"},
                    "b": {"type": "number"},
                },
                "required": ["a", "b"],
            },
        },
    }
]


@mlflow.trace
def f():
    span = mlflow.get_current_active_span()
    set_span_chat_tools(span, tools)
    return 0


f()
class mlflow.tracing.destination.Databricks(experiment_id: Optional[str] = None, experiment_name: Optional[str] = None)[source]

注意

实验性：此类可能在将来的版本中更改或在未发出警告的情况下被移除。

表示 Databricks 跟踪服务器的目标。

在 mlflow.tracing.set_destination() 函数中设置此目标后，MLflow 将把跟踪日志记录到指定的实验。

如果未指定 experiment_id 或 experiment_name，则在创建 traces 时的某个活动实验将被用作目标。如果两者都指定，则它们必须指向同一个实验。

experiment_id

用于记录跟踪信息的实验 ID。

Type

str | None

experiment_name

要将跟踪信息记录到的实验名称。

Type

str | None

property type: str

目标的类型。

class mlflow.tracing.destination.MlflowExperiment(experiment_id: Optional[str] = None)[source]

注意

实验性：此类可能在将来的版本中更改或在未发出警告的情况下被移除。

表示一个 MLflow 实验的目标。

通过在 mlflow.tracing.set_destination() 函数中设置此目标，MLflow 会将跟踪记录到指定的实验。

experiment_id

要记录跟踪的实验 ID。如果未指定，将使用当前活动的实验。

Type

str | None

property type: str

Type of the destination.

class mlflow.tracing.destination.TraceDestination[source]

注意

实验性：此类可能在将来的版本中更改或在未发出警告的情况下被移除。

用于指定追踪数据目标的配置对象。

property type: str

目标的类型。