Telegraf nomad 输入插件：采集 HashiCorp Nomad 集群遥测指标的实践与源码解析

Telegraf nomad 输入插件：采集 HashiCorp Nomad 集群遥测指标的实践与源码解析

【免费下载链接】telegrafAgent for collecting, processing, aggregating, and writing metrics, logs, and other arbitrary data.项目地址: https://gitcode.com/GitHub_Trending/te/telegraf

本文以 Telegraf 仓库中的plugins/inputs/nomad插件为主体，讲清楚这个插件能采集什么、如何配置、以及指标是如何从 Nomad API 的/v1/metrics响应映射成 Telegraf Metric 的。读完后你可以直接在生产集群中部署该插件，并能对照源码理解每一类指标（counter/gauge/point/sample）的字段与标签来源。

插件定位：连接每一个 Nomad Agent

nomad是一个 server 类型的输入插件（自 Telegraf v1.22.0 引入，支持所有平台）。它的工作方式是：向指定 Nomad agent 的 HTTP API 发起一次GET /v1/metrics请求，把返回的遥测摘要（telemetry summary）整体转换为 Telegraf 指标。

典型的部署形态是"每节点一个 Telegraf"——Telegraf 与 Nomad agent 部署在同一台机器上，通过本地回环地址访问，无需暴露集群 API。这一点在插件源码中有明确体现：nomad.go 中Init()方法在未配置url时默认使用http://127.0.0.1:4646，正是 Nomad agent 的默认 HTTP 端口。

配置说明

以下配置完整继承自仓库中的样例配置文件 sample.conf（该文件通过go:embed内嵌进插件，运行telegraf --usage inputs.nomad时打印的就是它）：

# Read metrics from the Nomad API [[inputs.nomad]] ## URL for the Nomad agent # url = "http://127.0.0.1:4646" ## Set response_timeout (default 5 seconds) # response_timeout = "5s" ## Optional TLS Config # tls_ca = /path/to/cafile # tls_cert = /path/to/certfile # tls_key = /path/to/keyfile

参数详解

除上述插件专属参数外，该插件还支持 Telegraf 的全局插件配置能力（字段/标签过滤、插件别名、插件排序等），详见 CONFIGURATION.md。

从 nomad.go 的源码结构看，Nomad结构体只有三个配置字段（URL、ResponseTimeout、内嵌的tls.ClientConfig），其余运行时对象在Init()中一次性构建：

• tls.ClientConfig.TLSConfig()解析 TLS 参数，生成*tls.Config；
• 基于该配置构造一个专用的http.Transport，其中TLSHandshakeTimeout固定为 5 秒，ResponseHeaderTimeout则取用户配置的response_timeout；
• 插件注册默认值在 nomad.go 的init()中完成：ResponseTimeout初始化为 5 秒。

采集流程与底层实现

每次采集周期内，Gather()的调用链非常直接（见 nomad.go）：

1. n.loadJSON(n.URL+"/v1/metrics", summaryMetrics)—— 发起 HTTP GET 请求，要求状态码为 200，否则返回HTTP status错误；随后将响应体解码为metricsSummary结构；
2. buildNomadMetrics(acc, summaryMetrics)—— 将摘要中的四类指标逐组写入 accumulator。

请求失败的行为

loadJSON()（nomad.go）的错误处理逻辑：

• 请求发起失败 →error making HTTP request to "<url>"；
• 响应码非 200 →<url> returned HTTP status <状态>；
• JSON 解码失败 →error parsing json response。

即单次采集失败会以错误形式上报给 Telegraf agent，下个采集周期自动重试，插件本身不做额外重试或退避。

时间戳解析

buildNomadMetrics首先按固定布局2006-01-02 15:04:05 -0700 MST解析响应中的timestamp字段（见 nomad.go），解析结果作为全部生成指标的时间戳。若响应时间戳格式不符合该布局，整个采集周期会报错——这一点在对接自改 Nomad 版本时需要留意。

