企业官网建设流程全解析

Telegraf Jenkins 输入插件实战指南：采集节点与作业构建指标

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

本篇技术指南围绕 Telegraf 官方 Jenkins 输入插件（inputs.jenkins）展开，讲解如何通过 Jenkins 原生 API 采集集群执行器、节点资源与作业构建状态等指标。读者将掌握该插件的完整配置参数、三类输出指标（jenkins、jenkins_node、jenkins_job）的字段语义、基于源码的底层采集原理，以及可直接落地的 InfluxQL 查询示例。

该插件自 Telegraf v1.9.0 起可用，分类为 applications（应用类），支持全平台（Linux / Windows / macOS）运行。它直接调用 Jenkins HTTP API 完成数据获取，无需在 Jenkins 服务端安装任何插件，配置轻量、侵入性为零。

插件简介与工作原理

Jenkins 输入插件用于收集 Jenkins 实例中节点（Node）与作业（Job）的运行信息，包括：

• 集群层面的执行器使用情况（忙/总执行器数）；
• 每个节点的 CPU 架构、磁盘/临时目录可用空间、内存与 Swap 可用量、响应时间、执行器数量与在线状态；
• 每个作业最近若干次构建的持续时间、构建号、构建结果。

从源码结构看（见 jenkins.go），插件的采集流程非常直接：在Gather方法中依次调用gatherNodesData与gatherJobs，全部数据都来自 Jenkins 的 REST API，不依赖服务端侧插件。这意味着只要 Telegraf 能通过 HTTP(S) 访问到 Jenkins 地址，即可完成接入。

全局配置选项说明

与其他 Telegraf 插件一样，inputs.jenkins支持全局配置选项（例如name_prefix、name_override、tags、fieldpass/fielddrop、tagpass/tagdrop等，用于修改指标名、标签、字段以及控制插件执行顺序）。完整说明见 CONFIGURATION.md，文中的"Plugins"一节对此有系统介绍。

基本配置示例

以下是插件官方样例配置（见 sample.conf），可直接复制到 Telegraf 配置文件中使用：

# Read jobs and cluster metrics from Jenkins instances [[inputs.jenkins]] ## The Jenkins URL in the format "schema://host:port" url = "http://my-jenkins-instance:8080" # username = "admin" # password = "admin" ## Set response_timeout response_timeout = "5s" ## Optional TLS Config # tls_ca = "/etc/telegraf/ca.pem" # tls_cert = "/etc/telegraf/cert.pem" # tls_key = "/etc/telegraf/key.pem" ## Use SSL but skip chain & host verification # insecure_skip_verify = false ## Optional Max Job Build Age filter ## Default 1 hour, ignore builds older than max_build_age # max_build_age = "1h" ## Optional Sub Job Depth filter ## Jenkins can have unlimited layer of sub jobs ## This config will limit the layers of pulling, default value 0 means ## unlimited pulling until no more sub jobs # max_subjob_depth = 0 ## Optional Sub Job Per Layer ## In workflow-multibranch-plugin, each branch will be created as a sub job. ## This config will limit to call only the lasted branches in each layer, ## empty will use default value 10 # max_subjob_per_layer = 10 ## Jobs to include or exclude from gathering ## When using both lists, job_exclude has priority. ## Wildcards are supported: [ "jobA/*", "jobB/subjob1/*"] # job_include = [ "*" ] # job_exclude = [ ] ## Nodes to include or exclude from gathering ## When using both lists, node_exclude has priority. # node_include = [ "*" ] # node_exclude = [ ] ## Worker pool for jenkins plugin only ## Empty this field will use default value 5 # max_connections = 5 ## When set to true will add node labels as a comma-separated tag. If none, ## are found, then a tag with the value of 'none' is used. Finally, if a ## label contains a comma it is replaced with an underscore. # node_labels_as_tag = false

配置参数详解

连接地址与认证

从 jenkins.go 的源码可以看出，插件在initialize阶段会解析 URL：当端口缺省时自动推断——http协议默认补80，https协议默认补443，并取主机名（Hostname）作为source标签的值。认证方式为 HTTP Basic Auth（见 client.go 中createGetRequest的SetBasicAuth调用）。

