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 Agentnomad是一个 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参数详解参数类型默认值说明urlstringhttp://127.0.0.1:4646Nomad agent 的 HTTP API 地址。插件会向url/v1/metrics发起请求response_timeout时长duration5sHTTP 响应头超时时间支持5s、1m等写法tls_ca/tls_cert/tls_key字符串空可选 TLS 配置CA 文件、客户端证书、私钥路径除上述插件专属参数外该插件还支持 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.gon.loadJSON(n.URL/v1/metrics, summaryMetrics)—— 发起 HTTP GET 请求要求状态码为 200否则返回HTTP status错误随后将响应体解码为metricsSummary结构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.gometricsSummary及其子类型gaugeValue、pointValue、sampledValue映射逻辑与字段如下API 类型accumulator 方法生成的字段fields标签来源tagscountersAddCountercount、rate、sum、sumsq、min、max、meanLabelsDisplayLabelsgaugesAddGaugevalueLabelspointsAddFieldsvalue整个点数组无samplesAddCountercount、rate、sum、stddev、sumsq、min、max、meanLabels对应实现见 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.goLabels以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.jsonGauges: [ { 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_eligibilityeligible, hostnode1, node_id2bbff078-..., datacenterdc1, node_classnone, node_statusready fields: value500 time: 2021-11-13 22:39:00 UTC 由响应 timestamp 字段解析同文件中的 counternomad.nomad.rpc.query字段count7, max1, min1, mean1, rate0.7, sum7, sumsq0和 samplenomad.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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考