指标映射：四种 API 类型到 Telegraf 指标

Nomad API/v1/metrics返回的摘要包含四类数据。插件的响应解码结构定义在 nomad_metrics.go（metricsSummary及其子类型gaugeValue、pointValue、sampledValue），映射逻辑与字段如下：

对应实现见 nomad.go。几个值得注意的细节：

• 指标名直接使用 Nomad 上报的name（如nomad.client.allocated.cpu），并加nomad.前缀命名空间——这是 Nomad 自身指标的命名约定，插件不做改名；
• counters与samples虽然都映射为 Counter 类指标，但samples多一个stddev字段，这与 JSON 中AggregateSample嵌入结构体（含count/rate/sum/min/max）外加mean/stddev字段的布局一致（见 nomad_metrics.go）；
• Labels以map[string]string形式（JSON 键Labels）直接作为 Telegraf 标签，Nomad 会为节点级指标附加host、node_id、datacenter、node_status、node_class等标签，可用于后续按节点/数据中心过滤。

由于 Nomad 侧上报哪些指标由其在nomad.hcl中的 metrics/telemetry 配置决定，插件没有固定的指标清单——"output depends on plugin input"。

用测试用例验证一次真实映射

仓库自带测试 nomad_test.go 用httptest.NewServer模拟了 agent 的/v1/metrics端点，响应体取自 response_key_metrics.json。该测试断言了完整的"输入 JSON → Telegraf Metric"映射，是最可信的行为佐证。以其中的 gauge 为例：

API 响应片段（testdata/response_key_metrics.json）：

"Gauges": [ { "Labels": { "node_scheduling_eligibility": "eligible", "host": "node1", "node_id": "2bbff078-8473-a9de-6c5e-42b4e053e12f", "datacenter": "dc1", "node_class": "none", "node_status": "ready" }, "Name": "nomad.client.allocated.cpu", "Value": 500 } ]

期望生成的 Telegraf 指标：

nomad.client.allocated.cpu tags: node_scheduling_eligibility=eligible, host=node1, node_id=2bbff078-..., datacenter=dc1, node_class=none, node_status=ready fields: value=500 time: 2021-11-13 22:39:00 UTC （由响应 timestamp 字段解析）

同文件中的 counter（nomad.nomad.rpc.query，字段count=7, max=1, min=1, mean=1, rate=0.7, sum=7, sumsq=0）和 sample（nomad.memberlist.gossip，额外含stddev）也按上表断言，验证了字段集合与时间戳来源。测试中SumSq字段标记为json:"-"，即 API 不返回该值，Telegraf 输出中恒为 0——这解释了为什么断言里sumsq为 0。

部署建议与限制

• 访问模型：插件只请求url + /v1/metrics一个端点，属于轻量只读轮询；intervals与插件的interval对齐即可，无需担心对 agent 造成额外压力；
• TLS 场景：若 Nomad agent 的 HTTP 端口启用了 TLS 或 mTLS，配置tls_ca/tls_cert/tls_key即可，底层由 Telegraf 公共 TLS 实现（plugins/common/tls/common.go）统一处理，默认最低 TLS 版本为 1.2；
• 指标含义：Nomad 指标名（如nomad.nomad.rpc.query、nomad.memberlist.gossip、nomad.client.allocated.cpu）的完整语义以 Nomad 官方 metrics/telemetry 文档为准，插件原样透传，不做归一化；
• 版本前提：插件自 Telegraf v1.22.0 可用（README 中标注），时间戳解析布局与响应结构均对应 Nomad API 的当前约定。

插件在构建中的注册入口为 plugins/inputs/all/nomad.go，使用!custom || inputs || inputs.nomad构建标签——即默认构建及启用inputs.nomad自定义构建时都会包含该插件。

【免费下载链接】telegrafAgent for collecting, processing, aggregating, and writing metrics, logs, and other arbitrary data.项目地址: https://gitcode.com/GitHub_Trending/te/telegraf