Vector 日志事件Log Event数据模型完全解析Schema 中立、字段类型与时区语义【免费下载链接】vectorA high-performance observability data pipeline.项目地址: https://gitcode.com/GitHub_Trending/vect/vector本文基于 observability 数据管道项目 Vector 的官方架构文档系统讲解 Vector 内部日志事件Log Event的统一数据模型事件以 JSON 兼容的嵌套结构表示字段类型与边界如何定义、时间戳如何被摄取与强转、时区语义如何处理以及通过log_schema全局配置自定义消息、时间戳、主机等关键字段的实现原理。读完本文你将掌握 Vector 日志管道的核心抽象并能准确配置[log_schema]段与remap转换让日志字段在你的拓扑中按预期流转。一个日志事件的表示方式Vector 中的日志事件log event本质上是一个结构化的数据对象。官方文档给出了一个以 JSON 呈现的典型示例{ log: { custom: field, host: my.host.com, message: Hello world, timestamp: 2020-11-01T21:15:4700:00 } }这个例子直观地展示了三点核心信息顶层有一个log命名空间事件被包裹在log键下与 Vector 的metric、trace事件类型相区分。字段完全自由除了message、host、timestamp这类被 Vector 赋予语义的字段外任何自定义字段如custom都可以直接附加。时间戳是带时区的 ISO 8601 字符串2020-11-01T21:15:4700:00明确携带了00:00的 UTC 偏移。从源码看这一 JSON 形态与 Vector 内部LogEvent的序列化行为一致——事件字段以键值对Key-Value形式存储可被任意 source、transform、sink 按路径读写。SchemaVector 的 Schema 中立原则什么是 SchemaLog schema日志模式是 Vector 用来统一处理事件字段、并指定哪些字段承载特定数据的约定。在 lib/vector-core/src/config/log_schema.rs 中LogSchema被定义为A log schema is used by Vector not only to uniformly process the fields of an event, but also to specify which fields should hold specific data that is also set by Vector once an event is flowing through a topology.即LogSchema既用于统一处理事件字段也用于指定哪些字段承载特定语义数据例如哪一个是消息、哪一个是时间戳这些字段由 Vector 在事件流经拓扑时自动写入。Vector 是 Schema 中立的官方文档明确指出Vector is schema-neutral and doesnt require any specific schema. This ensures that Vector can work with a variety of schemas, supporting legacy schemas as well as future schemas.Vector 不强制任何特定 Schema因此既能对接既有legacy的日志格式也能适应未来可能出现的新格式。这是 Vector 数据管道能够什么都能接、什么都能发的根本原因——你不必为了接入 Vector 而改造上游日志结构只需要通过配置告诉 Vector 哪个字段是什么即可。LogSchema的五个内置字段与默认值LogSchema结构体lib/vector-core/src/config/log_schema.rs定义了五个可配置的语义字段字段默认值语义message_keymessage事件的消息字段通常承载原始日志行timestamp_keytimestamp事件的时间戳字段host_keyhost发送消息的主机真实主机或容器取决于 sourcesource_type_keysource_type产生事件的 Vector source 标识metadata_keymetadata事件元数据例如remaptransform 在出错或中止时的注解这些默认值定义在源码常量中lib/vector-core/src/config/log_schema.rs以及对应的default_*_key()方法中lib/vector-core/src/config/log_schema.rs并通过#[serde(default ...)]属性实现不配置即使用默认值的行为。如何自定义log_schema你可以通过全局配置段[log_schema]覆盖这些默认字段名。src/config/mod.rs中的测试用例展示了其配置形态src/config/mod.rs[log_schema] message_key message timestamp_key timestamp例如如果上游系统约定使用msg和ts作为消息与时间字段你可以这样配置[log_schema] message_key msg timestamp_key ts之后 Vector 内部对消息时间戳的读写如 source 自动填充、sink 序列化都会落到你指定的路径上。全局 schema 的加载机制LogSchema通过全局单例在进程内生效相关逻辑同样位于 lib/vector-core/src/config/log_schema.rsstatic LOG_SCHEMA: OnceLockLogSchema保存配置加载后的全局 schemainit_log_schema(log_schema, deny_if_set)在配置阶段写入全局 schema若deny_if_set为true且已被设置过则会 panic防止重复初始化log_schema()返回全局 schema 引用未初始化时回退到不变的LogSchema::default()。源码注释明确要求组件应当始终通过log_schema()获取 schema而不是直接使用LogSchema::default()因为配置后的值可能与默认值不同。支持的数据类型Vector 日志事件的字段值支持以下类型集合覆盖了 JSON 及主流日志格式的全部需要字符串Strings字符串为UTF-8 兼容长度仅受可用系统内存限制。任何合法的 UTF-8 文本包括多语言日志、Emoji、二进制转义后的内容都可以安全存放。整数Integers整数为有符号 64 位signed integer up to 64 bits即覆盖i64的取值范围-9223372036854775808到9223372036854775807。超出该范围的数值无法以整数类型表示。浮点数Floats浮点数为64 位 IEEE 754双精度浮点数double与多数语言中的double/f64一致。官方文档明确引用 IEEE 754 标准。布尔值Booleans布尔值表示二元的true/false用于标志位、状态开关等场景。时间戳Timestamps时间戳以 Rust 的DateTime结构体 表示并且统一存储为 UTC。这意味着无论上游时区如何事件在 Vector 内部流转时时间基准一致不会因服务器时区差异产生歧义。时间戳强转Timestamp Coercion存在一些格式没有正式时间戳定义最典型的就是 JSON——JSON 中时间只能以字符串或整数原始形式存在。此时 Vector 会按原始形式字符串或整数摄取该字段而不会擅自假设其含义。如果你需要把它当作时间戳使用可以通过remaptransform 结合 VRL 的parse_timestamp函数进行强转coerce。这是一个典型的配置示例[transforms.coerce_ts] type remap inputs [in] source parsed parse_timestamp!(.timestamp, format: %Y-%m-%dT%H:%M:%S%:z) .ts parsed 其中parse_timestamp!会按给定格式解析字符串成功则返回timestamp类型的值并写回.ts失败则触发事件错误。值得注意的是remap转换的配置中提供了timezone选项用于指定时间戳转换时若输入不含时区信息应使用哪个时区并覆盖全局timezone选项同时还提供drop_on_error选项设为true可丢弃处理失败的事件避免错误事件继续向下游传播——这些都在 src/transforms/remap.rs 的RemapConfig中有明确定义。时区Time zones对于不包含时区信息的时间戳Vector 会假定其为本地时间并据此换算为 UTC 后存储原文assumes that the timestamp is in local time and converts the timestamp to UTC from the local time。这一点对排查时间为何偏移了 8 小时类问题至关重要如果你的日志时间戳没有Z或08:00这类后缀Vector 会按运行进程的本地时区解释它。因此要么让上游日志携带明确的时区偏移要么通过全局timezone选项 /remap的timezone选项固定解释时区。空值Null values为了兼容 JSON 日志事件Vector 同样支持null值。上游 JSON 中的field: null会在事件中保留为 null而不会直接丢弃从而避免字段缺失导致的语义变化。映射Maps映射map是将字符串字段名映射到任意类型值的关联数组即 JSON 中的对象object。例如示例中的log本身就是一个 map其值可以是字符串、数字、布尔、时间戳、null、另一个 map 或数组支持嵌套。数组Arrays数组字段是任意类型值的有序序列对应 JSON 中的 array。数组内元素类型可以不统一例如[a, 1, null]合法并且数组与 map 可以任意嵌套从而表达任意复杂的结构化日志。在管道中使用这些语义理解了数据模型之后实际配置中的几个关键点如下无需预定义 Schema直接把任意结构的日志喂给 Vector如file、socket、http等 sourceVector 会保持其字段原样流转。关键字段可重映射通过[log_schema]全局配置告诉 Vector 哪个字段是消息/时间戳/主机而非迁移数据。时间戳标准化事件进入 Vector 后时间戳统一按 UTC 存储需要解析字符串/整数时间时使用remapparse_timestamp并注意时区解释规则无时区信息默认按本地时间。类型安全整数为 64 位有符号、浮点为 IEEE 754 双精度、字符串为 UTF-8在设计 VRL 表达式与 sink 序列化时需要遵循这些边界。延伸阅读日志事件数据模型的架构图源文件website/static/img/data-model-log.svgLogSchema完整源码结构体、默认值、全局加载lib/vector-core/src/config/log_schema.rs[log_schema]配置的测试用例示例src/config/mod.rsremaptransform 的timezone与drop_on_error配置src/transforms/remap.rs官方示例配置演示事件流转与字段处理config/vector.yaml【免费下载链接】vectorA high-performance observability data pipeline.项目地址: https://gitcode.com/GitHub_Trending/vect/vector创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Vector 日志事件（Log Event）数据模型完全解析：Schema 中立、字段类型与时区语义
Vector 日志事件Log Event数据模型完全解析Schema 中立、字段类型与时区语义【免费下载链接】vectorA high-performance observability data pipeline.项目地址: https://gitcode.com/GitHub_Trending/vect/vector本文基于 observability 数据管道项目 Vector 的官方架构文档系统讲解 Vector 内部日志事件Log Event的统一数据模型事件以 JSON 兼容的嵌套结构表示字段类型与边界如何定义、时间戳如何被摄取与强转、时区语义如何处理以及通过log_schema全局配置自定义消息、时间戳、主机等关键字段的实现原理。读完本文你将掌握 Vector 日志管道的核心抽象并能准确配置[log_schema]段与remap转换让日志字段在你的拓扑中按预期流转。一个日志事件的表示方式Vector 中的日志事件log event本质上是一个结构化的数据对象。官方文档给出了一个以 JSON 呈现的典型示例{ log: { custom: field, host: my.host.com, message: Hello world, timestamp: 2020-11-01T21:15:4700:00 } }这个例子直观地展示了三点核心信息顶层有一个log命名空间事件被包裹在log键下与 Vector 的metric、trace事件类型相区分。字段完全自由除了message、host、timestamp这类被 Vector 赋予语义的字段外任何自定义字段如custom都可以直接附加。时间戳是带时区的 ISO 8601 字符串2020-11-01T21:15:4700:00明确携带了00:00的 UTC 偏移。从源码看这一 JSON 形态与 Vector 内部LogEvent的序列化行为一致——事件字段以键值对Key-Value形式存储可被任意 source、transform、sink 按路径读写。SchemaVector 的 Schema 中立原则什么是 SchemaLog schema日志模式是 Vector 用来统一处理事件字段、并指定哪些字段承载特定数据的约定。在 lib/vector-core/src/config/log_schema.rs 中LogSchema被定义为A log schema is used by Vector not only to uniformly process the fields of an event, but also to specify which fields should hold specific data that is also set by Vector once an event is flowing through a topology.即LogSchema既用于统一处理事件字段也用于指定哪些字段承载特定语义数据例如哪一个是消息、哪一个是时间戳这些字段由 Vector 在事件流经拓扑时自动写入。Vector 是 Schema 中立的官方文档明确指出Vector is schema-neutral and doesnt require any specific schema. This ensures that Vector can work with a variety of schemas, supporting legacy schemas as well as future schemas.Vector 不强制任何特定 Schema因此既能对接既有legacy的日志格式也能适应未来可能出现的新格式。这是 Vector 数据管道能够什么都能接、什么都能发的根本原因——你不必为了接入 Vector 而改造上游日志结构只需要通过配置告诉 Vector 哪个字段是什么即可。LogSchema的五个内置字段与默认值LogSchema结构体lib/vector-core/src/config/log_schema.rs定义了五个可配置的语义字段字段默认值语义message_keymessage事件的消息字段通常承载原始日志行timestamp_keytimestamp事件的时间戳字段host_keyhost发送消息的主机真实主机或容器取决于 sourcesource_type_keysource_type产生事件的 Vector source 标识metadata_keymetadata事件元数据例如remaptransform 在出错或中止时的注解这些默认值定义在源码常量中lib/vector-core/src/config/log_schema.rs以及对应的default_*_key()方法中lib/vector-core/src/config/log_schema.rs并通过#[serde(default ...)]属性实现不配置即使用默认值的行为。如何自定义log_schema你可以通过全局配置段[log_schema]覆盖这些默认字段名。src/config/mod.rs中的测试用例展示了其配置形态src/config/mod.rs[log_schema] message_key message timestamp_key timestamp例如如果上游系统约定使用msg和ts作为消息与时间字段你可以这样配置[log_schema] message_key msg timestamp_key ts之后 Vector 内部对消息时间戳的读写如 source 自动填充、sink 序列化都会落到你指定的路径上。全局 schema 的加载机制LogSchema通过全局单例在进程内生效相关逻辑同样位于 lib/vector-core/src/config/log_schema.rsstatic LOG_SCHEMA: OnceLockLogSchema保存配置加载后的全局 schemainit_log_schema(log_schema, deny_if_set)在配置阶段写入全局 schema若deny_if_set为true且已被设置过则会 panic防止重复初始化log_schema()返回全局 schema 引用未初始化时回退到不变的LogSchema::default()。源码注释明确要求组件应当始终通过log_schema()获取 schema而不是直接使用LogSchema::default()因为配置后的值可能与默认值不同。支持的数据类型Vector 日志事件的字段值支持以下类型集合覆盖了 JSON 及主流日志格式的全部需要字符串Strings字符串为UTF-8 兼容长度仅受可用系统内存限制。任何合法的 UTF-8 文本包括多语言日志、Emoji、二进制转义后的内容都可以安全存放。整数Integers整数为有符号 64 位signed integer up to 64 bits即覆盖i64的取值范围-9223372036854775808到9223372036854775807。超出该范围的数值无法以整数类型表示。浮点数Floats浮点数为64 位 IEEE 754双精度浮点数double与多数语言中的double/f64一致。官方文档明确引用 IEEE 754 标准。布尔值Booleans布尔值表示二元的true/false用于标志位、状态开关等场景。时间戳Timestamps时间戳以 Rust 的DateTime结构体 表示并且统一存储为 UTC。这意味着无论上游时区如何事件在 Vector 内部流转时时间基准一致不会因服务器时区差异产生歧义。时间戳强转Timestamp Coercion存在一些格式没有正式时间戳定义最典型的就是 JSON——JSON 中时间只能以字符串或整数原始形式存在。此时 Vector 会按原始形式字符串或整数摄取该字段而不会擅自假设其含义。如果你需要把它当作时间戳使用可以通过remaptransform 结合 VRL 的parse_timestamp函数进行强转coerce。这是一个典型的配置示例[transforms.coerce_ts] type remap inputs [in] source parsed parse_timestamp!(.timestamp, format: %Y-%m-%dT%H:%M:%S%:z) .ts parsed 其中parse_timestamp!会按给定格式解析字符串成功则返回timestamp类型的值并写回.ts失败则触发事件错误。值得注意的是remap转换的配置中提供了timezone选项用于指定时间戳转换时若输入不含时区信息应使用哪个时区并覆盖全局timezone选项同时还提供drop_on_error选项设为true可丢弃处理失败的事件避免错误事件继续向下游传播——这些都在 src/transforms/remap.rs 的RemapConfig中有明确定义。时区Time zones对于不包含时区信息的时间戳Vector 会假定其为本地时间并据此换算为 UTC 后存储原文assumes that the timestamp is in local time and converts the timestamp to UTC from the local time。这一点对排查时间为何偏移了 8 小时类问题至关重要如果你的日志时间戳没有Z或08:00这类后缀Vector 会按运行进程的本地时区解释它。因此要么让上游日志携带明确的时区偏移要么通过全局timezone选项 /remap的timezone选项固定解释时区。空值Null values为了兼容 JSON 日志事件Vector 同样支持null值。上游 JSON 中的field: null会在事件中保留为 null而不会直接丢弃从而避免字段缺失导致的语义变化。映射Maps映射map是将字符串字段名映射到任意类型值的关联数组即 JSON 中的对象object。例如示例中的log本身就是一个 map其值可以是字符串、数字、布尔、时间戳、null、另一个 map 或数组支持嵌套。数组Arrays数组字段是任意类型值的有序序列对应 JSON 中的 array。数组内元素类型可以不统一例如[a, 1, null]合法并且数组与 map 可以任意嵌套从而表达任意复杂的结构化日志。在管道中使用这些语义理解了数据模型之后实际配置中的几个关键点如下无需预定义 Schema直接把任意结构的日志喂给 Vector如file、socket、http等 sourceVector 会保持其字段原样流转。关键字段可重映射通过[log_schema]全局配置告诉 Vector 哪个字段是消息/时间戳/主机而非迁移数据。时间戳标准化事件进入 Vector 后时间戳统一按 UTC 存储需要解析字符串/整数时间时使用remapparse_timestamp并注意时区解释规则无时区信息默认按本地时间。类型安全整数为 64 位有符号、浮点为 IEEE 754 双精度、字符串为 UTF-8在设计 VRL 表达式与 sink 序列化时需要遵循这些边界。延伸阅读日志事件数据模型的架构图源文件website/static/img/data-model-log.svgLogSchema完整源码结构体、默认值、全局加载lib/vector-core/src/config/log_schema.rs[log_schema]配置的测试用例示例src/config/mod.rsremaptransform 的timezone与drop_on_error配置src/transforms/remap.rs官方示例配置演示事件流转与字段处理config/vector.yaml【免费下载链接】vectorA high-performance observability data pipeline.项目地址: https://gitcode.com/GitHub_Trending/vect/vector创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考