Telegraf 数据解析完全指南从原始数据到行协议的 Parser 选择、字段划分与时间戳配置【免费下载链接】telegrafAgent for collecting, processing, aggregating, and writing metrics, logs, and other arbitrary data.项目地址: https://gitcode.com/GitHub_Trending/te/telegraf导读Telegraf 本身并不直接存储原始数据而是通过可插拔的 parser 将 CSV、JSON、XML、InfluxDB Line Protocol 等任意格式的数据统一转换为由metric 名称measurement name、tags、fields 和时间戳组成的内部度量表示再交由聚合器、处理器和输出插件处理。本文基于仓库文档 docs/PARSING_DATA.md系统讲解如何为输入插件选择正确的 parser、如何把数据划分成 tags 与 fields以及如何配置 Unix 时间戳、Go 参考时间格式与时区相关参数并通过 CSV、JSON 的完整实战示例帮助你快速上手。读完本文你将能针对任意数据格式给出可直接运行的 Telegraf 解析配置。Telegraf 的内部度量模型解析的前提Telegraf 能够接收多种格式的数据但它要求用户提供配置才能正确解析、存储和发送原始数据——Telegraf 并不会保留原始数据而是将其转换后内部存储。这一内部表示由四个要素构成见 metric/metric.go 中的metric结构体MetricName度量名称measurement nameMetricTags标签集合用于索引和检索MetricFields字段集合即实际数值数据MetricTime时间戳这与 InfluxDB 的 line protocol 非常相似。也就是说解析的本质工作就是把任意输入数据拆解为 metric 名称、tags、fields 和时间戳四部分。虽然这四个部分并非全部强制要求例如未指定时间戳时使用当前时间但它们都开放给用户配置以确保数据被正确表达。从 metric/metric.go 可以看到metric.New()会接收名称、tags、fields 和时间戳参数其中字段值会经过convertField()的类型归一化tags 会按键排序这为下游处理提供了统一的度量结构。理解这一模型后解析流程就清晰了先选 parser再划分 tags/fields最后配置时间戳。下面逐一展开。第一步选择正确的 Parser解析的第一步是确定使用哪个 parser。Telegraf 的输入插件通过data_format选项选择 parser所有 parser 实现在 plugins/parsers 目录下完整清单见 docs/DATA_FORMATS_INPUT.md。当前仓库中可用的数据格式包括数据格式说明avroApache Avro 二进制格式binary通用二进制格式支持 base64/hex 编码collectdcollectd 网络协议二进制格式csv逗号分隔值文本dropwizardDropwizard 指标 JSON 格式form_urlencodedapplication/x-www-form-urlencoded 编码数据graphiteGraphite 纯文本协议grokGrok 模式匹配文本influxInfluxDB Line Protocoljson扁平 JSON 对象/数组json_v2面向嵌套 JSON 对象的进阶解析器logfmtlogfmt 键值对格式nagiosNagios 性能数据openmetricsOpenMetrics 文本格式opentsdbOpenTSDB telnet 协议parquetApache Parquet 列式文件prometheusPrometheus 文本/protobuf 格式prometheusremotewritePrometheus Remote Write 格式value单一标量值如45或booyahwavefrontWavefront 格式xpath基于 XPath 的解析器支持 XML、JSONxpath_json、MessagePackxpath_msgpack、CBORxpath_cbor、Protocol Buffersxpath_protobuf选择 parser 通常很直观数据类型一般只有一种真正适用的 parser。例如任意包含data_format选项的输入插件都可以这样指定解析器[[inputs.exec]] ## Commands array commands [/tmp/test.sh, /usr/bin/mycollector --foobar] ## measurement name suffix (for separating different commands) name_suffix _mycollector ## Data format to consume. data_format json从源码结构看parser 的注册机制位于 plugins/parsers/registry.go各格式的init()函数如 plugins/parsers/json/parser.go 中的parsers.Add(json, ...)在启动时完成注册此外在默认构建中所有内置格式会被统一编译进 plugins/parsers/all/all.go因此开箱即用。JSON 数据的例外三种 Parser 如何取舍JSON 数据是一个例外——它没有单一的 parser而是有三个都能读取 JSON 的解析器各自的适用场景差异很大json最适合扁平的 JSON 数据。如果 JSON 比较复杂例如包含嵌套对象或嵌套数组就不要用它请参考另外两个选项。从 plugins/parsers/json/parser.go 的实现看它通过gjson支持json_query预提取子文档再对对象/数组做扁平化处理其 READMEplugins/parsers/json/README.md明确说明所有 JSON 数字会被转为 float 字段JSON 字符串和布尔值默认被忽略除非在tag_keys或json_string_fields中显式指定。json_v2为解析JSON 对象而诞生能够处理更高级的场景嵌套对象、数组等代价是需要更多配置。它通过object、field、tag等子配置表精确描述目标行协议且对字段类型提供int/uint/float/string/bool的显式强制转换。**xpath_json**三者中能力最强的。虽然名字里有 XPath 会让人联想到 XML但它用 XPath 表达式可以解析多种数据类型包括 XML、JSON、MessagePack、Protocol Buffers 等。仓库中 [plugins/parsers/xpath/README.md](https://link.gitcode.com/i/7615cb1f7b416939a11593b1b9f169c3) 详细列出了这五种格式的data_format 值。需要留意的是plugins/parsers/json_v2/README.md 中给出了一个重要的维护者警告在当前实现状态下建议优先使用 XPath parser 而不是 json_v2尤其是在处理数组时。这一点对选择 JSON parser 有直接指导意义。第二步划分 Tags 与 Fields下一步是查看数据决定如何将其拆分为 tags 和 fieldsTags通常是字符串或用户想要用来检索/过滤的值例如主机名、节点名、环境等Fields是原始数据值通常是数值类型。一般规则是除非显式指定为 tag否则数据都被当作 field。例如 CSV 解析时通过csv_tag_columns指定哪些列作为 tag其余列自动成为 fieldJSON 解析时通过tag_keys指定被匹配的键会从 fields 中移到 tags参见 plugins/parsers/json/parser.go 中switchFieldToTag的实现字符串、布尔值、浮点数均会被转换为字符串形式的 tag 值并从 fields 中删除。第三步配置时间戳要解析时间戳至少需要指定两件事哪个字段/键包含时间戳以及时间戳的格式。格式既可以是预定义的 Unix 时间戳也可以是基于 Go 参考时间的自定义格式。Unix 时间戳格式Telegraf 支持以下 Unix 时间戳设置对应 internal/internal.go 中ParseTimestamp的分支处理内部按精度因子换算为纳秒时间戳时间戳格式1709572232unix1709572232123unix_ms1709572232123456unix_us1709572232123456789unix_nsUnix 时间戳没有时区概念始终按 UTC 解释。值得注意的是从 internal/internal.go 的parseUnix实现看Unix 时间戳可以来自整数、浮点数或字符串当为字符串时会先清洗千位分隔符再以高精度有理数解析以避免浮点精度损失。命名格式Named Formats此外还有一些 Go 标准库预定义的命名格式可用它们与 Gotime包常量一一对应在 internal/internal.go 中通过大小写不敏感的字符串匹配完成映射时间戳命名格式Mon Jan _2 15:04:05 2006ANSICMon Jan _2 15:04:05 MST 2006UnixDateMon Jan 02 15:04:05 -0700 2006RubyDate02 Jan 06 15:04 MSTRFC82202 Jan 06 15:04 -0700RFC822ZMonday, 02-Jan-06 15:04:05 MSTRFC850Mon, 02 Jan 2006 15:04:05 MSTRFC1123Mon, 02 Jan 2006 15:04:05 -0700RFC1123Z2006-01-02T15:04:05Z07:00RFC33392006-01-02T15:04:05.999999999Z07:00RFC3339NanoJan _2 15:04:05StampJan _2 15:04:05.000StampMilliJan _2 15:04:05.000000StampMicroJan _2 15:04:05.000000000StampNano自定义 Go 参考时间格式如果时间戳不符合上述任何格式用户可以指定自定义格式但必须使用Go 参考时间reference time记法。下面是一些示例时间戳及其 Go 参考时间等价写法时间戳Go 参考时间2024-03-04T17:10:322006-01-02T15:04:0504 Mar 24 10:10 -070002 Jan 06 15:04 -07002024-03-04T10:10:32Z07:002006-01-02T15:04:05Z07:002024-03-04 17:10:32.123002006-01-02 15:04:05.999002024-03-04T10:10:32.123456Z2006-01-02T15:04:05.000000Z2024-03-04T10:10:32.123456Z2006-01-02T15:04:05.999999999Z关于小数秒有两个重要注意点分数秒部分既可以使用9也可以使用0使用0会强制固定长度使用9则不强制长度时区缩写具有歧义性例如MST既可能表示 Mountain Standard TimeUTC-07也可能表示 Malaysia Standard TimeUTC08。因此应尽量避免使用缩写时区。从 internal/internal.go 的实现可以看到Telegraf 在解析包含MST这类缩写时区的时间戳时会尝试按缩写名加载时区并给出最佳推测同时会在日志中打印关于 v1.27.0 起解析行为变化的警告提示用户仔细核对时间戳数据。本地时区的 Unix 时间戳timestamp_tz 系列有些设备上报的时间戳是类似 Unix 格式的数字但使用的是本地时区而非 UTC。下面的格式通过计算本地时间与 UTC 之间的偏移来支持这类场景对应 internal/internal.go先按对应unix格式解析再用location的时区偏移进行修正时间戳时间戳格式1709572232timestamp_tz1709572232123timestamp_tz_ms1709572232123456timestamp_tz_us1709572232123456789timestamp_tz_ns使用这类格式时需要配合指定时区如 CSV 的csv_timezone、JSON 的json_timezone/timestamp_timezone时区值遵循 IANA 时区数据库如Pacific/Fiji、America/New_York、Local。实战示例下面是从 docs/PARSING_DATA.md 继承的五个示例覆盖了最常见的 CSV 与 JSON 场景。每个示例均基于inputs.file输入插件展示配置与期望输出。示例一CSV 基础解析给定数据node,temp,humidity,alarm,time node1,32.3,23,false,2023-03-06T16:52:23Z node2,22.6,44,false,2023-03-06T16:52:23Z node3,17.9,56,true,2023-03-06T16:52:23Z对应的 parser 配置与结果[[inputs.file]] files [test.csv] data_format csv csv_header_row_count 1 csv_column_names [node,temp,humidity,alarm,time] csv_tag_columns [node] csv_timestamp_column time csv_timestamp_format 2006-01-02T15:04:05Zfile,nodenode1 temp32.3,humidity23i,alarmfalse 1678121543000000000 file,nodenode2 temp22.6,humidity44i,alarmfalse 1678121543000000000 file,nodenode3 temp17.9,humidity56i,alarmtrue 1678121543000000000可以看到node被划为 tag数值列自动推断为对应类型temp为 floathumidity与alarm为整数/布尔时间列被解析为纳秒级时间戳。CSV parser 的完整配置选项如csv_skip_rows、csv_metadata_rows、csv_delimiter、csv_comment、csv_skip_values、csv_reset_mode等可参考 plugins/parsers/csv/README.md其中包括通过csv_metadata_separators把文件头部的元数据行解析为 tag 的能力。示例二CSV 使用本地时区时间戳有些设备的 CSV 时间列是本地时区的 Unix 数字而不是 UTC。给定数据node,temp,humidity,alarm,time node1,32.3,23,false,1568338208 node2,22.6,44,false,1568338208对应的 parser 配置与结果[[inputs.file]] files [test.csv] data_format csv csv_header_row_count 1 csv_column_names [node,temp,humidity,alarm,time] csv_tag_columns [node] csv_timestamp_column time csv_timestamp_format timestamp_tz csv_timezone Pacific/Fijifile,nodenode1 temp32.3,humidity23i,alarmfalse 1568295008000000000 file,nodenode2 temp22.6,humidity44i,alarmfalse 1568295008000000000 file,nodenode3 temp17.9,humidity56i,alarmtrue 1568295008000000000请注意CSV 中的时间戳比生成的 metric 时间戳晚了 12 小时因为Pacific/Fiji是 12:00 时区——即原始时间1568338208表示 Fiji 本地时间Telegraf 通过timestamp_tz格式计算出与 UTC 的偏移-12 小时后得到正确的 UTC 时间戳1568295008。示例三扁平 JSON 数据给定数据{ node: node, temp: 32.3, humidity: 23, alarm: false, time: 1709572232123456789}对应的 parser 配置[[inputs.file]] files [test.json] precision 1ns data_format json tag_keys [node] json_time_key time json_time_format unix_nsfile,nodenode temp32.3,humidity23 1709572232123456789说明tag_keys把node提为 tagjson_time_key配合json_time_format使用unix_ns精确到纳秒。注意alarm这个布尔值没有出现在输出中——这正是 plugins/parsers/json/README.md 中强调的 json parser 行为布尔值默认被忽略如需保留需通过json_string_fields显式指定。precision 1ns用于确保输出的时间戳精度不被截断。json parser 还支持json_name_key用文档内字段作为 measurement 名称、json_queryGJSON 路径预提取子文档等高级选项。示例四JSON 对象json_v2当 JSON 包含嵌套数组/对象时需要使用json_v2。给定数据{ metrics: [ { node: node1, temp: 32.3, humidity: 23, alarm: false, time: 1678121543}, { node: node2, temp: 22.6, humidity: 44, alarm: false, time: 1678121543}, { node: node3, temp: 17.9, humidity: 56, alarm: true, time: 1678121543} ] }对应的 parser 配置[[inputs.file]] files [test.json] data_format json_v2 [[inputs.file.json_v2]] [[inputs.file.json_v2.object]] path metrics timestamp_key time timestamp_format unix [[inputs.file.json_v2.object.tag]] path #.node [[inputs.file.json_v2.object.field]] path #.temp type float [[inputs.file.json_v2.object.field]] path #.humidity type int [[inputs.file.json_v2.object.field]] path #.alarm type boolfile,nodenode1 temp32.3,humidity23i,alarmfalse 1678121543000000000 file,nodenode2 temp22.6,humidity44i,alarmfalse 1678121543000000000 file,nodenode3 temp17.9,humidity56i,alarmtrue 1678121543000000000path metrics定位到根数组#.node等相对路径针对数组中的每个元素取值type显式指定字段类型float/int/booltimestamp_key/timestamp_format从元素中提取 Unix 时间戳。json_v2 的完整配置模型measurement_name、measurement_name_path、timestamp_path、included_keys/excluded_keys、disable_prepend_keys、renames、fields类型映射表等定义在 plugins/parsers/json_v2/parser.go 中可参阅 plugins/parsers/json_v2/README.md 了解其“数组的每个元素生成独立行协议、对象的每个键值对构成单条行协议”的处理规则。示例五JSON Line Protocolxpath_json对于结构上直接形如 line protocol 的 JSON 文档含fields/tags/name/time键xpath_json可以一行行地映射。给定数据{ fields: {temp: 32.3, humidity: 23, alarm: false}, name: measurement, tags: {node: node1}, time: 2024-03-04T10:10:32.123456Z }对应的 parser 配置[[inputs.file]] files [test.json] precision 1us data_format xpath_json [[inputs.file.xpath]] metric_name /name field_selection fields/* tag_selection tags/* timestamp /time timestamp_format 2006-01-02T15:04:05.999999999Zmeasurement,nodenode1 alarmfalse,humidity23,temp32.3 1709547032123456000XPath 的批量选择方式field_selection/tag_selection非常适合字段名不确定或数量庞大的文档metric_name从文档中提取 measurement 名称timestamp与timestamp_format从文档中提取时间。XPath parser 还支持显式定义方式fields_int、fields、tags子表、metric_selection多节点选择、field_name_expansion名称展开以及针对 Protocol Buffers 的xpath_protobuf_files/xpath_protobuf_type等参数详见 plugins/parsers/xpath/README.md。更多参考输入数据格式总览全部支持的数据格式与各 parser 入口插件解析器源码目录各 parser 的实现、README 与测试用例指标Metrics说明理解 Telegraf 度量模型与行协议配置指南metric 过滤、通用输入配置等【免费下载链接】telegrafAgent for collecting, processing, aggregating, and writing metrics, logs, and other arbitrary data.项目地址: https://gitcode.com/GitHub_Trending/te/telegraf创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Telegraf 数据解析完全指南：从原始数据到行协议的 Parser 选择、字段划分与时间戳配置
Telegraf 数据解析完全指南从原始数据到行协议的 Parser 选择、字段划分与时间戳配置【免费下载链接】telegrafAgent for collecting, processing, aggregating, and writing metrics, logs, and other arbitrary data.项目地址: https://gitcode.com/GitHub_Trending/te/telegraf导读Telegraf 本身并不直接存储原始数据而是通过可插拔的 parser 将 CSV、JSON、XML、InfluxDB Line Protocol 等任意格式的数据统一转换为由metric 名称measurement name、tags、fields 和时间戳组成的内部度量表示再交由聚合器、处理器和输出插件处理。本文基于仓库文档 docs/PARSING_DATA.md系统讲解如何为输入插件选择正确的 parser、如何把数据划分成 tags 与 fields以及如何配置 Unix 时间戳、Go 参考时间格式与时区相关参数并通过 CSV、JSON 的完整实战示例帮助你快速上手。读完本文你将能针对任意数据格式给出可直接运行的 Telegraf 解析配置。Telegraf 的内部度量模型解析的前提Telegraf 能够接收多种格式的数据但它要求用户提供配置才能正确解析、存储和发送原始数据——Telegraf 并不会保留原始数据而是将其转换后内部存储。这一内部表示由四个要素构成见 metric/metric.go 中的metric结构体MetricName度量名称measurement nameMetricTags标签集合用于索引和检索MetricFields字段集合即实际数值数据MetricTime时间戳这与 InfluxDB 的 line protocol 非常相似。也就是说解析的本质工作就是把任意输入数据拆解为 metric 名称、tags、fields 和时间戳四部分。虽然这四个部分并非全部强制要求例如未指定时间戳时使用当前时间但它们都开放给用户配置以确保数据被正确表达。从 metric/metric.go 可以看到metric.New()会接收名称、tags、fields 和时间戳参数其中字段值会经过convertField()的类型归一化tags 会按键排序这为下游处理提供了统一的度量结构。理解这一模型后解析流程就清晰了先选 parser再划分 tags/fields最后配置时间戳。下面逐一展开。第一步选择正确的 Parser解析的第一步是确定使用哪个 parser。Telegraf 的输入插件通过data_format选项选择 parser所有 parser 实现在 plugins/parsers 目录下完整清单见 docs/DATA_FORMATS_INPUT.md。当前仓库中可用的数据格式包括数据格式说明avroApache Avro 二进制格式binary通用二进制格式支持 base64/hex 编码collectdcollectd 网络协议二进制格式csv逗号分隔值文本dropwizardDropwizard 指标 JSON 格式form_urlencodedapplication/x-www-form-urlencoded 编码数据graphiteGraphite 纯文本协议grokGrok 模式匹配文本influxInfluxDB Line Protocoljson扁平 JSON 对象/数组json_v2面向嵌套 JSON 对象的进阶解析器logfmtlogfmt 键值对格式nagiosNagios 性能数据openmetricsOpenMetrics 文本格式opentsdbOpenTSDB telnet 协议parquetApache Parquet 列式文件prometheusPrometheus 文本/protobuf 格式prometheusremotewritePrometheus Remote Write 格式value单一标量值如45或booyahwavefrontWavefront 格式xpath基于 XPath 的解析器支持 XML、JSONxpath_json、MessagePackxpath_msgpack、CBORxpath_cbor、Protocol Buffersxpath_protobuf选择 parser 通常很直观数据类型一般只有一种真正适用的 parser。例如任意包含data_format选项的输入插件都可以这样指定解析器[[inputs.exec]] ## Commands array commands [/tmp/test.sh, /usr/bin/mycollector --foobar] ## measurement name suffix (for separating different commands) name_suffix _mycollector ## Data format to consume. data_format json从源码结构看parser 的注册机制位于 plugins/parsers/registry.go各格式的init()函数如 plugins/parsers/json/parser.go 中的parsers.Add(json, ...)在启动时完成注册此外在默认构建中所有内置格式会被统一编译进 plugins/parsers/all/all.go因此开箱即用。JSON 数据的例外三种 Parser 如何取舍JSON 数据是一个例外——它没有单一的 parser而是有三个都能读取 JSON 的解析器各自的适用场景差异很大json最适合扁平的 JSON 数据。如果 JSON 比较复杂例如包含嵌套对象或嵌套数组就不要用它请参考另外两个选项。从 plugins/parsers/json/parser.go 的实现看它通过gjson支持json_query预提取子文档再对对象/数组做扁平化处理其 READMEplugins/parsers/json/README.md明确说明所有 JSON 数字会被转为 float 字段JSON 字符串和布尔值默认被忽略除非在tag_keys或json_string_fields中显式指定。json_v2为解析JSON 对象而诞生能够处理更高级的场景嵌套对象、数组等代价是需要更多配置。它通过object、field、tag等子配置表精确描述目标行协议且对字段类型提供int/uint/float/string/bool的显式强制转换。**xpath_json**三者中能力最强的。虽然名字里有 XPath 会让人联想到 XML但它用 XPath 表达式可以解析多种数据类型包括 XML、JSON、MessagePack、Protocol Buffers 等。仓库中 [plugins/parsers/xpath/README.md](https://link.gitcode.com/i/7615cb1f7b416939a11593b1b9f169c3) 详细列出了这五种格式的data_format 值。需要留意的是plugins/parsers/json_v2/README.md 中给出了一个重要的维护者警告在当前实现状态下建议优先使用 XPath parser 而不是 json_v2尤其是在处理数组时。这一点对选择 JSON parser 有直接指导意义。第二步划分 Tags 与 Fields下一步是查看数据决定如何将其拆分为 tags 和 fieldsTags通常是字符串或用户想要用来检索/过滤的值例如主机名、节点名、环境等Fields是原始数据值通常是数值类型。一般规则是除非显式指定为 tag否则数据都被当作 field。例如 CSV 解析时通过csv_tag_columns指定哪些列作为 tag其余列自动成为 fieldJSON 解析时通过tag_keys指定被匹配的键会从 fields 中移到 tags参见 plugins/parsers/json/parser.go 中switchFieldToTag的实现字符串、布尔值、浮点数均会被转换为字符串形式的 tag 值并从 fields 中删除。第三步配置时间戳要解析时间戳至少需要指定两件事哪个字段/键包含时间戳以及时间戳的格式。格式既可以是预定义的 Unix 时间戳也可以是基于 Go 参考时间的自定义格式。Unix 时间戳格式Telegraf 支持以下 Unix 时间戳设置对应 internal/internal.go 中ParseTimestamp的分支处理内部按精度因子换算为纳秒时间戳时间戳格式1709572232unix1709572232123unix_ms1709572232123456unix_us1709572232123456789unix_nsUnix 时间戳没有时区概念始终按 UTC 解释。值得注意的是从 internal/internal.go 的parseUnix实现看Unix 时间戳可以来自整数、浮点数或字符串当为字符串时会先清洗千位分隔符再以高精度有理数解析以避免浮点精度损失。命名格式Named Formats此外还有一些 Go 标准库预定义的命名格式可用它们与 Gotime包常量一一对应在 internal/internal.go 中通过大小写不敏感的字符串匹配完成映射时间戳命名格式Mon Jan _2 15:04:05 2006ANSICMon Jan _2 15:04:05 MST 2006UnixDateMon Jan 02 15:04:05 -0700 2006RubyDate02 Jan 06 15:04 MSTRFC82202 Jan 06 15:04 -0700RFC822ZMonday, 02-Jan-06 15:04:05 MSTRFC850Mon, 02 Jan 2006 15:04:05 MSTRFC1123Mon, 02 Jan 2006 15:04:05 -0700RFC1123Z2006-01-02T15:04:05Z07:00RFC33392006-01-02T15:04:05.999999999Z07:00RFC3339NanoJan _2 15:04:05StampJan _2 15:04:05.000StampMilliJan _2 15:04:05.000000StampMicroJan _2 15:04:05.000000000StampNano自定义 Go 参考时间格式如果时间戳不符合上述任何格式用户可以指定自定义格式但必须使用Go 参考时间reference time记法。下面是一些示例时间戳及其 Go 参考时间等价写法时间戳Go 参考时间2024-03-04T17:10:322006-01-02T15:04:0504 Mar 24 10:10 -070002 Jan 06 15:04 -07002024-03-04T10:10:32Z07:002006-01-02T15:04:05Z07:002024-03-04 17:10:32.123002006-01-02 15:04:05.999002024-03-04T10:10:32.123456Z2006-01-02T15:04:05.000000Z2024-03-04T10:10:32.123456Z2006-01-02T15:04:05.999999999Z关于小数秒有两个重要注意点分数秒部分既可以使用9也可以使用0使用0会强制固定长度使用9则不强制长度时区缩写具有歧义性例如MST既可能表示 Mountain Standard TimeUTC-07也可能表示 Malaysia Standard TimeUTC08。因此应尽量避免使用缩写时区。从 internal/internal.go 的实现可以看到Telegraf 在解析包含MST这类缩写时区的时间戳时会尝试按缩写名加载时区并给出最佳推测同时会在日志中打印关于 v1.27.0 起解析行为变化的警告提示用户仔细核对时间戳数据。本地时区的 Unix 时间戳timestamp_tz 系列有些设备上报的时间戳是类似 Unix 格式的数字但使用的是本地时区而非 UTC。下面的格式通过计算本地时间与 UTC 之间的偏移来支持这类场景对应 internal/internal.go先按对应unix格式解析再用location的时区偏移进行修正时间戳时间戳格式1709572232timestamp_tz1709572232123timestamp_tz_ms1709572232123456timestamp_tz_us1709572232123456789timestamp_tz_ns使用这类格式时需要配合指定时区如 CSV 的csv_timezone、JSON 的json_timezone/timestamp_timezone时区值遵循 IANA 时区数据库如Pacific/Fiji、America/New_York、Local。实战示例下面是从 docs/PARSING_DATA.md 继承的五个示例覆盖了最常见的 CSV 与 JSON 场景。每个示例均基于inputs.file输入插件展示配置与期望输出。示例一CSV 基础解析给定数据node,temp,humidity,alarm,time node1,32.3,23,false,2023-03-06T16:52:23Z node2,22.6,44,false,2023-03-06T16:52:23Z node3,17.9,56,true,2023-03-06T16:52:23Z对应的 parser 配置与结果[[inputs.file]] files [test.csv] data_format csv csv_header_row_count 1 csv_column_names [node,temp,humidity,alarm,time] csv_tag_columns [node] csv_timestamp_column time csv_timestamp_format 2006-01-02T15:04:05Zfile,nodenode1 temp32.3,humidity23i,alarmfalse 1678121543000000000 file,nodenode2 temp22.6,humidity44i,alarmfalse 1678121543000000000 file,nodenode3 temp17.9,humidity56i,alarmtrue 1678121543000000000可以看到node被划为 tag数值列自动推断为对应类型temp为 floathumidity与alarm为整数/布尔时间列被解析为纳秒级时间戳。CSV parser 的完整配置选项如csv_skip_rows、csv_metadata_rows、csv_delimiter、csv_comment、csv_skip_values、csv_reset_mode等可参考 plugins/parsers/csv/README.md其中包括通过csv_metadata_separators把文件头部的元数据行解析为 tag 的能力。示例二CSV 使用本地时区时间戳有些设备的 CSV 时间列是本地时区的 Unix 数字而不是 UTC。给定数据node,temp,humidity,alarm,time node1,32.3,23,false,1568338208 node2,22.6,44,false,1568338208对应的 parser 配置与结果[[inputs.file]] files [test.csv] data_format csv csv_header_row_count 1 csv_column_names [node,temp,humidity,alarm,time] csv_tag_columns [node] csv_timestamp_column time csv_timestamp_format timestamp_tz csv_timezone Pacific/Fijifile,nodenode1 temp32.3,humidity23i,alarmfalse 1568295008000000000 file,nodenode2 temp22.6,humidity44i,alarmfalse 1568295008000000000 file,nodenode3 temp17.9,humidity56i,alarmtrue 1568295008000000000请注意CSV 中的时间戳比生成的 metric 时间戳晚了 12 小时因为Pacific/Fiji是 12:00 时区——即原始时间1568338208表示 Fiji 本地时间Telegraf 通过timestamp_tz格式计算出与 UTC 的偏移-12 小时后得到正确的 UTC 时间戳1568295008。示例三扁平 JSON 数据给定数据{ node: node, temp: 32.3, humidity: 23, alarm: false, time: 1709572232123456789}对应的 parser 配置[[inputs.file]] files [test.json] precision 1ns data_format json tag_keys [node] json_time_key time json_time_format unix_nsfile,nodenode temp32.3,humidity23 1709572232123456789说明tag_keys把node提为 tagjson_time_key配合json_time_format使用unix_ns精确到纳秒。注意alarm这个布尔值没有出现在输出中——这正是 plugins/parsers/json/README.md 中强调的 json parser 行为布尔值默认被忽略如需保留需通过json_string_fields显式指定。precision 1ns用于确保输出的时间戳精度不被截断。json parser 还支持json_name_key用文档内字段作为 measurement 名称、json_queryGJSON 路径预提取子文档等高级选项。示例四JSON 对象json_v2当 JSON 包含嵌套数组/对象时需要使用json_v2。给定数据{ metrics: [ { node: node1, temp: 32.3, humidity: 23, alarm: false, time: 1678121543}, { node: node2, temp: 22.6, humidity: 44, alarm: false, time: 1678121543}, { node: node3, temp: 17.9, humidity: 56, alarm: true, time: 1678121543} ] }对应的 parser 配置[[inputs.file]] files [test.json] data_format json_v2 [[inputs.file.json_v2]] [[inputs.file.json_v2.object]] path metrics timestamp_key time timestamp_format unix [[inputs.file.json_v2.object.tag]] path #.node [[inputs.file.json_v2.object.field]] path #.temp type float [[inputs.file.json_v2.object.field]] path #.humidity type int [[inputs.file.json_v2.object.field]] path #.alarm type boolfile,nodenode1 temp32.3,humidity23i,alarmfalse 1678121543000000000 file,nodenode2 temp22.6,humidity44i,alarmfalse 1678121543000000000 file,nodenode3 temp17.9,humidity56i,alarmtrue 1678121543000000000path metrics定位到根数组#.node等相对路径针对数组中的每个元素取值type显式指定字段类型float/int/booltimestamp_key/timestamp_format从元素中提取 Unix 时间戳。json_v2 的完整配置模型measurement_name、measurement_name_path、timestamp_path、included_keys/excluded_keys、disable_prepend_keys、renames、fields类型映射表等定义在 plugins/parsers/json_v2/parser.go 中可参阅 plugins/parsers/json_v2/README.md 了解其“数组的每个元素生成独立行协议、对象的每个键值对构成单条行协议”的处理规则。示例五JSON Line Protocolxpath_json对于结构上直接形如 line protocol 的 JSON 文档含fields/tags/name/time键xpath_json可以一行行地映射。给定数据{ fields: {temp: 32.3, humidity: 23, alarm: false}, name: measurement, tags: {node: node1}, time: 2024-03-04T10:10:32.123456Z }对应的 parser 配置[[inputs.file]] files [test.json] precision 1us data_format xpath_json [[inputs.file.xpath]] metric_name /name field_selection fields/* tag_selection tags/* timestamp /time timestamp_format 2006-01-02T15:04:05.999999999Zmeasurement,nodenode1 alarmfalse,humidity23,temp32.3 1709547032123456000XPath 的批量选择方式field_selection/tag_selection非常适合字段名不确定或数量庞大的文档metric_name从文档中提取 measurement 名称timestamp与timestamp_format从文档中提取时间。XPath parser 还支持显式定义方式fields_int、fields、tags子表、metric_selection多节点选择、field_name_expansion名称展开以及针对 Protocol Buffers 的xpath_protobuf_files/xpath_protobuf_type等参数详见 plugins/parsers/xpath/README.md。更多参考输入数据格式总览全部支持的数据格式与各 parser 入口插件解析器源码目录各 parser 的实现、README 与测试用例指标Metrics说明理解 Telegraf 度量模型与行协议配置指南metric 过滤、通用输入配置等【免费下载链接】telegrafAgent for collecting, processing, aggregating, and writing metrics, logs, and other arbitrary data.项目地址: https://gitcode.com/GitHub_Trending/te/telegraf创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
