Telegraf Value 数据格式解析器value parser完整指南将单一数值转换为指标【免费下载链接】telegrafAgent for collecting, processing, aggregating, and writing metrics, logs, and other arbitrary data.项目地址: https://gitcode.com/GitHub_Trending/te/telegraf导读Telegraf 的 Value 数据格式value data format是所有输入插件中最简单的解析方式之一它把输入数据中的单一数值直接翻译成一条 Telegraf 指标metric为该指标指定一个测量名称measurement name并把原始数值放入名为value的单个字段field中。本指南以 plugins/parsers/value/README.md 为核心结合仓库中的源码与测试完整讲解它的配置方法、7 种数据类型datatype的语义与取舍、底层解析原理以及value_field_name、name_override等关键参数的实际效果。读完本文你将能熟练地用value格式为 exec、socket_listener、mqtt_consumer 等输入插件解析任意单值输出型数据源。一、Value 解析器是什么Telegraf 内置了十余种输入数据格式详见 docs/DATA_FORMATS_INPUT.mdValue 是其中最简单的一种。它面向的场景非常直接数据源每次只输出一个数值例如命令执行结果cat /proc/sys/kernel/random/entropy_avail输出一个表示系统熵的整数socket、MQTT 等流式数据中的纯数字消息任何单行、单值的文本输出。当配置data_format value后解析器会读取输入缓冲区按data_type指定的类型转换原始文本构造一条测量名measurement name为插件名或name_override的指标将转换后的值写入名为value可被value_field_name覆盖的字段使用当前时间或SetTimeFunc指定的时间作为指标时间戳。也就是说一个原本没有结构的数字会被包装成 Telegraf 标准的指标从而进入后续的处理器processor、聚合器aggregator和输出output流水线。在源码中的位置解析器实现plugins/parsers/value/parser.go单元测试plugins/parsers/value/parser_test.go解析器注册表plugins/parsers/registry.govalue解析器通过 registry.go 中的parsers.Add(value, ...)注册到全局解析器表任何带data_format选项的输入插件exec、socket_listener、mqtt_consumer、firehose 等都可以直接引用它。二、配置示例与核心参数2.1 最小可用配置以exec输入插件为例plugins/parsers/value/README.md 中的原始示例[[inputs.exec]] ## Commands array commands [cat /proc/sys/kernel/random/entropy_avail] ## override the default metric name of exec name_override entropy_available ## override the field name of value # value_field_name value ## Data format to consume. ## Each data format has its own unique set of configuration options, read ## more about them here: ## https://github.com/influxdata/telegraf/blob/master/docs/DATA_FORMATS_INPUT.md data_format value data_type integer # required这条配置采集/proc/sys/kernel/random/entropy_avail的整数值最终生成类似下面的指标entropy_available value2467 1699999999999999999其中entropy_available是测量名value是字段名2467是转换后的整数值。2.2 参数一览配置项说明默认值data_format value启用 Value 数据格式解析器无data_type必填。指定原始数据的类型决定如何转换无value_field_name覆盖默认字段名valuevaluename_override覆盖默认测量名默认取插件名插件名这三个参数在源码中分别对应Parser结构体的DataType、FieldName、MetricName字段parser.gotype Parser struct { DataType string toml:data_type FieldName string toml:value_field_name MetricName string toml:- DefaultTags map[string]string toml:- }注意MetricName和DefaultTags的 toml 标签为-它们不来自用户配置而是由 Telegraf 框架在创建解析器时通过parsers.Add(value, func(defaultMetricName string) telegraf.Parser {...})注入parser.go。2.3 测量名Metric nameREADME 明确建议为指标设置一个有意义的name_override。如果省略测量名会退化为插件名例如exec、mqtt_consumer。对单值数据源来说测量名往往代表这是什么指标因此一个语义化的名称如entropy_available比默认的插件名更符合可观测性最佳实践。2.4 字段名覆盖value_field_name默认字段名是value。当同一采集任务中需要区分多个单值来源时可以用value_field_name覆盖。例如把熵值字段改名为entropy[[inputs.exec]] commands [cat /proc/sys/kernel/random/entropy_avail] data_format value data_type integer value_field_name entropy生成的字段将为entropy2467。测试 TestParseCustomFieldName 验证了这一点当FieldName设为penguin时解析55得到字段{penguin: int64(55)}。若该参数留空Init() 会自动补上默认值value。三、data_type7 种数据类型的语义与选择data_type是 Value 解析器唯一必填的选项它告诉 Telegraf 把原始文本解释成什么类型。README 定义了 7 种取值plugins/parsers/value/README.mddata_type行为非法的输入integer转换为整数值非整数数据如55.0、foobar报错float转换为浮点值整数会被当作浮点数处理无法转换的数据如字符串报错string原样输出为字符串无任何文本均可base64输出为 base64 编码的字符串无对原始缓冲区编码boolean转换为布尔值除true/false之外的任何数据报错auto_integer能转整数则转整数否则原样返回字符串无用于混合类型数据auto_float能转浮点则转浮点否则原样返回字符串无用于混合类型数据3.1 严格类型strict typinginteger / float / booleaninteger底层调用strconv.Atoi。测试 TestParseInvalidValues 证实输入55.0会返回包含invalid syntax的解析错误float底层调用strconv.ParseFloat(vStr, 64)因此整数文本如64会被解析为float64(64)见 TestParseValidValuesboolean底层调用strconv.ParseBool只有true/false不区分大小写是合法的213会报错。严格类型的好处是确定性值要么成功转换为目标类型要么明确报错绝不会有歧义。3.2 宽松类型auto 系列auto_integer / auto_float这两个类型专门用于混合类型数据源——同一字段在不同时刻可能输出数字或字符串auto_integer先尝试strconv.Atoi失败则保留字符串且不报错auto_float先尝试strconv.ParseFloat失败则保留字符串且不报错。测试 TestParseValidValues 展示了两者的完整行为矩阵输入auto_integer结果auto_float结果55int64(55)float64(55)55.055.0字符串float64(55)64.264.2字符串float64(64.2)foobarfoobar字符串foobar字符串3.3 string / base64非数值类型string不做任何转换直接输出原始文本。这也是唯一不执行取最后一个字段逻辑的类型见下一节源码分析base64对原始输入缓冲区做base64.StdEncoding.EncodeToString(buf)而不是对取出的字段编码。测试中输入foobar得到Zm9vYmFy。3.4 官方关于 auto 类型的警告README 特别指出auto转换可能意外地把字符串转成数字。例如一个以字符串形式提供55的数据源会被auto_integer/auto_float转换成数字。如果下游输出端要求某个字段或列内保持一致的数据类型这种类型漂移可能造成写入失败。因此只要可能尽量使用严格类型。3.5 别名与非法值从源码 Init() 看data_type还支持若干别名标准名可接受的别名integer空、intfloatlongstringstrbooleanboolbase64无auto_integer/auto_float无其中空字符串默认等于integer。任何其他取值如foo都会在Init阶段返回unknown datatype foo错误测试 TestInvalidDatatype 对此有覆盖。四、源码级解析原理4.1 Parse() 的完整流程parser.go 中的Parse()是实现的核心流程如下清洗缓冲区bytes.TrimSpace(bytes.Trim(buf, \x00))去除首尾空白和\x00空字符。测试 TestParseValuesWithNullCharacter 验证了输入55\x00能被正确解析为55——这对处理 C 风格字符串结尾的采集场景很实用取最后一个字段仅对非 string 类型strings.Fields(vStr)按空白拆分只取最后一个字段。也就是说即使输入包含多个值如55 45 223 12 999也只取999。README 通过这个设计让 Value 解析器能容忍混入前缀噪声的数据测试 TestParseValidValues 的 multiple integers 用例证实了这一行为按类型转换对应strconv.Atoi、strconv.ParseFloat、strconv.ParseBool、base64.StdEncoding.EncodeToString或原样保留错误处理转换失败立即返回err不产出指标构造指标metric.New(v.MetricName, v.DefaultTags, map[string]interface{}{v.FieldName: value}, v.timeFunc())。4.2 ParseLine() 与空输入ParseLine()parser.go是Parse()的薄封装解析结果为空时返回can not parse the line: ... for data format: value错误。Parse()在取字段阶段如果发现字段数为 0空输入会返回nil, nil——不报错也不产出指标。4.3 测试覆盖与基准测试parser_test.go 提供了非常完整的验证矩阵可作为理解行为的可执行文档TestParseValidValues12 个正向用例覆盖全部 7 种类型及多值输入TestParseInvalidValues/TestParseLineInvalidValues负向用例断言错误包含invalid syntaxTestParseCustomFieldName验证value_field_name覆盖TestParseValidValuesDefaultTags验证SetDefaultTags注入的标签会写入指标TestParseValuesWithNullCharacter验证\x00清洗TestInvalidDatatype验证非法data_type报错BenchmarkParsing单值解析的基准测试可用于性能回归监控。五、实战场景与组合用法5.1 组合 1exec value 解析系统参数这是 README 的原始场景。用name_override给指标一个语义化名称用data_type integer严格解析[[inputs.exec]] commands [cat /proc/sys/kernel/random/entropy_avail] name_override entropy_available data_format value data_type integer5.2 组合 2mqtt_consumer value topic_parsing在 plugins/inputs/mqtt_consumer/README.md 中value格式与 MQTT 主题解析topic_parsing配合能从主题路径中提取测量名、标签和额外字段形成一条更丰富的指标[[inputs.mqtt_consumer]] servers [tcp://127.0.0.1:1883] topics [telegraf//cpu/23] data_format value data_type float [[inputs.mqtt_consumer.topic_parsing]] topic telegraf/one/cpu/23 measurement _/_/measurement/_ tags tag/_/_/_ fields _/_/_/test [inputs.mqtt_consumer.topic_parsing.types] test int上述配置产出的指标形如cpu,hostpop-os,tagtelegraf,topictelegraf/one/cpu/23 value45,test23i 1637014942460689291这里的value45正是由 value 解析器产出的字段test23i则来自主题解析。这个例子说明value 格式不排斥与其他解析机制共存它只负责把消息体里的单值变成字段。5.3 组合 3socket_listener 采集单值流仓库中 plugins/inputs/socket_listener/testcases/splitting_fixed_length/telegraf.conf 也在测试配置中使用data_format value适用于 UDP/TCP socket 上推送裸数字流的场景firehose 插件的 README 同样提供了 value 格式示例。这类单值流正是 value 格式设计的目标场景。5.4 常见问题速查症状原因解法unknown datatype ...data_type拼写错误检查是否为 7 种合法值之一含别名integer 解析报invalid syntax输入含小数或非数字改用float或改用auto_integerboolean 解析1/0报错strconv.ParseBool只接受true/false数据源输出 true/false或改用整数类型多值输出只保留最后一个设计如此取最后一个字段若需全部分析改用其他数据格式如 influx、csv测量名是插件名而非语义名未设置name_override补上name_override字段名与下游 schema 冲突默认字段名固定为value用value_field_name改名六、小结与选型建议Value 数据格式的核心价值在于极简一条配置、一个必填参数就能把任意单值文本接入 Telegraf 指标体系。选择data_type时记住三条原则数据源类型固定如/proc下的计数器→ 用严格类型integer/float/boolean获得确定性数据源类型可能漂移数字与字符串混合→ 用auto_integer/auto_float但需注意类型漂移可能影响下游输出的一致性数据源是任意文本→ 用string需要传输二进制内容时用base64。想深入验证以上行为可以直接运行仓库中的测试go test ./plugins/parsers/value/...并结合 plugins/parsers/value/parser.go 与 plugins/parsers/value/parser_test.go 逐行对照你会对 Telegraf 的解析器框架创建、注册、Init、Parse形成完整认识。【免费下载链接】telegrafAgent for collecting, processing, aggregating, and writing metrics, logs, and other arbitrary data.项目地址: https://gitcode.com/GitHub_Trending/te/telegraf创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Telegraf Value 数据格式解析器（value parser）完整指南：将单一数值转换为指标
Telegraf Value 数据格式解析器value parser完整指南将单一数值转换为指标【免费下载链接】telegrafAgent for collecting, processing, aggregating, and writing metrics, logs, and other arbitrary data.项目地址: https://gitcode.com/GitHub_Trending/te/telegraf导读Telegraf 的 Value 数据格式value data format是所有输入插件中最简单的解析方式之一它把输入数据中的单一数值直接翻译成一条 Telegraf 指标metric为该指标指定一个测量名称measurement name并把原始数值放入名为value的单个字段field中。本指南以 plugins/parsers/value/README.md 为核心结合仓库中的源码与测试完整讲解它的配置方法、7 种数据类型datatype的语义与取舍、底层解析原理以及value_field_name、name_override等关键参数的实际效果。读完本文你将能熟练地用value格式为 exec、socket_listener、mqtt_consumer 等输入插件解析任意单值输出型数据源。一、Value 解析器是什么Telegraf 内置了十余种输入数据格式详见 docs/DATA_FORMATS_INPUT.mdValue 是其中最简单的一种。它面向的场景非常直接数据源每次只输出一个数值例如命令执行结果cat /proc/sys/kernel/random/entropy_avail输出一个表示系统熵的整数socket、MQTT 等流式数据中的纯数字消息任何单行、单值的文本输出。当配置data_format value后解析器会读取输入缓冲区按data_type指定的类型转换原始文本构造一条测量名measurement name为插件名或name_override的指标将转换后的值写入名为value可被value_field_name覆盖的字段使用当前时间或SetTimeFunc指定的时间作为指标时间戳。也就是说一个原本没有结构的数字会被包装成 Telegraf 标准的指标从而进入后续的处理器processor、聚合器aggregator和输出output流水线。在源码中的位置解析器实现plugins/parsers/value/parser.go单元测试plugins/parsers/value/parser_test.go解析器注册表plugins/parsers/registry.govalue解析器通过 registry.go 中的parsers.Add(value, ...)注册到全局解析器表任何带data_format选项的输入插件exec、socket_listener、mqtt_consumer、firehose 等都可以直接引用它。二、配置示例与核心参数2.1 最小可用配置以exec输入插件为例plugins/parsers/value/README.md 中的原始示例[[inputs.exec]] ## Commands array commands [cat /proc/sys/kernel/random/entropy_avail] ## override the default metric name of exec name_override entropy_available ## override the field name of value # value_field_name value ## Data format to consume. ## Each data format has its own unique set of configuration options, read ## more about them here: ## https://github.com/influxdata/telegraf/blob/master/docs/DATA_FORMATS_INPUT.md data_format value data_type integer # required这条配置采集/proc/sys/kernel/random/entropy_avail的整数值最终生成类似下面的指标entropy_available value2467 1699999999999999999其中entropy_available是测量名value是字段名2467是转换后的整数值。2.2 参数一览配置项说明默认值data_format value启用 Value 数据格式解析器无data_type必填。指定原始数据的类型决定如何转换无value_field_name覆盖默认字段名valuevaluename_override覆盖默认测量名默认取插件名插件名这三个参数在源码中分别对应Parser结构体的DataType、FieldName、MetricName字段parser.gotype Parser struct { DataType string toml:data_type FieldName string toml:value_field_name MetricName string toml:- DefaultTags map[string]string toml:- }注意MetricName和DefaultTags的 toml 标签为-它们不来自用户配置而是由 Telegraf 框架在创建解析器时通过parsers.Add(value, func(defaultMetricName string) telegraf.Parser {...})注入parser.go。2.3 测量名Metric nameREADME 明确建议为指标设置一个有意义的name_override。如果省略测量名会退化为插件名例如exec、mqtt_consumer。对单值数据源来说测量名往往代表这是什么指标因此一个语义化的名称如entropy_available比默认的插件名更符合可观测性最佳实践。2.4 字段名覆盖value_field_name默认字段名是value。当同一采集任务中需要区分多个单值来源时可以用value_field_name覆盖。例如把熵值字段改名为entropy[[inputs.exec]] commands [cat /proc/sys/kernel/random/entropy_avail] data_format value data_type integer value_field_name entropy生成的字段将为entropy2467。测试 TestParseCustomFieldName 验证了这一点当FieldName设为penguin时解析55得到字段{penguin: int64(55)}。若该参数留空Init() 会自动补上默认值value。三、data_type7 种数据类型的语义与选择data_type是 Value 解析器唯一必填的选项它告诉 Telegraf 把原始文本解释成什么类型。README 定义了 7 种取值plugins/parsers/value/README.mddata_type行为非法的输入integer转换为整数值非整数数据如55.0、foobar报错float转换为浮点值整数会被当作浮点数处理无法转换的数据如字符串报错string原样输出为字符串无任何文本均可base64输出为 base64 编码的字符串无对原始缓冲区编码boolean转换为布尔值除true/false之外的任何数据报错auto_integer能转整数则转整数否则原样返回字符串无用于混合类型数据auto_float能转浮点则转浮点否则原样返回字符串无用于混合类型数据3.1 严格类型strict typinginteger / float / booleaninteger底层调用strconv.Atoi。测试 TestParseInvalidValues 证实输入55.0会返回包含invalid syntax的解析错误float底层调用strconv.ParseFloat(vStr, 64)因此整数文本如64会被解析为float64(64)见 TestParseValidValuesboolean底层调用strconv.ParseBool只有true/false不区分大小写是合法的213会报错。严格类型的好处是确定性值要么成功转换为目标类型要么明确报错绝不会有歧义。3.2 宽松类型auto 系列auto_integer / auto_float这两个类型专门用于混合类型数据源——同一字段在不同时刻可能输出数字或字符串auto_integer先尝试strconv.Atoi失败则保留字符串且不报错auto_float先尝试strconv.ParseFloat失败则保留字符串且不报错。测试 TestParseValidValues 展示了两者的完整行为矩阵输入auto_integer结果auto_float结果55int64(55)float64(55)55.055.0字符串float64(55)64.264.2字符串float64(64.2)foobarfoobar字符串foobar字符串3.3 string / base64非数值类型string不做任何转换直接输出原始文本。这也是唯一不执行取最后一个字段逻辑的类型见下一节源码分析base64对原始输入缓冲区做base64.StdEncoding.EncodeToString(buf)而不是对取出的字段编码。测试中输入foobar得到Zm9vYmFy。3.4 官方关于 auto 类型的警告README 特别指出auto转换可能意外地把字符串转成数字。例如一个以字符串形式提供55的数据源会被auto_integer/auto_float转换成数字。如果下游输出端要求某个字段或列内保持一致的数据类型这种类型漂移可能造成写入失败。因此只要可能尽量使用严格类型。3.5 别名与非法值从源码 Init() 看data_type还支持若干别名标准名可接受的别名integer空、intfloatlongstringstrbooleanboolbase64无auto_integer/auto_float无其中空字符串默认等于integer。任何其他取值如foo都会在Init阶段返回unknown datatype foo错误测试 TestInvalidDatatype 对此有覆盖。四、源码级解析原理4.1 Parse() 的完整流程parser.go 中的Parse()是实现的核心流程如下清洗缓冲区bytes.TrimSpace(bytes.Trim(buf, \x00))去除首尾空白和\x00空字符。测试 TestParseValuesWithNullCharacter 验证了输入55\x00能被正确解析为55——这对处理 C 风格字符串结尾的采集场景很实用取最后一个字段仅对非 string 类型strings.Fields(vStr)按空白拆分只取最后一个字段。也就是说即使输入包含多个值如55 45 223 12 999也只取999。README 通过这个设计让 Value 解析器能容忍混入前缀噪声的数据测试 TestParseValidValues 的 multiple integers 用例证实了这一行为按类型转换对应strconv.Atoi、strconv.ParseFloat、strconv.ParseBool、base64.StdEncoding.EncodeToString或原样保留错误处理转换失败立即返回err不产出指标构造指标metric.New(v.MetricName, v.DefaultTags, map[string]interface{}{v.FieldName: value}, v.timeFunc())。4.2 ParseLine() 与空输入ParseLine()parser.go是Parse()的薄封装解析结果为空时返回can not parse the line: ... for data format: value错误。Parse()在取字段阶段如果发现字段数为 0空输入会返回nil, nil——不报错也不产出指标。4.3 测试覆盖与基准测试parser_test.go 提供了非常完整的验证矩阵可作为理解行为的可执行文档TestParseValidValues12 个正向用例覆盖全部 7 种类型及多值输入TestParseInvalidValues/TestParseLineInvalidValues负向用例断言错误包含invalid syntaxTestParseCustomFieldName验证value_field_name覆盖TestParseValidValuesDefaultTags验证SetDefaultTags注入的标签会写入指标TestParseValuesWithNullCharacter验证\x00清洗TestInvalidDatatype验证非法data_type报错BenchmarkParsing单值解析的基准测试可用于性能回归监控。五、实战场景与组合用法5.1 组合 1exec value 解析系统参数这是 README 的原始场景。用name_override给指标一个语义化名称用data_type integer严格解析[[inputs.exec]] commands [cat /proc/sys/kernel/random/entropy_avail] name_override entropy_available data_format value data_type integer5.2 组合 2mqtt_consumer value topic_parsing在 plugins/inputs/mqtt_consumer/README.md 中value格式与 MQTT 主题解析topic_parsing配合能从主题路径中提取测量名、标签和额外字段形成一条更丰富的指标[[inputs.mqtt_consumer]] servers [tcp://127.0.0.1:1883] topics [telegraf//cpu/23] data_format value data_type float [[inputs.mqtt_consumer.topic_parsing]] topic telegraf/one/cpu/23 measurement _/_/measurement/_ tags tag/_/_/_ fields _/_/_/test [inputs.mqtt_consumer.topic_parsing.types] test int上述配置产出的指标形如cpu,hostpop-os,tagtelegraf,topictelegraf/one/cpu/23 value45,test23i 1637014942460689291这里的value45正是由 value 解析器产出的字段test23i则来自主题解析。这个例子说明value 格式不排斥与其他解析机制共存它只负责把消息体里的单值变成字段。5.3 组合 3socket_listener 采集单值流仓库中 plugins/inputs/socket_listener/testcases/splitting_fixed_length/telegraf.conf 也在测试配置中使用data_format value适用于 UDP/TCP socket 上推送裸数字流的场景firehose 插件的 README 同样提供了 value 格式示例。这类单值流正是 value 格式设计的目标场景。5.4 常见问题速查症状原因解法unknown datatype ...data_type拼写错误检查是否为 7 种合法值之一含别名integer 解析报invalid syntax输入含小数或非数字改用float或改用auto_integerboolean 解析1/0报错strconv.ParseBool只接受true/false数据源输出 true/false或改用整数类型多值输出只保留最后一个设计如此取最后一个字段若需全部分析改用其他数据格式如 influx、csv测量名是插件名而非语义名未设置name_override补上name_override字段名与下游 schema 冲突默认字段名固定为value用value_field_name改名六、小结与选型建议Value 数据格式的核心价值在于极简一条配置、一个必填参数就能把任意单值文本接入 Telegraf 指标体系。选择data_type时记住三条原则数据源类型固定如/proc下的计数器→ 用严格类型integer/float/boolean获得确定性数据源类型可能漂移数字与字符串混合→ 用auto_integer/auto_float但需注意类型漂移可能影响下游输出的一致性数据源是任意文本→ 用string需要传输二进制内容时用base64。想深入验证以上行为可以直接运行仓库中的测试go test ./plugins/parsers/value/...并结合 plugins/parsers/value/parser.go 与 plugins/parsers/value/parser_test.go 逐行对照你会对 Telegraf 的解析器框架创建、注册、Init、Parse形成完整认识。【免费下载链接】telegrafAgent for collecting, processing, aggregating, and writing metrics, logs, and other arbitrary data.项目地址: https://gitcode.com/GitHub_Trending/te/telegraf创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考