Telegraf outputs.groundwork 输出插件详解将指标推送到 GroundWork Monitor【免费下载链接】telegrafAgent for collecting, processing, aggregating, and writing metrics, logs, and other arbitrary data.项目地址: https://gitcode.com/GitHub_Trending/te/telegraf本篇技术指南以 Telegraf 的outputs.groundwork输出插件文档为核心完整覆盖该插件的全部配置项、标签语义与状态机规则并结合 groundwork.go 源码与 groundwork_test.go 测试用例讲清 Telegraf 指标到 GroundWork Monitor 监控对象的映射过程、初始化校验逻辑以及字符串字段被跳过的限制。读完本文你可以完成插件的部署配置理解阈值与状态的优先级覆盖规则并能基于源码定位上报 payload 的生成细节。插件定位与版本要求outputs.groundwork是一个输出插件用于把 Telegraf 采集到的指标写入 GroundWork Monitor 实例GroundWork 是一款第三方监控平台。插件在 Telegraf v1.21.0 引入运行于所有平台。根据 README 中的重要提示该插件仅支持 GroundWork v8 或更新版本对接更低版本的服务端时不可用。插件通过标准输出插件注册机制接入 Telegraf注册代码与默认值集中在 groundwork.go 的init()中func init() { outputs.Add(groundwork, func() telegraf.Output { return Groundwork{ GroupTag: group, ResourceTag: host, DefaultHost: telegraf, DefaultAppType: TELEGRAF, DefaultServiceState: string(transit.ServiceOk), } }) }默认值同时体现在 sample.conf 的注释项中。在自定义构建custom build场景下该插件由 plugins/outputs/all/groundwork.go 通过构建标签outputs.groundwork引入//go:build !custom || outputs || outputs.groundwork import _ github.com/influxdata/telegraf/plugins/outputs/groundwork // register plugin完整配置与参数说明以下配置完整继承自 sample.conf即插件SampleConfig()嵌入的配置可直接复制到 telegraf 配置文件中# Send telegraf metrics to GroundWork Monitor [[outputs.groundwork]] ## URL of your groundwork instance. url https://groundwork.example.com ## Agent uuid for GroundWork API Server. agent_id ## Username and password to access GroundWork API. username password ## Default application type to use in GroundWork client # default_app_type TELEGRAF ## Default display name for the host with services(metrics). # default_host telegraf ## Default service state. # default_service_state SERVICE_OK ## The name of the tag that contains the hostname. # resource_tag host ## The name of the tag that contains the host group name. # group_tag group各参数含义、默认值与校验行为如下默认值取自 groundwork.go 的init()校验行为取自Init()配置项默认值说明url无必填GroundWork 实例的访问地址agent_id无必填GroundWork API Server 的 Agent UUIDusername无必填访问 GroundWork API 的用户名支持 secret storepassword无必填访问 GroundWork API 的密码支持 secret storedefault_app_typeTELEGRAF上报到 GroundWork 客户端的默认应用类型default_hosttelegraf承载服务即指标的主机默认显示名default_service_stateSERVICE_OK服务默认状态必须是合法状态值resource_taghost存放主机名的 tag 名称group_taggroup存放主机组名的 tag 名称插件遵循 Telegraf 的通用插件配置机制别名、排序、标签与字段过滤等这些通用能力在 CONFIGURATION.md 中有统一说明。初始化校验与连接生命周期Init()groundwork.go在启动阶段逐项校验配置任一缺失都会以明确错误信息使插件初始化失败url为空no url providedagent_id为空no agent_id providedusername/password为空no username provided/no password provideddefault_host、resource_tag为空同样报错default_service_state不是合法状态值invalid default_service_state provided随后Init()从 secret store或直接字符串取出用户名和密码构造底层 SDK 客户端clients.GWClient其中AppName固定为telegraf、IsDynamicInventory设为true即动态清单模式主机与组随上报自动建立。SDK 日志会被适配为 Telegraf 日志日志分组为tcg.sdk。底层 SDK 为github.com/gwos/tcg/sdk具体版本可在 go.mod 中查到当前为v0.0.0-20240830123415-f8a34bba6358。Connect()调用client.Connect()完成登录失败时报could not loginClose()调用client.Disconnect()登出失败时报could not logout。Secret store 支持username与password两项支持从 secret store 读取秘密值对应 CONFIGURATION.md 中 Secret store secrets 一节。在代码中这两个字段声明为config.Secret类型groundwork.go读取成功后会立即调用Destroy()清理内存中的明文避免凭据驻留。指标到 GroundWork payload 的映射规则这是理解该插件的核心。Write()groundwork.go接收一批 Telegraf 指标后先逐条调用parseMetric()将每个指标转换为一个 GroundWork 的MonitoredService服务对象再把指标按 tag 聚合成Groups主机组与Resources主机最终序列化为transit.ResourcesWithServicesRequest发送。每次Write都会生成一个新的 UUID 作为TraceToken写入请求上下文连同AppType、AgentID、时间戳与模型版本一起构成追踪上下文。结构映射指标 → 服务 → 主机 → 主机组parseMetric()groundwork.go的映射规则如下主机资源取resource_tag默认hosttag 的值作为主机名若指标上没有该 tag则回退到default_host默认telegraf。服务默认取指标名metric name作为服务名如果指标带有servicetag则用该 tag 的值覆盖服务名。主机组取group_tag默认grouptag 的值带组 tag 的指标会把其主机作为HostGroup类型的一个成员引用汇入对应transit.ResourceGroup。主机状态每个被聚合出的主机在 payload 中固定标记为HostUp。其他 tag不属于已知关键字的 tag 会被原样写入服务的Properties类型为字符串TypedValue。已知关键字包括以_cr/_wn结尾的 tag、critical、warning、group_tag、resource_tag、service、status、message、unitType见knownKey判断逻辑。其他字段非字符串字段成为服务下的一条时间序列TimeSeries带值、单位与阈值unitTypetag 决定单位缺省为计数器类型UnitCounter。文档定义的标签清单及其语义README 中List of tags used by the plugin一节定义的标签在源码中的落点一一对应group定义要监控的主机组名可通过group_tag改名host定义要监控的主机名可通过resource_tag改名service定义服务名覆盖默认用指标名做服务名的规则status定义服务状态支持的值只有SERVICE_OK、SERVICE_WARNING、SERVICE_UNSCHEDULED_CRITICAL、SERVICE_PENDING、SERVICE_SCHEDULED_CRITICAL、SERVICE_UNKNOWN六个由 groundwork.go 的validStatus()白名单校验message提供任意消息覆盖message字段值unitType监控上下文中使用的单位UCUM 标准的子集文档声明支持1、%cpu、KB、GB、MBcritical定义默认严重阈值覆盖value_cr字段warning定义默认警告阈值覆盖value_wn字段value_cr定义严重阈值覆盖criticaltag 与value_cr字段value_wn定义警告阈值覆盖warningtag 与value_wn字段。阈值与状态的优先级源码细节文档描述的覆盖关系在 groundwork.go 中有精确实现。对每个数值字段field严重阈值的取用顺序是tagfield_cr→tagcritical→fieldfield_cr警告阈值同理依次为tagfield_wn→tagwarning→fieldfield_wn。tag 形式取到后还会做ParseFloat校验无法解析为浮点数的 tag 值会被忽略并落到下一优先级。这与 README 的表述tag 覆盖 field一致且补充了一个文档未强调的细节field_cr这种按字段命名的 tag 优先级高于通用的criticaltag。状态status的判定顺序在 groundwork.gotagstatus合法 → 直接采用否则 fieldstatusstring 或 []byte且合法 → 采用否则调用 SDK 的transit.CalculateServiceStatus()根据已收集的阈值关系自动计算服务状态计算出错时回退到default_service_state默认SERVICE_OK。message的处理同样 tag 优先messagetag 存在即覆盖messagefieldgroundwork.go。此外服务对象的NextCheckTime会被显式设置为与LastCheckTime相同源码注释说明这是为了避免 GroundWork 自行推断出LastCheckTime 5 分钟的下次检查时间。字符串值指标的限制README 的 NOTE 部分指出当前版本的 GroundWork Monitor 不支持字符串值的指标此类指标会被跳过、不会加入最终 payload。源码中的对应实现在字段遍历处switch field.Value.(type) { case string, []byte: g.Log.Warnf(string values are not supported, skipping field %s: %q, field.Key, field.Value) continue }groundwork.go被跳过的字段会输出 Warn 级别日志便于在调试时排查为什么某个字段没上报。另外无法转换为TypedValue的非数字类型同样会被跳过并记录警告。测试用例对行为的验证groundwork_test.go 用httptest起了一个模拟 GroundWork 服务器的 HTTP 端点反序列化上报的ResourcesWithServicesRequest后逐项断言 payload共覆盖四种场景TestWriteWithDefaults验证默认值下Context.AgentID、Context.AppType、主机名telegraf、状态SERVICE_OK、服务名与数值 42 均正确送达且Groups为空TestWriteWithFields验证value_cr/value_wn字段成为阈值3.0 / 2.0、message字段写入LastPluginOutput、status字段SERVICE_WARNING生效TestWriteWithTags验证 tag 对 field 的覆盖关系——tagvalue_cr9.0覆盖 fieldvalue_cr3.0、tagstatusSERVICE_PENDING覆盖 fieldstatus、service/resource-tag/group-tag分别决定服务名、主机名与组名以及未知 tagfacility、severity进入PropertiesTestWriteWithDebug开启 debug 日志断言日志中包含 AgentID 与服务端返回的 trace token用于验证 SDK 日志适配链路。这些测试与上文描述的映射规则、优先级完全一致可作为行为契约参考。演进历史从 CHANGELOG.md 可以追溯该插件的关键演进节点最初由 PR #9891 引入#10499 增加了 group tag 处理#10623 将NextCheckTime设为与LastCheckTime相同以避免 GroundWork 臆造下次检查时间#11300 将default_app_type暴露为配置项对应本仓库中的default_app_type选项#11443 改进了指标解析以扩展输出能力。这些记录解释了当前配置项集合的由来。小结outputs.groundwork插件的本质是一个指标到监控对象的转换器Telegraf 指标的 tag 与字段被系统性地映射为 GroundWork 的主机组、主机、服务、时间序列、阈值、状态与消息映射优先级tag 覆盖 field、按字段命名的阈值 tag 优先于通用阈值 tag、状态白名单校验与自动状态计算在源码中有明确实现并由测试用例固化。部署时请注意四个必填项缺失会导致启动失败目标 GroundWork 实例必须是 v8 及以上字符串值字段会被跳过并打印警告日志。【免费下载链接】telegrafAgent for collecting, processing, aggregating, and writing metrics, logs, and other arbitrary data.项目地址: https://gitcode.com/GitHub_Trending/te/telegraf创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/9/14 3:11:56 · 阅读 1.2k Telegraf outputs.groundwork 输出插件详解：将指标推送到 GroundWork Monitor
Telegraf outputs.groundwork 输出插件详解将指标推送到 GroundWork Monitor【免费下载链接】telegrafAgent for collecting, processing, aggregating, and writing metrics, logs, and other arbitrary data.项目地址: https://gitcode.com/GitHub_Trending/te/telegraf本篇技术指南以 Telegraf 的outputs.groundwork输出插件文档为核心完整覆盖该插件的全部配置项、标签语义与状态机规则并结合 groundwork.go 源码与 groundwork_test.go 测试用例讲清 Telegraf 指标到 GroundWork Monitor 监控对象的映射过程、初始化校验逻辑以及字符串字段被跳过的限制。读完本文你可以完成插件的部署配置理解阈值与状态的优先级覆盖规则并能基于源码定位上报 payload 的生成细节。插件定位与版本要求outputs.groundwork是一个输出插件用于把 Telegraf 采集到的指标写入 GroundWork Monitor 实例GroundWork 是一款第三方监控平台。插件在 Telegraf v1.21.0 引入运行于所有平台。根据 README 中的重要提示该插件仅支持 GroundWork v8 或更新版本对接更低版本的服务端时不可用。插件通过标准输出插件注册机制接入 Telegraf注册代码与默认值集中在 groundwork.go 的init()中func init() { outputs.Add(groundwork, func() telegraf.Output { return Groundwork{ GroupTag: group, ResourceTag: host, DefaultHost: telegraf, DefaultAppType: TELEGRAF, DefaultServiceState: string(transit.ServiceOk), } }) }默认值同时体现在 sample.conf 的注释项中。在自定义构建custom build场景下该插件由 plugins/outputs/all/groundwork.go 通过构建标签outputs.groundwork引入//go:build !custom || outputs || outputs.groundwork import _ github.com/influxdata/telegraf/plugins/outputs/groundwork // register plugin完整配置与参数说明以下配置完整继承自 sample.conf即插件SampleConfig()嵌入的配置可直接复制到 telegraf 配置文件中# Send telegraf metrics to GroundWork Monitor [[outputs.groundwork]] ## URL of your groundwork instance. url https://groundwork.example.com ## Agent uuid for GroundWork API Server. agent_id ## Username and password to access GroundWork API. username password ## Default application type to use in GroundWork client # default_app_type TELEGRAF ## Default display name for the host with services(metrics). # default_host telegraf ## Default service state. # default_service_state SERVICE_OK ## The name of the tag that contains the hostname. # resource_tag host ## The name of the tag that contains the host group name. # group_tag group各参数含义、默认值与校验行为如下默认值取自 groundwork.go 的init()校验行为取自Init()配置项默认值说明url无必填GroundWork 实例的访问地址agent_id无必填GroundWork API Server 的 Agent UUIDusername无必填访问 GroundWork API 的用户名支持 secret storepassword无必填访问 GroundWork API 的密码支持 secret storedefault_app_typeTELEGRAF上报到 GroundWork 客户端的默认应用类型default_hosttelegraf承载服务即指标的主机默认显示名default_service_stateSERVICE_OK服务默认状态必须是合法状态值resource_taghost存放主机名的 tag 名称group_taggroup存放主机组名的 tag 名称插件遵循 Telegraf 的通用插件配置机制别名、排序、标签与字段过滤等这些通用能力在 CONFIGURATION.md 中有统一说明。初始化校验与连接生命周期Init()groundwork.go在启动阶段逐项校验配置任一缺失都会以明确错误信息使插件初始化失败url为空no url providedagent_id为空no agent_id providedusername/password为空no username provided/no password provideddefault_host、resource_tag为空同样报错default_service_state不是合法状态值invalid default_service_state provided随后Init()从 secret store或直接字符串取出用户名和密码构造底层 SDK 客户端clients.GWClient其中AppName固定为telegraf、IsDynamicInventory设为true即动态清单模式主机与组随上报自动建立。SDK 日志会被适配为 Telegraf 日志日志分组为tcg.sdk。底层 SDK 为github.com/gwos/tcg/sdk具体版本可在 go.mod 中查到当前为v0.0.0-20240830123415-f8a34bba6358。Connect()调用client.Connect()完成登录失败时报could not loginClose()调用client.Disconnect()登出失败时报could not logout。Secret store 支持username与password两项支持从 secret store 读取秘密值对应 CONFIGURATION.md 中 Secret store secrets 一节。在代码中这两个字段声明为config.Secret类型groundwork.go读取成功后会立即调用Destroy()清理内存中的明文避免凭据驻留。指标到 GroundWork payload 的映射规则这是理解该插件的核心。Write()groundwork.go接收一批 Telegraf 指标后先逐条调用parseMetric()将每个指标转换为一个 GroundWork 的MonitoredService服务对象再把指标按 tag 聚合成Groups主机组与Resources主机最终序列化为transit.ResourcesWithServicesRequest发送。每次Write都会生成一个新的 UUID 作为TraceToken写入请求上下文连同AppType、AgentID、时间戳与模型版本一起构成追踪上下文。结构映射指标 → 服务 → 主机 → 主机组parseMetric()groundwork.go的映射规则如下主机资源取resource_tag默认hosttag 的值作为主机名若指标上没有该 tag则回退到default_host默认telegraf。服务默认取指标名metric name作为服务名如果指标带有servicetag则用该 tag 的值覆盖服务名。主机组取group_tag默认grouptag 的值带组 tag 的指标会把其主机作为HostGroup类型的一个成员引用汇入对应transit.ResourceGroup。主机状态每个被聚合出的主机在 payload 中固定标记为HostUp。其他 tag不属于已知关键字的 tag 会被原样写入服务的Properties类型为字符串TypedValue。已知关键字包括以_cr/_wn结尾的 tag、critical、warning、group_tag、resource_tag、service、status、message、unitType见knownKey判断逻辑。其他字段非字符串字段成为服务下的一条时间序列TimeSeries带值、单位与阈值unitTypetag 决定单位缺省为计数器类型UnitCounter。文档定义的标签清单及其语义README 中List of tags used by the plugin一节定义的标签在源码中的落点一一对应group定义要监控的主机组名可通过group_tag改名host定义要监控的主机名可通过resource_tag改名service定义服务名覆盖默认用指标名做服务名的规则status定义服务状态支持的值只有SERVICE_OK、SERVICE_WARNING、SERVICE_UNSCHEDULED_CRITICAL、SERVICE_PENDING、SERVICE_SCHEDULED_CRITICAL、SERVICE_UNKNOWN六个由 groundwork.go 的validStatus()白名单校验message提供任意消息覆盖message字段值unitType监控上下文中使用的单位UCUM 标准的子集文档声明支持1、%cpu、KB、GB、MBcritical定义默认严重阈值覆盖value_cr字段warning定义默认警告阈值覆盖value_wn字段value_cr定义严重阈值覆盖criticaltag 与value_cr字段value_wn定义警告阈值覆盖warningtag 与value_wn字段。阈值与状态的优先级源码细节文档描述的覆盖关系在 groundwork.go 中有精确实现。对每个数值字段field严重阈值的取用顺序是tagfield_cr→tagcritical→fieldfield_cr警告阈值同理依次为tagfield_wn→tagwarning→fieldfield_wn。tag 形式取到后还会做ParseFloat校验无法解析为浮点数的 tag 值会被忽略并落到下一优先级。这与 README 的表述tag 覆盖 field一致且补充了一个文档未强调的细节field_cr这种按字段命名的 tag 优先级高于通用的criticaltag。状态status的判定顺序在 groundwork.gotagstatus合法 → 直接采用否则 fieldstatusstring 或 []byte且合法 → 采用否则调用 SDK 的transit.CalculateServiceStatus()根据已收集的阈值关系自动计算服务状态计算出错时回退到default_service_state默认SERVICE_OK。message的处理同样 tag 优先messagetag 存在即覆盖messagefieldgroundwork.go。此外服务对象的NextCheckTime会被显式设置为与LastCheckTime相同源码注释说明这是为了避免 GroundWork 自行推断出LastCheckTime 5 分钟的下次检查时间。字符串值指标的限制README 的 NOTE 部分指出当前版本的 GroundWork Monitor 不支持字符串值的指标此类指标会被跳过、不会加入最终 payload。源码中的对应实现在字段遍历处switch field.Value.(type) { case string, []byte: g.Log.Warnf(string values are not supported, skipping field %s: %q, field.Key, field.Value) continue }groundwork.go被跳过的字段会输出 Warn 级别日志便于在调试时排查为什么某个字段没上报。另外无法转换为TypedValue的非数字类型同样会被跳过并记录警告。测试用例对行为的验证groundwork_test.go 用httptest起了一个模拟 GroundWork 服务器的 HTTP 端点反序列化上报的ResourcesWithServicesRequest后逐项断言 payload共覆盖四种场景TestWriteWithDefaults验证默认值下Context.AgentID、Context.AppType、主机名telegraf、状态SERVICE_OK、服务名与数值 42 均正确送达且Groups为空TestWriteWithFields验证value_cr/value_wn字段成为阈值3.0 / 2.0、message字段写入LastPluginOutput、status字段SERVICE_WARNING生效TestWriteWithTags验证 tag 对 field 的覆盖关系——tagvalue_cr9.0覆盖 fieldvalue_cr3.0、tagstatusSERVICE_PENDING覆盖 fieldstatus、service/resource-tag/group-tag分别决定服务名、主机名与组名以及未知 tagfacility、severity进入PropertiesTestWriteWithDebug开启 debug 日志断言日志中包含 AgentID 与服务端返回的 trace token用于验证 SDK 日志适配链路。这些测试与上文描述的映射规则、优先级完全一致可作为行为契约参考。演进历史从 CHANGELOG.md 可以追溯该插件的关键演进节点最初由 PR #9891 引入#10499 增加了 group tag 处理#10623 将NextCheckTime设为与LastCheckTime相同以避免 GroundWork 臆造下次检查时间#11300 将default_app_type暴露为配置项对应本仓库中的default_app_type选项#11443 改进了指标解析以扩展输出能力。这些记录解释了当前配置项集合的由来。小结outputs.groundwork插件的本质是一个指标到监控对象的转换器Telegraf 指标的 tag 与字段被系统性地映射为 GroundWork 的主机组、主机、服务、时间序列、阈值、状态与消息映射优先级tag 覆盖 field、按字段命名的阈值 tag 优先于通用阈值 tag、状态白名单校验与自动状态计算在源码中有明确实现并由测试用例固化。部署时请注意四个必填项缺失会导致启动失败目标 GroundWork 实例必须是 v8 及以上字符串值字段会被跳过并打印警告日志。【免费下载链接】telegrafAgent for collecting, processing, aggregating, and writing metrics, logs, and other arbitrary data.项目地址: https://gitcode.com/GitHub_Trending/te/telegraf创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考