Trace Concepts

什么是 Trace？

Trace 是一种可观测性技术，它捕获请求在您的应用程序中的完整执行流程。与捕获离散事件的传统日志记录不同，Trace 创建了一个详细的系统数据流图，记录了每个操作、转换和决策点。

在 GenAI 应用程序的上下文中，Trace 变得至关重要，因为这些系统涉及复杂的多步工作流程，如果没有对其执行情况的完全可见性，将难以调试和优化。

工具调用代理 (Tool Calling Agent) 的 Trace 示例

用例

调试

Trace 提供了对 GenAI 库抽象层之下发生情况的深入洞察，帮助您精确地识别问题发生的地点。

质量检查

Trace 提供了一种统一的方式来跟踪输出质量。您可以手动审查在 Trace 中记录的输出，并向 Trace 添加反馈，以表明输出的质量。

生产监控

Trace 在每一步捕获延迟和 token 使用量等关键指标，帮助您识别瓶颈，监控效率，并找到优化机会。

数据集收集

生产系统的 Trace 捕获了用于构建高质量数据集的完美数据，具有用于检索器和工具等内部组件的精确细节。

核心结构

高层次上，MLflow Trace 由两个主要对象组成

TraceInfo：元数据，有助于解释 Trace 的来源、Trace 的状态、总执行时间等信息。这包括提供 Trace 额外上下文的标签，例如用户、会话和开发者提供的键:值对。标签可用于搜索或过滤 Trace。

TraceData：实际的有效负载，其中包含 instrumented 的 Span 对象，这些对象捕获了您的应用程序从输入到输出的分步执行情况。

MLflow Trace 架构概述

MLflow Trace 设计为与 OpenTelemetry 规范兼容，OpenTelemetry 是可观测性领域广泛采用的行业标准。这确保了互操作性，并允许 MLflow Trace 与其他 OpenTelemetry 兼容系统进行导出和使用。MLflow 通过为 Generative AI 用例定义特定的结构和属性，增强了基本的 OpenTelemetry Span 模型，从而提供了更丰富的上下文以及对质量和性能更深入的洞察。

TraceInfo：元数据和上下文

MLflow 追踪功能的 TraceInfo 旨在提供关键数据的轻量级快照，以了解整个 Trace。在 Python SDK 中，TraceInfo 被设计为一个数据类对象，其中包含有关 Trace 的元数据。

此元数据包括有关 Trace 的来源、状态以及在使用 mlflow.search_traces() 时有助于检索和过滤 Trace 的各种其他数据，以及用于在 MLflow UI 中导航 Trace 的数据。

字段	类型	描述
trace_id	str	Trace 的主标识符。
trace_location	TraceLocation	Trace 存储的位置，表示为 TraceLocation 对象。MLflow 目前支持 MLflow Experiment 作为 Trace 位置。
request_time	int	Trace 的开始时间（以毫秒为单位）。
state	TraceState	Trace 的状态，表示为 TraceState 枚举。可以是 OK、ERROR、IN_PROGRESS、STATE_UNSPECIFIED 之一。
execution_duration	int	Trace 的持续时间（以毫秒为单位）。
request_preview	Optional[str]	对模型/代理的请求，相当于根 Span 的输入，但已 JSON 编码并且可能会被截断。
response_preview	Optional[str]	来自模型/代理的响应，相当于根 Span 的输出，但已 JSON 编码并且可能会被截断。
client_request_id	Optional[str]	客户端提供的与 Trace 关联的请求 ID。这可用于标识产生 Trace 的外部系统中的 Trace/请求，例如 Web 应用程序中的会话 ID。
trace_metadata	dict[str, str]	与 Trace 关联的键值对。它们设计用于不可变值，例如与 Trace 关联的 run ID。
tags	dict[str, str]	标签是键值对，可用于注解 Trace。它们设计用于可变值，可以在 Trace 通过 MLflow UI 或 API 创建后进行更新，并有助于对 Trace 进行分组和高效查询。有关标签使用方法的更多详细信息，请访问设置 Trace 标签。

TraceData：Span 的容器

MLflow 的 TraceData 对象，可通过 trace.data 访问，是 Span 对象的容器。这是存储实际执行细节的地方，包括请求和响应数据、每个步骤的延迟、输入到 LLM 的输入和输出消息、从向量存储检索的文档、工具调用参数等。

Trace 中的 Span 通过父子连接形成一个层次结构。每个 Span 详细说明了一个特定的工作单元。

例如，下图说明了一组在 Trace 中以树状结构组织的 Span。每条线代表一个 Span，树状结构由线之间的曲线边形成。例如，根 Span 是“agent”，它连接到三个子 Span：2 个 LLM 调用和 1 个工具处理。

要了解有关 Span 对象及其模式的更多信息，请继续阅读Span Concepts 页面。

存储布局

TraceInfo 是一个轻量级的元数据对象，因此可以直接存储在关系数据库中。例如，如果您在 PostgreSQL 等 SQL 数据库上运行 MLflow Tracking Server，TraceInfo 将存储在 trace 表中的单行中，并支持带有索引的高效查询。例如，TraceInfo 对象中包含的数据用于填充 MLflow Tracking UI 中的 trace 视图页面。

TraceData（Spans）与 TraceInfo 相比是相对较大的对象，因为它包含了每个执行步骤的丰富信息，例如 LLM 调用输入的消息完整历史记录。因此，MLflow 将它们存储在 artifact 存储中，而不是数据库中。这使您能够以更低的成本处理大量 Trace，并最大限度地减少对 Trace 的典型过滤和分组操作性能的影响。