实践建议：出于安全考虑，优先使用具备最小权限的 Jenkins 用户，或使用 Jenkins API Token 作为密码，而非管理员明文口令。

TLS 配置

与 Telegraf 其他输入插件一致，支持以下 TLS 选项（通过内嵌的tls.ClientConfig提供，相关实现见 tls 公共库）：

• tls_ca：CA 证书路径，用于校验 Jenkins 服务端证书；
• tls_cert：客户端证书路径（若 Jenkins 启用了双向 TLS）；
• tls_key：客户端私钥路径；
• insecure_skip_verify：设为true时跳过证书链与主机名校验（仅建议在测试环境使用）。

作业与节点过滤

过滤逻辑基于filter.NewIncludeExcludeFilter实现（见 jenkins.go）。对于作业，过滤匹配的是完整层级路径，例如多级作业apps/k8s-cloud/PR-100，其匹配名称为带/分隔的层级字符串（对应源码中的hierarchyName()方法）。

子作业深度与每层数量（多分支流水线场景）

这两个参数对性能影响显著：在分支数量巨大的多分支流水线中，如果不对深度和每层数量做限制，插件会递归遍历全部子作业，产生大量 HTTP 请求。源码中getJobDetail在jr.layer == j.MaxSubJobDepth时直接返回（深度限制），每层只取最后MaxSubJobPerLayer个作业（按 Jenkins API 返回顺序的尾部，即最新的分支）。

构建年龄过滤

实现上，插件在 jenkins.go 中以cutoff := time.Now().Add(-1 * time.Duration(j.MaxBuildAge))计算截止时间，凡是构建时间戳早于截止时间的构建都被跳过。该机制能有效控制单次采集的数据量与 API 调用次数。

并发连接池

源码中通过semaphore chan struct{}（容量为max_connections）实现并发限流，且初始化时若该值<= 0会强制回退为默认值 5。作业遍历、子作业递归均采用 goroutine + WaitGroup 的方式并发执行（见 jenkins.go 的gatherJobs与getJobDetail）。

节点标签

标签的归一化规则（见 jenkins.go 的gatherNodeData）：

• 若节点没有任何标签，则labels = "none"；
• 若标签名中包含逗号，逗号会被替换为下划线_；
• 多个标签按字典序排序后以逗号连接。

采集的数据指标详解

插件输出三类指标，命名常量定义在 jenkins.go 中：jenkins、jenkins_node、jenkins_job。

jenkins—— 集群汇总指标

用于描述整个 Jenkins 集群的执行器状态。

• tags：
  • source：Jenkins 主机名
  • port：Jenkins 端口（缺省时按协议推断 80/443）
• fields：
  • busy_executors（int）：忙碌中的执行器数量
  • total_executors（int）：执行器总数

数据来源为/computer/api/json接口返回的busyExecutors与totalExecutors字段。

jenkins_node—— 节点指标

描述每个 Jenkins 节点（含 master 与各 slave agent）的资源与状态。

• tags：
  • arch：节点 CPU 架构（来自 ArchitectureMonitor）
  • disk_path：磁盘监控路径（来自 DiskSpaceMonitor）
  • temp_path：临时目录监控路径（来自 TemporarySpaceMonitor）
  • node_name：节点显示名称
  • status：节点状态，"online"或"offline"
  • source、port：同上
• fields（单位标注见官方文档）：
  • disk_available（Bytes）：磁盘可用空间
  • temp_available（Bytes）：临时目录可用空间
  • memory_available（Bytes）：可用物理内存
  • memory_total（Bytes）：物理内存总量
  • swap_available（Bytes）：可用 Swap 空间
  • swap_total（Bytes）：Swap 总量
  • response_time（ms）：节点平均响应时间
  • num_executors：节点上配置的执行器数量

值得注意的实现细节：status标签由节点的offline布尔字段推导（true为offline，否则为online，见 jenkins.go）；磁盘、临时目录、内存/Swap、响应时间等字段分别来自 Jenkins 节点监控数据中的hudson.node_monitors.DiskSpaceMonitor、TemporarySpaceMonitor、SwapSpaceMonitor、ResponseTimeMonitor。若某个监控项未启用或返回为空，对应的字段与标签将不会被写入。

