尧图网页设计 
MLflow 仓库内 OpenTelemetry Protobuf 定义最小化 Vendor 机制、数据模型与更新维护指南【免费下载链接】mlflowThe open source AI engineering platform for agents, LLMs, and ML models. MLflow enables teams of all sizes to debug, evaluate, monitor, and optimize production-quality AI applications while controlling costs and managing access to models and data.项目地址: https://gitcode.com/GitHub_Trending/ml/mlflow本文聚焦 MLflow 开源仓库中mlflow/protos/opentelemetry/目录下的 OpenTelemetry Protocol Bufferprotobuf规范定义。MLflow 的 AI Tracing 能力以 OpenTelemetry 数据模型为底层格式但并未全量引入上游规范而是只 vendor 了一个最小够用的子集。读完本文你将掌握这三个 proto 文件各自承担的数据建模职责、它们如何被 MLflow 的 tracing 链路OTLP 导出、trace 归档、Databricks 服务对接实际消费以及如何通过update.sh安全地升级这批定义。为什么 MLflow 需要内置 OpenTelemetry Proto 定义MLflow 的 Tracing 模块 采用 OpenTelemetry 的 Span 模型来记录一次 LLM/Agent 调用链路的输入、输出、耗时与中间事件。为了保证生成的 trace 能够通过标准的 OTLPOpenTelemetry Protocol导出到任意兼容后端在TracesData结构上与 OpenTelemetry 生态直接互换与 Databricks tracking server 的 trace 存储协议保持字节级兼容MLflow 的 Python 包必须在运行时拥有对应的 protobuf 消息类。这些类的定义不能依赖用户环境是否安装了完整的opentelemetry-proto包因此 MLflow 选择将所需的最小集合直接 vendor 进仓库随 mlflow 包本体 一起分发。目录结构与包含内容mlflow/protos/opentelemetry/ ├── README.md # 本文所述的说明文档 ├── update.sh # 上游同步脚本 └── proto/ ├── common/ │ └── v1/ │ └── common.proto # 通用数据类型 ├── resource/ │ └── v1/ │ └── resource.proto # 资源属性 └── trace/ └── v1/ └── trace.proto # Trace 数据模型README 明确说明这是一个刻意的最小子集MLflow 只需要 trace追踪能力因此仅引入了上表中的三个文件。对比上游opentelemetry-proto的完整集还包括 metrics、logs、profiles、experimental 等大量目录这套 vendor 只保留了 3 个.proto源文件显著降低了仓库体积与生成代码量。数据模型详解trace.prototrace.proto 是整个 vendor 子集的核心声明了package opentelemetry.proto.trace.v1并 import 了common.proto与resource.proto两个姊妹文件。三层嵌套结构TracesData → ResourceSpans → ScopeSpans从源码结构看trace.proto#L38-L83OTLP 的 trace 数据采用三层容器嵌套消息关键字段语义TracesDatarepeated ResourceSpans resource_spans顶层数据包可批量携带来自多个资源的 span 集合ResourceSpansResource resource、repeated ScopeSpans scope_spans、string schema_url归属于同一 Resource 的 span 集合schema_url标识资源数据遵循的 schema 版本ScopeSpansInstrumentationScope scope、repeated Span spans、string schema_url归属于同一插桩作用域如某个 SDK/flavor的 span 列表ResourceSpans与ScopeSpans各带独立的schema_url字段分别约束 resource 数据与 span 数据遵循的 schema 版本见 trace.proto#L58-L64 与 L77-L82 的注释说明。中间转发节点可将多个来源的 span 批量合并进同一个TracesData这也是 OTLP 导出路径的天然形态。Span 消息一次操作的最小单元Span消息trace.proto#L88-L302描述了系统中单个组件执行的一次操作其核心字段如下字段类型说明trace_idbytes16 字节所属 trace 的唯一标识同一条 trace 的所有 span 共享全零或非 16 字节视为非法必填span_idbytes8 字节本 span 在 trace 内的唯一标识创建时分配必填parent_span_idbytes8 字节父 span 的 ID根 span 此字段必须为空trace_statestringW3C Trace Context 格式的 trace 状态namestring操作描述如qualified method name 行号语义上必须非空必填kindSpanKind枚举span 类型见下文start_time_unix_nano/end_time_unix_nanofixed64以纳秒计的 Unix 时间戳语义上要求end_time start_timeattributesrepeated KeyValue键值对属性集合键必须唯一eventsrepeated Event带时间戳的注解事件time_unix_nanonameattributeslinksrepeated Link指向同 trace 或跨 trace 其他 span 的引用如批处理场景statusStatus最终状态见下文flagsfixed32位标志字段见下文dropped_*_countuint32因超长或超量被丢弃的 attributes / events / links 计数Event、Link内嵌消息同样以KeyValue携带属性且各自维护dropped_attributes_count用于记录截断损耗——这保证了消费者能感知到数据缺失而不会被静默误导。SpanKind区分调用语义SpanKind枚举trace.proto#L152-L178用于在父子关系之外补充描述 span 的语义角色SPAN_KIND_INTERNAL默认应用内部操作非边界调用SPAN_KIND_SERVER服务端处理某个 RPC/远程请求SPAN_KIND_CLIENT向远程服务发起的请求SPAN_KIND_PRODUCER/SPAN_KIND_CONSUMER消息队列的投递与消费生产者与消费者之间通常不存在直接的关键路径时延关系。Status错误模型Status消息trace.proto#L306-L326由message人类可读错误信息与StatusCode枚举构成STATUS_CODE_UNSET默认、STATUS_CODE_OK开发者确认成功、STATUS_CODE_ERRORspan 包含错误。未显式设置 status 时按UNSET处理。SpanFlagstrace 标志位的位掩码约定SpanFlags枚举trace.proto#L342-L357定义了Span.flags位字段的解读方式第 0-7 位W3C Trace Context 的 trace flags读取用flags SPAN_FLAGS_TRACE_FLAGS_MASK第 8 位SPAN_FLAGS_CONTEXT_HAS_IS_REMOTE_MASK父 span/link 是否 remote 的信息是否已知第 9 位SPAN_FLAGS_CONTEXT_IS_REMOTE_MASK父 span/link 是否为 remote第 10-31 位保留。该枚举与flags字段均为 OpenTelemetry 协议 1.1 引入的增量特性旧生产者不会设置该字段因此消费者不能依据某标志位的缺失反推功能缺失。common.proto通用值类型common.proto 定义了一组被 trace、resource 反复复用的基础类型声明package opentelemetry.proto.common.v1AnyValuecommon.proto#L28-L40属性值的统一容器通过oneof承载string_value、bool_value、int_value、double_value、array_value、kvlist_value、bytes_value七种取值支持嵌套的数组与键值列表ArrayValuerepeated AnyValue values因 protobuf 的oneof不允许repeated字段所以单独拆成消息KeyValueList键值对列表的包装键必须唯一而像Span.attributes这种高频场景直接使用repeated KeyValue以避免多余包装层见 common.proto#L49-L53 的注释两种方式语义等价KeyValuestring keyAnyValue value是 attribute 的最小单元InstrumentationScopecommon.proto#L71-L81插桩作用域信息含name空名视为未知、version及可选 attributes用于区分不同 SDK/flavor 产生的 spanEntityRefcommon.proto#L87-L115对实体如 service、host的引用描述包含type、标识性属性键id_keys与描述性属性键description_keys目前标注为 Development 状态。resource.proto资源属性resource.proto 定义了Resource消息resource.proto#L28-L43用于描述产生遥测数据的资源实体attributes描述资源的属性集合键必须唯一通常承载 service.name、service.version、host 信息等全局属性dropped_attributes_count被丢弃的属性数量entity_refs参与该资源的实体引用列表Development 状态。在 OTLP 层级中Resource挂载在ResourceSpans.resource上与ScopeSpans中的 span 数据解耦实现一份资源属性复用多条 span的高效打包。这些 Proto 在 MLflow 源码中的实际消费vendor 进来的定义不是摆设它们在 MLflow 的 tracing 链路上被多处直接引用Databricks trace 服务协议databricks_tracing.proto在第 13 行import opentelemetry/proto/trace/v1/trace.proto并在Trace消息中直接以repeated opentelemetry.proto.trace.v1.Span spans承载 span 数据databricks_tracing.proto#L516-L519。这意味着与 Databricks tracking server 交互时trace 的线上序列化格式就是 OpenTelemetry 的 Span 结构OTLP 导出器otlp.py 从opentelemetry.proto.common.v1.common_pb2与opentelemetry.proto.resource.v1.resource_pb2导入AnyValue、ArrayValue、KeyValueList与Resourceotlp.py#L7-L8并实现_set_otel_proto_anyvalue/_decode_otel_proto_anyvalue在 Python 值与 OTel proto 值之间互转同文件还定义了 OTLP 的/v1/traces、/v1/metrics路径及 gRPC / HTTP-protobuf 两种导出协议选择Trace 归档与恢复otel_archival.py 从opentelemetry.proto.trace.v1.trace_pb2导入TracesDataotel_archival.py#L10将 span 编码为 OTLPTracesData落盘读取归档时再经Span.from_otel_proto还原。这也解释了为什么三个文件一个都不能少trace.proto提供结构common.proto提供值类型resource.proto提供资源上下文三者通过 import 关系形成完整闭环。更新流程update.sh逐步解析README 给出的升级步骤为修改update.sh中的COMMIT_SHA→ 执行脚本。结合脚本源码update.sh完整流程如下锁定上游版本COMMIT_SHA8654ab7a5a43ca25fe8046e59dcd6935c3f76de0update.sh#L13对应 opentelemetry-proto 的 v1.7.0 版本脚本以 commit 级别的 tar 包为唯一事实来源确保可复现定位脚本目录SCRIPT_DIR$(cd $(dirname ${BASH_SOURCE[0]}) pwd)后cd进入保证脚本可以从仓库任意位置调用清理旧文件rm -rf proto删除现有 vendor 目录避免残留文件造成新旧混用下载并解压curl -fsSL $ARCHIVE_URL | tar -xzf - -C $TEMP_DIR使用mktemp -d临时目录并以trap ... EXIT保证退出时清理兼容 macOS BSD tar 与 GNU tar选择性拷贝仅拷贝三个目标文件到proto/trace/v1、proto/common/v1、proto/resource/v1update.sh#L33-L36其余上游文件一律不引入。执行方式从仓库根目录./mlflow/protos/opentelemetry/update.sh维护注意事项与扩展建议保持最小子集原则README 强调若未来需要 metrics、logs 等能力应先扩展update.sh的提取列表再运行脚本而不是手动复制文件——否则下次同步会被rm -rf proto清掉校验 import 链三个文件之间存在 import 依赖trace.proto依赖common.proto、resource.proto新增文件时务必连同其 import 链一并提取版本一致性COMMIT_SHA锁定的是 opentelemetry-proto 的 commit 而非发行 tag升级后应关注SpanFlags等增量字段、schema_url语义变化及EntityRef等 Development 状态消息的演进生成代码同步.proto仅是源定义MLflow 包内实际加载的是编译后的_pb2类如opentelemetry.proto.trace.v1.trace_pb2。替换 proto 后需重新生成对应的 Python 绑定代码并运行 tracing 相关测试 验证序列化兼容性。相关源码指引定义文件trace.proto、common.proto、resource.proto、update.sh消费方databricks_tracing.proto、otlp.py、otel_archival.py上层 tracing 模块mlflow/tracing测试tests/tracing【免费下载链接】mlflowThe open source AI engineering platform for agents, LLMs, and ML models. MLflow enables teams of all sizes to debug, evaluate, monitor, and optimize production-quality AI applications while controlling costs and managing access to models and data.项目地址: https://gitcode.com/GitHub_Trending/ml/mlflow创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 MLflow 仓库内 OpenTelemetry Protobuf 定义：最小化 Vendor 机制、数据模型与更新维护指南
MLflow 仓库内 OpenTelemetry Protobuf 定义最小化 Vendor 机制、数据模型与更新维护指南【免费下载链接】mlflowThe open source AI engineering platform for agents, LLMs, and ML models. MLflow enables teams of all sizes to debug, evaluate, monitor, and optimize production-quality AI applications while controlling costs and managing access to models and data.项目地址: https://gitcode.com/GitHub_Trending/ml/mlflow本文聚焦 MLflow 开源仓库中mlflow/protos/opentelemetry/目录下的 OpenTelemetry Protocol Bufferprotobuf规范定义。MLflow 的 AI Tracing 能力以 OpenTelemetry 数据模型为底层格式但并未全量引入上游规范而是只 vendor 了一个最小够用的子集。读完本文你将掌握这三个 proto 文件各自承担的数据建模职责、它们如何被 MLflow 的 tracing 链路OTLP 导出、trace 归档、Databricks 服务对接实际消费以及如何通过update.sh安全地升级这批定义。为什么 MLflow 需要内置 OpenTelemetry Proto 定义MLflow 的 Tracing 模块 采用 OpenTelemetry 的 Span 模型来记录一次 LLM/Agent 调用链路的输入、输出、耗时与中间事件。为了保证生成的 trace 能够通过标准的 OTLPOpenTelemetry Protocol导出到任意兼容后端在TracesData结构上与 OpenTelemetry 生态直接互换与 Databricks tracking server 的 trace 存储协议保持字节级兼容MLflow 的 Python 包必须在运行时拥有对应的 protobuf 消息类。这些类的定义不能依赖用户环境是否安装了完整的opentelemetry-proto包因此 MLflow 选择将所需的最小集合直接 vendor 进仓库随 mlflow 包本体 一起分发。目录结构与包含内容mlflow/protos/opentelemetry/ ├── README.md # 本文所述的说明文档 ├── update.sh # 上游同步脚本 └── proto/ ├── common/ │ └── v1/ │ └── common.proto # 通用数据类型 ├── resource/ │ └── v1/ │ └── resource.proto # 资源属性 └── trace/ └── v1/ └── trace.proto # Trace 数据模型README 明确说明这是一个刻意的最小子集MLflow 只需要 trace追踪能力因此仅引入了上表中的三个文件。对比上游opentelemetry-proto的完整集还包括 metrics、logs、profiles、experimental 等大量目录这套 vendor 只保留了 3 个.proto源文件显著降低了仓库体积与生成代码量。数据模型详解trace.prototrace.proto 是整个 vendor 子集的核心声明了package opentelemetry.proto.trace.v1并 import 了common.proto与resource.proto两个姊妹文件。三层嵌套结构TracesData → ResourceSpans → ScopeSpans从源码结构看trace.proto#L38-L83OTLP 的 trace 数据采用三层容器嵌套消息关键字段语义TracesDatarepeated ResourceSpans resource_spans顶层数据包可批量携带来自多个资源的 span 集合ResourceSpansResource resource、repeated ScopeSpans scope_spans、string schema_url归属于同一 Resource 的 span 集合schema_url标识资源数据遵循的 schema 版本ScopeSpansInstrumentationScope scope、repeated Span spans、string schema_url归属于同一插桩作用域如某个 SDK/flavor的 span 列表ResourceSpans与ScopeSpans各带独立的schema_url字段分别约束 resource 数据与 span 数据遵循的 schema 版本见 trace.proto#L58-L64 与 L77-L82 的注释说明。中间转发节点可将多个来源的 span 批量合并进同一个TracesData这也是 OTLP 导出路径的天然形态。Span 消息一次操作的最小单元Span消息trace.proto#L88-L302描述了系统中单个组件执行的一次操作其核心字段如下字段类型说明trace_idbytes16 字节所属 trace 的唯一标识同一条 trace 的所有 span 共享全零或非 16 字节视为非法必填span_idbytes8 字节本 span 在 trace 内的唯一标识创建时分配必填parent_span_idbytes8 字节父 span 的 ID根 span 此字段必须为空trace_statestringW3C Trace Context 格式的 trace 状态namestring操作描述如qualified method name 行号语义上必须非空必填kindSpanKind枚举span 类型见下文start_time_unix_nano/end_time_unix_nanofixed64以纳秒计的 Unix 时间戳语义上要求end_time start_timeattributesrepeated KeyValue键值对属性集合键必须唯一eventsrepeated Event带时间戳的注解事件time_unix_nanonameattributeslinksrepeated Link指向同 trace 或跨 trace 其他 span 的引用如批处理场景statusStatus最终状态见下文flagsfixed32位标志字段见下文dropped_*_countuint32因超长或超量被丢弃的 attributes / events / links 计数Event、Link内嵌消息同样以KeyValue携带属性且各自维护dropped_attributes_count用于记录截断损耗——这保证了消费者能感知到数据缺失而不会被静默误导。SpanKind区分调用语义SpanKind枚举trace.proto#L152-L178用于在父子关系之外补充描述 span 的语义角色SPAN_KIND_INTERNAL默认应用内部操作非边界调用SPAN_KIND_SERVER服务端处理某个 RPC/远程请求SPAN_KIND_CLIENT向远程服务发起的请求SPAN_KIND_PRODUCER/SPAN_KIND_CONSUMER消息队列的投递与消费生产者与消费者之间通常不存在直接的关键路径时延关系。Status错误模型Status消息trace.proto#L306-L326由message人类可读错误信息与StatusCode枚举构成STATUS_CODE_UNSET默认、STATUS_CODE_OK开发者确认成功、STATUS_CODE_ERRORspan 包含错误。未显式设置 status 时按UNSET处理。SpanFlagstrace 标志位的位掩码约定SpanFlags枚举trace.proto#L342-L357定义了Span.flags位字段的解读方式第 0-7 位W3C Trace Context 的 trace flags读取用flags SPAN_FLAGS_TRACE_FLAGS_MASK第 8 位SPAN_FLAGS_CONTEXT_HAS_IS_REMOTE_MASK父 span/link 是否 remote 的信息是否已知第 9 位SPAN_FLAGS_CONTEXT_IS_REMOTE_MASK父 span/link 是否为 remote第 10-31 位保留。该枚举与flags字段均为 OpenTelemetry 协议 1.1 引入的增量特性旧生产者不会设置该字段因此消费者不能依据某标志位的缺失反推功能缺失。common.proto通用值类型common.proto 定义了一组被 trace、resource 反复复用的基础类型声明package opentelemetry.proto.common.v1AnyValuecommon.proto#L28-L40属性值的统一容器通过oneof承载string_value、bool_value、int_value、double_value、array_value、kvlist_value、bytes_value七种取值支持嵌套的数组与键值列表ArrayValuerepeated AnyValue values因 protobuf 的oneof不允许repeated字段所以单独拆成消息KeyValueList键值对列表的包装键必须唯一而像Span.attributes这种高频场景直接使用repeated KeyValue以避免多余包装层见 common.proto#L49-L53 的注释两种方式语义等价KeyValuestring keyAnyValue value是 attribute 的最小单元InstrumentationScopecommon.proto#L71-L81插桩作用域信息含name空名视为未知、version及可选 attributes用于区分不同 SDK/flavor 产生的 spanEntityRefcommon.proto#L87-L115对实体如 service、host的引用描述包含type、标识性属性键id_keys与描述性属性键description_keys目前标注为 Development 状态。resource.proto资源属性resource.proto 定义了Resource消息resource.proto#L28-L43用于描述产生遥测数据的资源实体attributes描述资源的属性集合键必须唯一通常承载 service.name、service.version、host 信息等全局属性dropped_attributes_count被丢弃的属性数量entity_refs参与该资源的实体引用列表Development 状态。在 OTLP 层级中Resource挂载在ResourceSpans.resource上与ScopeSpans中的 span 数据解耦实现一份资源属性复用多条 span的高效打包。这些 Proto 在 MLflow 源码中的实际消费vendor 进来的定义不是摆设它们在 MLflow 的 tracing 链路上被多处直接引用Databricks trace 服务协议databricks_tracing.proto在第 13 行import opentelemetry/proto/trace/v1/trace.proto并在Trace消息中直接以repeated opentelemetry.proto.trace.v1.Span spans承载 span 数据databricks_tracing.proto#L516-L519。这意味着与 Databricks tracking server 交互时trace 的线上序列化格式就是 OpenTelemetry 的 Span 结构OTLP 导出器otlp.py 从opentelemetry.proto.common.v1.common_pb2与opentelemetry.proto.resource.v1.resource_pb2导入AnyValue、ArrayValue、KeyValueList与Resourceotlp.py#L7-L8并实现_set_otel_proto_anyvalue/_decode_otel_proto_anyvalue在 Python 值与 OTel proto 值之间互转同文件还定义了 OTLP 的/v1/traces、/v1/metrics路径及 gRPC / HTTP-protobuf 两种导出协议选择Trace 归档与恢复otel_archival.py 从opentelemetry.proto.trace.v1.trace_pb2导入TracesDataotel_archival.py#L10将 span 编码为 OTLPTracesData落盘读取归档时再经Span.from_otel_proto还原。这也解释了为什么三个文件一个都不能少trace.proto提供结构common.proto提供值类型resource.proto提供资源上下文三者通过 import 关系形成完整闭环。更新流程update.sh逐步解析README 给出的升级步骤为修改update.sh中的COMMIT_SHA→ 执行脚本。结合脚本源码update.sh完整流程如下锁定上游版本COMMIT_SHA8654ab7a5a43ca25fe8046e59dcd6935c3f76de0update.sh#L13对应 opentelemetry-proto 的 v1.7.0 版本脚本以 commit 级别的 tar 包为唯一事实来源确保可复现定位脚本目录SCRIPT_DIR$(cd $(dirname ${BASH_SOURCE[0]}) pwd)后cd进入保证脚本可以从仓库任意位置调用清理旧文件rm -rf proto删除现有 vendor 目录避免残留文件造成新旧混用下载并解压curl -fsSL $ARCHIVE_URL | tar -xzf - -C $TEMP_DIR使用mktemp -d临时目录并以trap ... EXIT保证退出时清理兼容 macOS BSD tar 与 GNU tar选择性拷贝仅拷贝三个目标文件到proto/trace/v1、proto/common/v1、proto/resource/v1update.sh#L33-L36其余上游文件一律不引入。执行方式从仓库根目录./mlflow/protos/opentelemetry/update.sh维护注意事项与扩展建议保持最小子集原则README 强调若未来需要 metrics、logs 等能力应先扩展update.sh的提取列表再运行脚本而不是手动复制文件——否则下次同步会被rm -rf proto清掉校验 import 链三个文件之间存在 import 依赖trace.proto依赖common.proto、resource.proto新增文件时务必连同其 import 链一并提取版本一致性COMMIT_SHA锁定的是 opentelemetry-proto 的 commit 而非发行 tag升级后应关注SpanFlags等增量字段、schema_url语义变化及EntityRef等 Development 状态消息的演进生成代码同步.proto仅是源定义MLflow 包内实际加载的是编译后的_pb2类如opentelemetry.proto.trace.v1.trace_pb2。替换 proto 后需重新生成对应的 Python 绑定代码并运行 tracing 相关测试 验证序列化兼容性。相关源码指引定义文件trace.proto、common.proto、resource.proto、update.sh消费方databricks_tracing.proto、otlp.py、otel_archival.py上层 tracing 模块mlflow/tracing测试tests/tracing【免费下载链接】mlflowThe open source AI engineering platform for agents, LLMs, and ML models. MLflow enables teams of all sizes to debug, evaluate, monitor, and optimize production-quality AI applications while controlling costs and managing access to models and data.项目地址: https://gitcode.com/GitHub_Trending/ml/mlflow创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考