Telegraf Strings 处理器插件实战对指标名称、标签与字段值进行字符串变换【免费下载链接】telegrafAgent for collecting, processing, aggregating, and writing metrics, logs, and other arbitrary data.项目地址: https://gitcode.com/GitHub_Trending/te/telegrafTelegraf 的strings处理器Processor Plugin提供了一组纯函数式的字符串变换能力可对指标Metric的**测量名称measurement、标签键/值tag / tag_key以及字段键/值field / field_key**执行大小写转换、裁剪、替换、按宽度截断、Base64 解码和 UTF-8 清洗等操作。本文以 strings 插件 README 为核心结合其 源码实现 与 测试用例完整讲解全部 12 个变换函数的配置方法、执行语义与底层实现细节帮助你在采集链路中实时标准化数据命名。插件概览做什么、何时用strings处理器于Telegraf v1.8.0引入类型标记为transformation数据变换all平台通用。它的核心定位非常明确让数据在写入输出端之前先统一成一致的命名与格式约定。典型应用场景包括将日志/流量采集上来的字段值统一大小写如把uri_stem/API/HealthCheck规范化为healthcheck去掉标签值中的前后缀如剥离 URL 的/api/前缀便于按业务维度聚合把标签键中的非法字符如-、:替换为下划线满足下游时序数据库对标识符的约束对 Base64 编码的消息字段进行解码或把含非法 UTF-8 字节的脏数据清洗为合法字符串。该插件在处理器管线中的位置是输入插件之后、聚合插件之前具体执行时机与全局配置见 docs/CONFIGURATION.md#plugins。安装与启用Telegraf 通过构建标签build-tags机制控制插件是否编译进二进制。strings插件在 plugins/processors/all/strings.go 中注册//go:build !custom || processors || processors.strings package all import _ github.com/influxdata/telegraf/plugins/processors/strings // register plugin而插件本体在包初始化阶段调用processors.Add(strings, ...)完成注册见 plugins/processors/strings/strings.go。使用官方发行版二进制时无需任何额外操作直接在配置文件中启用[[processors.strings]]即可若你使用自定义构建custom builder则需保留processors.strings构建标签。通用配置模型目标、目标位置与结果存放每个变换函数都以一个子表sub-table形式存在内部通过一组通用参数指定“改哪里、改什么、结果放哪”参数作用说明measurement指定要变换的测量名称可精确匹配或使用*匹配全部测量tag指定要变换的标签值value同上支持*tag_key指定要变换的标签键key同上支持*field指定要变换的字段值value同上支持*field_key指定要变换的字段键key同上支持*dest可选将变换结果存放到新的标签/字段仅当目标为单个具体名称时有效三个关键语义与 README 保持一致执行顺序即配置顺序所有变换操作严格按照配置文件中的出现次序执行后续操作可以消费前一步的变换结果。原位修改或另存不指定dest时原地覆盖原值指定dest时原值保留新值写入新标签/字段。通配符*可对全部 tag / tag_key / field / field_key / measurement 批量生效注意dest在配合*使用时会被忽略。从源码看每个转换器converter的字段定义与 TOML 标签一一对应见 strings.go并在convert()分发方法中按field → field_key → tag → tag_key → measurement的优先级依次尝试处理见 strings.go。全部 12 个变换函数详解完整的可复制配置模板位于 plugins/processors/strings/sample.confREADME 通过toml sample.conf自动注入。下面按功能分组逐一讲解。大小写转换lowercase / uppercase / titlecase[[processors.strings]] ## 将字段值转为小写并存到新字段 # [[processors.strings.lowercase]] # field uri_stem # dest uri_stem_normalised ## 将标签值转为大写 # [[processors.strings.uppercase]] # tag method ## 将字段值转为标题大小写每个单词首字母大写 # [[processors.strings.titlecase]] # field status源码实现中lowercase直接映射 Go 标准库的strings.ToLoweruppercase映射strings.ToUpper而titlecase使用golang.org/x/text的cases.Title(language.Und, cases.NoLower)见 strings.go因此它遵循 Unicode 标题大小写规则同时不会强制把其余字符改小写——例如/API/HealthCheck经 titlecase 处理后变为/API/HealthCheck语义下的逐词首字母大写形式。裁剪类trim / trim_left / trim_right / trim_prefix / trim_suffix## 使用默认 cutset空白字符裁剪首尾空白 # [[processors.strings.trim]] # field message ## 仅裁剪左侧属于 cutset 的字符 # [[processors.strings.trim_left]] # field message # cutset \t ## 仅裁剪右侧属于 cutset 的字符 # [[processors.strings.trim_right]] # field message # cutset \r\n ## 去除指定前缀 # [[processors.strings.trim_prefix]] # field my_value # prefix my_ ## 去除指定后缀 # [[processors.strings.trim_suffix]] # field read_count # suffix _count参数语义trim、trim_left、trim_right接受可选参数cutset它是一个字符集合字符串代表要从值中移除的字符不传cutset时默认按unicode.IsSpace裁剪所有空白字符含空格、\t、\r、\n等。源码中这一分支逻辑清晰可见strings.go。trim_prefix/trim_suffix分别接受prefix/suffix参数只做一次性精确匹配删除字符串头部恰为prefix时去掉该前缀否则不做任何改动。一个容易混淆的细节cutset是按“字符集合”而非“子串”工作的例如cutset /w会同时裁剪掉/和w两个字符的任意组合这一点在测试用例中有明确体现见 strings_test.go。子串替换replace## 将字符串中所有不重叠出现的 old 替换为 new # [[processors.strings.replace]] # measurement * # old : # new _replace在整个字符串上执行全局子串替换等价于 Go 的strings.ReplaceAll典型用途包括清除字段名/标签键中的非法字符、统一不同输入输出插件间的分隔符约定、剔除指标中无用的字符等。关键保护行为如果替换后整个名称被删空例如old恰好占满整个 measurement 名且new为空插件会拒绝执行该操作并保留原名见 strings.go测试TestMeasurementCharDeletion验证了这一行为strings_test.go。按宽度截断left## 按宽度截断字符串保留前 N 个字符 # [[processors.strings.left]] # field message # width 10left根据width保留字符串前 N 个字符其余丢弃当字符串长度小于width时不做任何处理见 strings.go。测试用例也覆盖了“宽度大于字符串长度时不做任何改动”的场景strings_test.go。Base64 解码base64decode## 解码 Base64 编码的 UTF-8 字符串 # [[processors.strings.base64decode]] # field messagebase64decode使用标准 Base64 编码base64.StdEncoding解码字符串并做了双重安全校验若解码失败非合法 Base64或解码结果不是合法 UTF-8则返回原始字符串、不产生副作用见 strings.go。三个对应的测试用例分别验证了成功解码、非法 Base64、非法 UTF-8 三种路径strings_test.go。UTF-8 清洗valid_utf8## 清洗字符串确保其是合法 UTF-8 ## 每一段非法 UTF-8 字节序列都会被替换为 replacement可为空字符串 # [[processors.strings.valid_utf8]] # field message # replacement valid_utf8调用 Go 的strings.ToValidUTF8把值中每一段连续的非法 UTF-8 字节序列替换为replacement当replacement为空字符串时等价于直接剔除所有非法字节见 strings.go。该函数非常适合处理来自不可靠数据源如外部日志、串口、二进制协议的脏字符串测试TestValidUTF8覆盖了三种典型输入strings_test.go。完整配置示例IIS 日志命名规范化下面这段配置来自 README 的 Example 1展示了一次典型的“组合拳”对uri_stem标签先转小写再剥离/api/前缀同时把cs-host字段大写并存入新字段且不破坏原值[[processors.strings]] [[processors.strings.lowercase]] tag uri_stem [[processors.strings.trim_prefix]] tag uri_stem prefix /api/ [[processors.strings.uppercase]] field cs-host dest cs-host_normalised输入iis_log,methodget,uri_stem/API/HealthCheck cs-hostMIXEDCASE_host,http_version1.1 1519652321000000000输出iis_log,methodget,uri_stemhealthcheck cs-hostMIXEDCASE_host,http_version1.1,cs-host_normalisedMIXEDCASE_HOST 1519652321000000000注意两点uri_stem被原地改写先 lowercase 后 trim_prefix两步串行cs-host原值保留变换结果写入新字段cs-host_normalised。该示例在测试TestReadmeExample中被完整还原验证strings_test.go。标签键/字段键变换第二个完整示例Example 2 展示了**对键名key**做变换的能力把标签键URI-Stem先转小写、再把连字符替换为下划线[[processors.strings]] [[processors.strings.lowercase]] tag_key URI-Stem [[processors.strings.replace]] tag_key uri-stem old - new _输入iis_log,URI-Stem/API/HealthCheck http_version1.1 1519652321000000000输出iis_log,uri_stem/API/HealthCheck http_version1.1 1519652321000000000注意这里执行顺序的妙用第一步把URI-Stem改写为uri-stem第二步才能以uri-stem为目标命中它再完成- → _的替换。如果两步顺序颠倒第二步将因找不到uri-stem而无效——这正是“操作按配置顺序执行”这一语义的实战体现。源码中键变换的实现会先移除旧键再添加新键当变换结果为空字符串时则跳过删除与重建见 strings.go 与 strings.go。源码级执行原理从 strings.go 可以还原出完整的执行模型Apply是唯一入口每个指标依次遍历所有已初始化的转换器逐条执行strings.go。惰性初始化initOnce首次调用时将各子表配置组装为带具体函数闭包的 converter 列表注册顺序固定为lowercase → uppercase → titlecase → trim → trim_left → trim_right → trim_prefix → trim_suffix → replace → left → base64decode → valid_utf8strings.go。该顺序决定了同一指标内不同类型变换的兜底次序因此测试注释中也提醒读者注意这一点strings_test.go。字段值类型安全字段值的变换仅作用于字符串类型数字、布尔等非字符串字段会被自动跳过见 strings.goTestMultipleConversions中的ignore_number、ignore_bool字段即验证了这一行为strings_test.go。目标缺失即跳过指定的 tag/field 不存在时转换器直接返回、不做任何操作如 strings.go。跟踪指标不丢失TestTrackedMetricNotLost验证了在配合 metric tracking送达确认机制时即使发生 UTF-8 清洗指标的投递信息也能被正确送达strings_test.go。与全局配置及处理器排序协同strings处理器支持所有处理器通用的全局配置项见 docs/CONFIGURATION.mdalias为插件实例命名便于日志区分order显式指定处理器执行顺序从 1 开始未指定order的处理器按配置出现顺序执行log_level覆盖该插件的日志级别metric filtering通用参数namepass、tagpass、fieldpass等可用于限定只处理部分指标。官方文档给出了一个与rename处理器配合、用order保证次序的示例docs/CONFIGURATION.md[[processors.rename]] order 1 [[processors.rename.replace]] tag path dest resource [[processors.strings]] order 2 [[processors.strings.trim_prefix]] tag resource prefix /api/这里rename先把标签path复制为resourcestrings再对resource剥离/api/前缀。由于涉及跨插件的先后依赖必须通过order显式声明执行顺序否则结果不可预期。使用建议与注意事项先小写/大写、再裁剪/替换是常见的高效组合——键名经过大小写归一化后更容易被后续规则精确命中参考第二个示例。涉及通配符*时不要配置dest该参数会被忽略若需要保留原始字段请将变换拆分为单独的、指定具体名称的配置块。需要跨多个处理器实例保证顺序时务必为所有相关处理器设置order。base64decode与valid_utf8都遵循“失败或结果不合法则保留原值”的保守策略可放心用于不可靠来源的数据不会引入额外脏数据。字段值变换只作用于字符串类型混合类型的字段会被安全跳过不会报错。若需深入阅读可继续查看 插件 README、示例配置、完整源码 与 1200 余行测试用例或参照 docs/PROCESSORS.md 了解如何编写自定义处理器插件。【免费下载链接】telegrafAgent for collecting, processing, aggregating, and writing metrics, logs, and other arbitrary data.项目地址: https://gitcode.com/GitHub_Trending/te/telegraf创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Telegraf Strings 处理器插件实战：对指标名称、标签与字段值进行字符串变换
Telegraf Strings 处理器插件实战对指标名称、标签与字段值进行字符串变换【免费下载链接】telegrafAgent for collecting, processing, aggregating, and writing metrics, logs, and other arbitrary data.项目地址: https://gitcode.com/GitHub_Trending/te/telegrafTelegraf 的strings处理器Processor Plugin提供了一组纯函数式的字符串变换能力可对指标Metric的**测量名称measurement、标签键/值tag / tag_key以及字段键/值field / field_key**执行大小写转换、裁剪、替换、按宽度截断、Base64 解码和 UTF-8 清洗等操作。本文以 strings 插件 README 为核心结合其 源码实现 与 测试用例完整讲解全部 12 个变换函数的配置方法、执行语义与底层实现细节帮助你在采集链路中实时标准化数据命名。插件概览做什么、何时用strings处理器于Telegraf v1.8.0引入类型标记为transformation数据变换all平台通用。它的核心定位非常明确让数据在写入输出端之前先统一成一致的命名与格式约定。典型应用场景包括将日志/流量采集上来的字段值统一大小写如把uri_stem/API/HealthCheck规范化为healthcheck去掉标签值中的前后缀如剥离 URL 的/api/前缀便于按业务维度聚合把标签键中的非法字符如-、:替换为下划线满足下游时序数据库对标识符的约束对 Base64 编码的消息字段进行解码或把含非法 UTF-8 字节的脏数据清洗为合法字符串。该插件在处理器管线中的位置是输入插件之后、聚合插件之前具体执行时机与全局配置见 docs/CONFIGURATION.md#plugins。安装与启用Telegraf 通过构建标签build-tags机制控制插件是否编译进二进制。strings插件在 plugins/processors/all/strings.go 中注册//go:build !custom || processors || processors.strings package all import _ github.com/influxdata/telegraf/plugins/processors/strings // register plugin而插件本体在包初始化阶段调用processors.Add(strings, ...)完成注册见 plugins/processors/strings/strings.go。使用官方发行版二进制时无需任何额外操作直接在配置文件中启用[[processors.strings]]即可若你使用自定义构建custom builder则需保留processors.strings构建标签。通用配置模型目标、目标位置与结果存放每个变换函数都以一个子表sub-table形式存在内部通过一组通用参数指定“改哪里、改什么、结果放哪”参数作用说明measurement指定要变换的测量名称可精确匹配或使用*匹配全部测量tag指定要变换的标签值value同上支持*tag_key指定要变换的标签键key同上支持*field指定要变换的字段值value同上支持*field_key指定要变换的字段键key同上支持*dest可选将变换结果存放到新的标签/字段仅当目标为单个具体名称时有效三个关键语义与 README 保持一致执行顺序即配置顺序所有变换操作严格按照配置文件中的出现次序执行后续操作可以消费前一步的变换结果。原位修改或另存不指定dest时原地覆盖原值指定dest时原值保留新值写入新标签/字段。通配符*可对全部 tag / tag_key / field / field_key / measurement 批量生效注意dest在配合*使用时会被忽略。从源码看每个转换器converter的字段定义与 TOML 标签一一对应见 strings.go并在convert()分发方法中按field → field_key → tag → tag_key → measurement的优先级依次尝试处理见 strings.go。全部 12 个变换函数详解完整的可复制配置模板位于 plugins/processors/strings/sample.confREADME 通过toml sample.conf自动注入。下面按功能分组逐一讲解。大小写转换lowercase / uppercase / titlecase[[processors.strings]] ## 将字段值转为小写并存到新字段 # [[processors.strings.lowercase]] # field uri_stem # dest uri_stem_normalised ## 将标签值转为大写 # [[processors.strings.uppercase]] # tag method ## 将字段值转为标题大小写每个单词首字母大写 # [[processors.strings.titlecase]] # field status源码实现中lowercase直接映射 Go 标准库的strings.ToLoweruppercase映射strings.ToUpper而titlecase使用golang.org/x/text的cases.Title(language.Und, cases.NoLower)见 strings.go因此它遵循 Unicode 标题大小写规则同时不会强制把其余字符改小写——例如/API/HealthCheck经 titlecase 处理后变为/API/HealthCheck语义下的逐词首字母大写形式。裁剪类trim / trim_left / trim_right / trim_prefix / trim_suffix## 使用默认 cutset空白字符裁剪首尾空白 # [[processors.strings.trim]] # field message ## 仅裁剪左侧属于 cutset 的字符 # [[processors.strings.trim_left]] # field message # cutset \t ## 仅裁剪右侧属于 cutset 的字符 # [[processors.strings.trim_right]] # field message # cutset \r\n ## 去除指定前缀 # [[processors.strings.trim_prefix]] # field my_value # prefix my_ ## 去除指定后缀 # [[processors.strings.trim_suffix]] # field read_count # suffix _count参数语义trim、trim_left、trim_right接受可选参数cutset它是一个字符集合字符串代表要从值中移除的字符不传cutset时默认按unicode.IsSpace裁剪所有空白字符含空格、\t、\r、\n等。源码中这一分支逻辑清晰可见strings.go。trim_prefix/trim_suffix分别接受prefix/suffix参数只做一次性精确匹配删除字符串头部恰为prefix时去掉该前缀否则不做任何改动。一个容易混淆的细节cutset是按“字符集合”而非“子串”工作的例如cutset /w会同时裁剪掉/和w两个字符的任意组合这一点在测试用例中有明确体现见 strings_test.go。子串替换replace## 将字符串中所有不重叠出现的 old 替换为 new # [[processors.strings.replace]] # measurement * # old : # new _replace在整个字符串上执行全局子串替换等价于 Go 的strings.ReplaceAll典型用途包括清除字段名/标签键中的非法字符、统一不同输入输出插件间的分隔符约定、剔除指标中无用的字符等。关键保护行为如果替换后整个名称被删空例如old恰好占满整个 measurement 名且new为空插件会拒绝执行该操作并保留原名见 strings.go测试TestMeasurementCharDeletion验证了这一行为strings_test.go。按宽度截断left## 按宽度截断字符串保留前 N 个字符 # [[processors.strings.left]] # field message # width 10left根据width保留字符串前 N 个字符其余丢弃当字符串长度小于width时不做任何处理见 strings.go。测试用例也覆盖了“宽度大于字符串长度时不做任何改动”的场景strings_test.go。Base64 解码base64decode## 解码 Base64 编码的 UTF-8 字符串 # [[processors.strings.base64decode]] # field messagebase64decode使用标准 Base64 编码base64.StdEncoding解码字符串并做了双重安全校验若解码失败非合法 Base64或解码结果不是合法 UTF-8则返回原始字符串、不产生副作用见 strings.go。三个对应的测试用例分别验证了成功解码、非法 Base64、非法 UTF-8 三种路径strings_test.go。UTF-8 清洗valid_utf8## 清洗字符串确保其是合法 UTF-8 ## 每一段非法 UTF-8 字节序列都会被替换为 replacement可为空字符串 # [[processors.strings.valid_utf8]] # field message # replacement valid_utf8调用 Go 的strings.ToValidUTF8把值中每一段连续的非法 UTF-8 字节序列替换为replacement当replacement为空字符串时等价于直接剔除所有非法字节见 strings.go。该函数非常适合处理来自不可靠数据源如外部日志、串口、二进制协议的脏字符串测试TestValidUTF8覆盖了三种典型输入strings_test.go。完整配置示例IIS 日志命名规范化下面这段配置来自 README 的 Example 1展示了一次典型的“组合拳”对uri_stem标签先转小写再剥离/api/前缀同时把cs-host字段大写并存入新字段且不破坏原值[[processors.strings]] [[processors.strings.lowercase]] tag uri_stem [[processors.strings.trim_prefix]] tag uri_stem prefix /api/ [[processors.strings.uppercase]] field cs-host dest cs-host_normalised输入iis_log,methodget,uri_stem/API/HealthCheck cs-hostMIXEDCASE_host,http_version1.1 1519652321000000000输出iis_log,methodget,uri_stemhealthcheck cs-hostMIXEDCASE_host,http_version1.1,cs-host_normalisedMIXEDCASE_HOST 1519652321000000000注意两点uri_stem被原地改写先 lowercase 后 trim_prefix两步串行cs-host原值保留变换结果写入新字段cs-host_normalised。该示例在测试TestReadmeExample中被完整还原验证strings_test.go。标签键/字段键变换第二个完整示例Example 2 展示了**对键名key**做变换的能力把标签键URI-Stem先转小写、再把连字符替换为下划线[[processors.strings]] [[processors.strings.lowercase]] tag_key URI-Stem [[processors.strings.replace]] tag_key uri-stem old - new _输入iis_log,URI-Stem/API/HealthCheck http_version1.1 1519652321000000000输出iis_log,uri_stem/API/HealthCheck http_version1.1 1519652321000000000注意这里执行顺序的妙用第一步把URI-Stem改写为uri-stem第二步才能以uri-stem为目标命中它再完成- → _的替换。如果两步顺序颠倒第二步将因找不到uri-stem而无效——这正是“操作按配置顺序执行”这一语义的实战体现。源码中键变换的实现会先移除旧键再添加新键当变换结果为空字符串时则跳过删除与重建见 strings.go 与 strings.go。源码级执行原理从 strings.go 可以还原出完整的执行模型Apply是唯一入口每个指标依次遍历所有已初始化的转换器逐条执行strings.go。惰性初始化initOnce首次调用时将各子表配置组装为带具体函数闭包的 converter 列表注册顺序固定为lowercase → uppercase → titlecase → trim → trim_left → trim_right → trim_prefix → trim_suffix → replace → left → base64decode → valid_utf8strings.go。该顺序决定了同一指标内不同类型变换的兜底次序因此测试注释中也提醒读者注意这一点strings_test.go。字段值类型安全字段值的变换仅作用于字符串类型数字、布尔等非字符串字段会被自动跳过见 strings.goTestMultipleConversions中的ignore_number、ignore_bool字段即验证了这一行为strings_test.go。目标缺失即跳过指定的 tag/field 不存在时转换器直接返回、不做任何操作如 strings.go。跟踪指标不丢失TestTrackedMetricNotLost验证了在配合 metric tracking送达确认机制时即使发生 UTF-8 清洗指标的投递信息也能被正确送达strings_test.go。与全局配置及处理器排序协同strings处理器支持所有处理器通用的全局配置项见 docs/CONFIGURATION.mdalias为插件实例命名便于日志区分order显式指定处理器执行顺序从 1 开始未指定order的处理器按配置出现顺序执行log_level覆盖该插件的日志级别metric filtering通用参数namepass、tagpass、fieldpass等可用于限定只处理部分指标。官方文档给出了一个与rename处理器配合、用order保证次序的示例docs/CONFIGURATION.md[[processors.rename]] order 1 [[processors.rename.replace]] tag path dest resource [[processors.strings]] order 2 [[processors.strings.trim_prefix]] tag resource prefix /api/这里rename先把标签path复制为resourcestrings再对resource剥离/api/前缀。由于涉及跨插件的先后依赖必须通过order显式声明执行顺序否则结果不可预期。使用建议与注意事项先小写/大写、再裁剪/替换是常见的高效组合——键名经过大小写归一化后更容易被后续规则精确命中参考第二个示例。涉及通配符*时不要配置dest该参数会被忽略若需要保留原始字段请将变换拆分为单独的、指定具体名称的配置块。需要跨多个处理器实例保证顺序时务必为所有相关处理器设置order。base64decode与valid_utf8都遵循“失败或结果不合法则保留原值”的保守策略可放心用于不可靠来源的数据不会引入额外脏数据。字段值变换只作用于字符串类型混合类型的字段会被安全跳过不会报错。若需深入阅读可继续查看 插件 README、示例配置、完整源码 与 1200 余行测试用例或参照 docs/PROCESSORS.md 了解如何编写自定义处理器插件。【免费下载链接】telegrafAgent for collecting, processing, aggregating, and writing metrics, logs, and other arbitrary data.项目地址: https://gitcode.com/GitHub_Trending/te/telegraf创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考