jenkins_job—— 作业构建指标

描述作业最近若干次构建的耗时与结果。

• tags：
  • name：作业名
  • parents：父作业层级路径（以/分隔，顶层作业为空字符串）
  • result：构建结果原文（如SUCCESS、FAILURE）
  • source、port：同上
• fields：
  • duration（ms）：构建持续时间
  • number：构建号
  • result_code：构建结果编码，0 = SUCCESS，1 = FAILURE，2 = NOT_BUILD，3 = UNSTABLE，4 = ABORTED

result_code的映射由mapResultCode函数实现（见 jenkins.go），对结果字符串做大小写无关匹配；若遇到无法识别的结果，返回-1。该字段的意义在于：InfluxDB 等时序数据库无法高效地按字符串标签做数值运算，而result_code可以直接用于聚合统计成功率。

此外，jenkins_job指标的时间戳取自构建自身的时间戳（b.getTimestamp()），而非采集时刻，因此在查询历史构建时能准确反映构建发生的时间。

底层实现原理（源码视角）

初始化流程

插件首次Gather时完成初始化（initialize方法，见 jenkins.go）：

1. 解析 URL，推导source与port标签；
2. 编译作业过滤与节点过滤；
3. 应用max_connections（默认 5）与max_subjob_per_layer（默认 10）的兜底默认值；
4. 创建并发信号量；
5. 创建 API 客户端并执行首次握手请求。

值得说明的是，默认值同时在 jenkins.go 的init()注册函数中被初始化（MaxBuildAge = 1h、MaxConnections = 5、MaxSubJobPerLayer = 10），保证未显式配置时行为一致。

会话与认证处理

client.go 中的client.init()会先请求 Jenkins 根路径以获取会话 Cookie（名为JSESSIONID），后续请求携带该 Cookie 并附带 Basic Auth 头。若请求返回401 Unauthorized，插件会清除失效的会话 Cookie 并返回带 URL 与状态码的错误信息（apiError类型）。

API 路径与 tree 参数

插件主要访问以下 Jenkins API 端点（常量定义见 client.go）：

• /computer/api/json：获取节点列表与执行器统计（getAllNodes）；
• /api/json：获取顶层作业列表（getJobs）；
• /job/<name>/api/json：获取指定作业的构建列表与子作业（嵌套作业路径逐级拼接/job/）；
• /job/<name>/<number>/api/json：获取单个构建的详情（getBuild）。

关键优化点：在获取作业详情时，请求会携带tree查询参数——

?tree=builds[number,url]{0,20},lastBuild[number,url],jobs[name,url,color],name

其中{0,20}表示仅获取最新的 20 条构建记录（maxBuildsPerJob = 20，见 client.go）。这从源头限制了单作业的数据量，避免为每个作业拉取全部历史构建。测试用例TestGatherBuildsCappedAt20专门验证了该行为：即使作业有 25 条构建，构建详情请求也不会超过 20 次。

构建采集的过滤链路

在getJobDetail中，对每个构建依次做如下判断（见 jenkins.go）：

1. 构建号小于 1 的跳过；
2. 进行中的构建（building = true）跳过——避免对运行中构建写入不完整的result与duration；
3. 时间戳早于max_build_age截止时间的跳过；
4. 若构建列表为空，回退使用lastBuild（且其构建号需大于等于 1）；
5. 单个构建详情请求失败时，仅记录错误并继续处理其他构建（部分成功策略）。

这些行为在 jenkins_test.go 中均有对应测试：TestGatherJobBuilds覆盖了多构建、运行中构建跳过、旧构建过滤、lastBuild 回退、旧构建夹杂在新构建之间等场景；TestGatherBuildFetchErrorPartial验证了单个构建拉取 404 时其余构建仍正常上报。

示例查询

以下 SQL 基于 InfluxDB，可直接用于监控面板。

查询最近 15 分钟内各节点的内存、临时目录可用情况：

