Vector metric_to_log 转换器把指标事件转为日志事件完整指南【免费下载链接】vectorA high-performance observability data pipeline.项目地址: https://gitcode.com/GitHub_Trending/vect/vector导读metric_to_log是 Vector 观测数据管道observability data pipeline中的一种 transform转换器用于将指标metric事件转换为日志log事件从而让下游只支持日志的组件也能接收指标数据。本文基于当前仓库中该组件的官方文档website/content/en/docs/reference/configuration/transforms/metric_to_log.md与源码src/transforms/metric_to_log.rs完整讲解其配置参数、转换后的字段结构、六种指标类型counter/gauge/set/distribution/histogram/summary的转换行为、标签tag编码策略、日志命名空间差异以及可复制的 YAML 配置示例。读完本文你将掌握如何把 Prometheus、StatsD 等来源的指标统一转化为日志字段接入 Elasticsearch、Loki 等日志型下游。一、metric_to_log 是什么根据组件元数据website/cue/reference/components/transforms/metric_to_log.cue该组件titleMetric to Logdescription将指标事件转换为日志事件常用于把指标发送给仅支持日志的下游组件。classesdevelopment: stable稳定egress_method: stream流式输出stateful: false无状态。featuresconvert转换。输入仅接受指标且六种指标类型全部支持counter、distribution、gauge、histogram、set、summary不接受 logs 与 traces。输出唯一输出为转换后的log事件。在源码中该组件通过#[configurable_component(transform(metric_to_log, Convert metric events to log events.))]注册src/transforms/metric_to_log.rs并声明input()返回Input::metric()、outputs()返回DataType::Log即“指标进、日志出”的单输入单输出无状态函数式转换器。它还实现了enable_concurrency() - true意味着可以并发执行适合高吞吐场景。二、配置参数详解metric_to_log的全部配置项来自生成文档 website/cue/reference/components/transforms/generated/metric_to_log.cue 与结构体定义 src/transforms/metric_to_log.rs参数类型必填默认值说明host_tagstring否无见下文指定指标中哪一个 tag 作为来源主机若存在其值会被写入生成日志的host字段字段名遵循全局log_schema.host_key选项。示例值host、hostnametimezonestring否继承全局timezone对不含显式时区的时间戳转换所用的时区名称覆盖全局设置。取值可为 TZ 数据库中的任意名称或local系统本地时间。示例值local、America/New_York、EST5EDTmetric_tag_valuesstring否single控制指标 tag 值的编码方式枚举见下文log_namespacebool否继承全局设置日志命名空间覆盖全局设置文档中标记为 hidden一般无需显式配置1.host_tag的默认行为从源码看MetricToLog::new中当host_tag未显式指定时会默认使用全局日志 schema 的host_key并加上tags前缀src/transforms/metric_to_log.rshost_tag: host_tag.map_or( log_schema().host_key().cloned().map(|mut key| { key.push_front_field(tags); key }), |host| Some(owned_value_path!(tags, host)), ),也就是说若不配置host_tagVector 会尝试从tags.全局host_key中取主机名若显式配置为host则从tags.host取。2.timezone的作用时机timezone只在Legacy 日志命名空间下、且指标时间戳字符串不含显式时区时才生效见下文“日志命名空间”小节。源码在转换时通过Conversion::Timestamp(self.timezone)将timestamp字段转换为时间类型src/transforms/metric_to_log.rs。3.metric_tag_values三种编码模式该枚举定义于 lib/codecs/src/lib.rs默认值为Singlesingle默认tag 值以单个字符串暴露与引入该配置项之前的行为一致。多值 tag 只显示最后一个被赋予的值null 值被忽略。full所有 tag 以数组形式暴露元素为字符串或 null与native_jsoncodec 的编码一致。auto按 tag 的底层形态编码单值 tag 编码为字符串多值 tag 编码为数组长度为 1 的数组在往返时退化为标量若需强制数组形态请使用full。在转换时若metric_tag_values Single会先调用metric.reduce_tags_to_single()src/transforms/metric_to_log.rs该方法将 tag 集缩减为单值并丢弃 null若结果为空则整体删除 tag 集合lib/vector-core/src/event/metric/mod.rs。三、转换后的日志字段结构转换过程的核心实现在transform_onesrc/transforms/metric_to_log.rs先将Metric通过serde_json::to_value序列化为 JSON 对象再把每个字段转换为 Vector 的日志字段最后依据日志命名空间做字段微调。因此转换后的日志事件包含以下通用字段字段类型说明namestring指标名称namespacestring可选指标命名空间仅当存在时tagsobject指标标签键值对形式受metric_tag_values影响kindstring指标类型absolute或incrementaltimestamptimestamp 或 string指标时间戳Legacy 命名空间下转换为时间类型Vector 命名空间下保留原样counter/gauge/set/distribution/aggregated_histogram/aggregated_summary/sketchobject按实际指标类型出现的取值结构见下节输出的 schema 定义schema_definitionsrc/transforms/metric_to_log.rs明确声明了上述字段的存在性与类型可作为下游 schema 校验与 VRL 编程的依据。各指标类型的取值结构指标值枚举定义于 lib/vector-core/src/event/metric/value.rs序列化时统一使用snake_case命名counter{value: f64}— 只能增加或归零的累计数值。gauge{value: f64}— 可任意上下波动的单一数值。set{values: [string, ...]}— 无序唯一值集合。distribution{samples: [{value: f64, rate: u64}, ...], statistic: histogram|summary}— 未聚合的观测样本集合。aggregated_histogram{buckets: [{upper_limit: f64, count: u64}, ...], count: u64, sum: f64}— 分桶计数直方图。aggregated_summary{quantiles: [{quantile: f64, value: f64}, ...], count: u64, sum: f64}— 分位数摘要。sketch任意结构DD 草图等尚未结构化拆解的指标值。注意MetricValue枚举使用了#[serde(rename_all snake_case)]lib/vector-core/src/event/metric/value.rs所以AggregatedHistogram序列化为aggregated_histogramAggregatedSummary序列化为aggregated_summary。四、完整配置示例与转换效果官方元数据中提供了一个示例website/cue/reference/components/transforms/metric_to_log.cue下面将其展开为可复制的 YAML 配置与输入输出对照。YAML 配置transforms: my_transform_id: type: metric_to_log inputs: - my_source_or_transform_id host_tag: host参数说明type固定为metric_to_log。inputs上游组件 ID必须产出指标metric事件。host_tag可选指定将哪个 tag 提升为日志的host字段。如需调整 tag 编码与时区可扩展为transforms: my_transform_id: type: metric_to_log inputs: - my_source_or_transform_id host_tag: hostname timezone: America/New_York metric_tag_values: full输入指标histogram 示例{ kind: absolute, name: histogram, timestamp: 2020-08-01T21:15:4700:00, tags: { host: my.host.com, code: 200 }, histogram: { buckets: [ {upper_limit: 1.0, count: 10}, {upper_limit: 2.0, count: 20} ], count: 30, sum: 50.0 } }输出日志{ name: histogram, timestamp: 2020-08-01T21:15:4700:00, host: my.host.com, tags: { code: 200 }, kind: absolute, histogram: { buckets: [ {count: 10, upper_limit: 1.0}, {count: 20, upper_limit: 2.0} ], count: 30, sum: 50.0 } }注意两点转换细节host字段提升由于配置了host_tag: host原指标 tag 中的host: my.host.com被提升为日志顶层host字段并从未转换的tags中移除源码中通过log.remove_prune((PathPrefix::Event, host_tag), true)实现src/transforms/metric_to_log.rs。输出中tags只剩下code。bucket 字段顺序JSON 对象键序不保证但键名count/upper_limit与输入完全一致源码中将 serde Value 逐字段插入日志不改变键名。五、六种指标类型的测试验证仓库源码自带完整的单元测试src/transforms/metric_to_log.rs逐一验证了六种指标类型的转换结果可当作“行为规范”阅读测试函数验证内容transform_countercounter 转换为counter.value、kind、name、tags.*、timestamp且host来自tags.hosttransform_gaugegauge 转换为gauge.value、kind、name、timestamptransform_setset 转换为set.values[0]、set.values[1]等数组元素字段transform_distributiondistribution 转换为distribution.samples[i].value、distribution.samples[i].rate、distribution.statistictransform_histogramhistogram 转换为aggregated_histogram.buckets[i].upper_limit、buckets[i].count、count、sumtransform_summarysummary 转换为aggregated_summary.quantiles[i].quantile、quantiles[i].value、count、sum例如transform_histogram断言输出字段src/transforms/metric_to_log.rs与上文第三节的字段结构完全一致可作为编写下游过滤、VRL 脚本的字段路径参考。此外还有两组基于 proptest 的属性测试transform_tag_single_encoding验证Single模式下无论原始 tag 集如何结果要么是单个字符串要么不存在。transform_tag_full_encoding验证Full模式下空集合 → 无 tag单值 → 标量多值 → 数组src/transforms/metric_to_log.rs。这两组测试说明metric_tag_values的编码行为是经过穷举式随机验证的可以放心依赖。六、日志命名空间Legacy 与 Vector 的差异log_namespace决定转换后字段的呈现方式。源码在transform_one与schema_definition中分别处理了两种命名空间Legacy 命名空间默认timestamp会被从原位置取出通过Conversion::Timestamp(self.timezone)转换为时间类型若原字符串不含时区则应用timezone配置再写入全局log_schema.timestamp_key对应的字段若解析失败则回退为当前 UTC 时间src/transforms/metric_to_log.rs。host_tag匹配到的 tag 会被提升为log_schema.host_key字段。schema 中timestamp字段类型为timestamphost字段为可选 bytessrc/transforms/metric_to_log.rs。Vector 命名空间timestamp字段保持原样字符串形式不做时间类型转换。会在 metadata 中写入vector空对象作为命名空间标记注释说明“一旦指标支持命名空间即可移除”src/transforms/metric_to_log.rs。schema 中timestamp为可选 bytessrc/transforms/metric_to_log.rs。如何切换全局配置方式schema: log_namespace: true # 启用 Vector 命名空间false 或省略为 Legacy也可在 transform 上单独设置log_namespace覆盖全局该参数在文档中标记为 hidden通常建议通过全局配置控制。七、错误处理与可观测性当指标无法序列化为 JSON 时理论上仅出现在内部数据结构异常时转换会失败并触发内部事件MetricToLogSerializeErrorsrc/internal_events/metric_to_log.rs。该内部事件记录error_type ENCODER_FAILED、stage PROCESSING的日志递增ComponentErrorsTotal计数器以UNINTENTIONAL类型上报ComponentEventsDropped { count: 1 }即该指标事件被丢弃。对应源码中的处理是serde_json::to_value(metric).map_err(|error| emit!(MetricToLogSerializeError { error }))失败时返回None该事件不会向下游传递src/transforms/metric_to_log.rs。八、典型应用场景与最佳实践场景一指标送日志型后端当你的下游只接受日志如某些日志聚合平台、SIEM可用 metric_to_log 将 Prometheus/StatsD 指标转为日志后发送。典型链路sources: statsd: type: statsd address: 0.0.0.0:8125 mode: server transforms: metrics_to_logs: type: metric_to_log inputs: - statsd host_tag: host metric_tag_values: single sinks: elasticsearch: type: elasticsearch inputs: - metrics_to_logs endpoints: - http://elasticsearch:9200场景二指标与日志统一管道metric_to_log 是无状态、可并发enable_concurrency() - true的转换器可将指标事件无损地“降维”为日志字段便于后续用 VRL 过滤、脱敏、富化后再分发。最佳实践要点善用host_tag若指标带有主机维度的 tag优先配置它转换后主机信息会进入标准host字段便于下游按主机检索。按需选择 tag 编码默认single与历史行为一致兼容性最好若存在多值 tag 且需保留全部信息用full追求紧凑可用auto。统一时区若日志系统要求统一时区通过全局timezone或本组件timezone保证转换一致性。注意 timestamp 差异Legacy 命名空间下时间戳为时间类型Vector 命名空间下为字符串下游字段类型映射需与此对应。验证字段路径编写下游过滤或 VRL 脚本前参考第五节测试断言中的字段路径如aggregated_histogram.buckets[i].upper_limit避免写错。九、小结metric_to_log是 Vector 中一个轻量、稳定的指标→日志转换器它接受全部六种指标类型输出单一日志事件字段结构与指标内部模型一一对应。其行为由host_tag、timezone、metric_tag_values、log_namespace四个参数控制并通过源码测试、属性测试全面验证。当你的架构中下游仅支持日志时该组件是打通“指标采集 → 日志输出”链路的最直接手段。延伸阅读组件元数据与示例website/cue/reference/components/transforms/metric_to_log.cue生成文档参数细节website/cue/reference/components/transforms/generated/metric_to_log.cue核心实现src/transforms/metric_to_log.rs内部事件src/internal_events/metric_to_log.rs指标值模型lib/vector-core/src/event/metric/value.rstag 编码枚举lib/codecs/src/lib.rs转换器注册入口src/transforms/mod.rs【免费下载链接】vectorA high-performance observability data pipeline.项目地址: https://gitcode.com/GitHub_Trending/vect/vector创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考