SELECT mean("memory_available") AS "mean_memory_available", mean("memory_total") AS "mean_memory_total", mean("temp_available") AS "mean_temp_available" FROM "jenkins_node" WHERE time > now() - 15m GROUP BY time(:interval:) FILL(null)

查询最近 24 小时内各作业的平均构建耗时：

SELECT mean("duration") AS "mean_duration" FROM "jenkins_job" WHERE time > now() - 24h GROUP BY time(:interval:) FILL(null)

此外，结合result_code字段可以统计构建成功率，例如按作业聚合：

SELECT count("result_code") AS "total_builds", sum("result_code" = 0) AS "success_builds" FROM "jenkins_job" WHERE time > now() - 24h GROUP BY "name"

示例输出

以下为官方文档给出的真实输出样例（节选），展示三类指标的完整形态：

jenkins,host=myhost,port=80,source=my-jenkins-instance busy_executors=4i,total_executors=8i 1580418261000000000 jenkins_node,arch=Linux\ (amd64),disk_path=/var/jenkins_home,temp_path=/tmp,host=myhost,node_name=master,source=my-jenkins-instance,port=8080 swap_total=4294963200,memory_available=586711040,memory_total=6089498624,status=online,response_time=1000i,disk_available=152392036352,temp_available=152392036352,swap_available=3503263744,num_executors=2i 1516031535000000000 jenkins_job,host=myhost,name=JOB1,parents=apps/br1,result=SUCCESS,source=my-jenkins-instance,port=8080 duration=2831i,result_code=0i 1516026630000000000 jenkins_job,host=myhost,name=JOB2,parents=apps/br2,result=SUCCESS,source=my-jenkins-instance,port=8080 duration=2285i,result_code=0i 1516027230000000000

解读要点：

• jenkins指标带host（Telegraf 默认host标签）、source、port三个标签；
• jenkins_node中arch含空格，行协议中以\转义；status=online表示节点在线；
• jenkins_job中parents=apps/br1表示该作业位于apps/br1层级之下，result_code=0对应SUCCESS。

测试与质量保障

插件测试集中在 jenkins_test.go，采用httptest.NewServer模拟 Jenkins API，覆盖了以下关键行为：

• URL 层级构建：TestJobRequestURL验证嵌套作业 URL 的拼接与特殊字符（空格）的 URL 转义；
• 结果编码：TestResultCode验证大小写无关的状态映射；
• 节点采集：TestGatherNodeData覆盖空监控数据、完整监控数据、节点过滤、离线节点等场景；
• 标签采集：TestGatherLabels验证node_labels_as_tag的排序、逗号替换与none兜底；
• 作业构建：TestGatherJobBuilds、TestGatherJobs覆盖多构建、嵌套作业、多分支流水线、通配符过滤等复杂拓扑；
• 上限保护：TestGatherBuildsCappedAt20验证 tree 参数与每作业最多 20 条构建的限制。

常见问题与排障建议

1. 采集不到任何数据：先确认 Telegraf 主机能否直接访问url指向的地址与端口；再检查 Jenkins 是否开启了 CSRF 保护（新版 Jenkins 默认开启），若使用 API Token 认证可绕过大部分限制。
2. 401 Unauthorized错误：检查username/password是否正确。从源码看，认证失败时会清除会话 Cookie 并返回[<url>] 401 Unauthorized形式的错误，该错误会通过acc.AddError记录在 Telegraf 日志中。
3. 采集超时：当 Jenkins 作业/节点数量庞大时，可适当调大response_timeout，或通过max_subjob_depth、max_subjob_per_layer、job_include/job_exclude收敛采集范围；同时可通过max_connections调节并发度。
4. 指标量过大：优先使用job_exclude与通配符排除非关键作业（如"apps/ignore-all/*"），并依赖默认的max_build_age = 1h过滤历史构建。
5. 多分支流水线采集过慢：确认max_subjob_per_layer是否为合适的值（默认 10），该参数专门用于限制每层分支的采集数量。

相关资源

• 插件实现源码：jenkins.go
• API 客户端实现：client.go
• 插件测试用例：jenkins_test.go
• 官方样例配置：sample.conf
• 全局配置选项说明：CONFIGURATION.md

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