Prometheus 监控 Jenkins 全栈实战：从构建队列到节点健康的 CI/CD 可观测性

Prometheus 监控 Jenkins 全栈实战：从构建队列到节点健康的 CI/CD 可观测性

Jenkins 作为持续集成与持续交付（CI/CD）的核心引擎，一旦它的 构建队列积压、执行器耗尽、节点离线、JVM 内存泄漏 或 插件异常，整个软件交付流水线就会中断，导致发布延迟甚至线上事故。Prometheus 通过官方的 Jenkins Prometheus Plugin 能将 Jenkins 的内部状态以标准格式暴露，无需额外 Exporter。本文将带你从安装插件、配置抓取，到解读核心指标、构建 Grafana 大屏与告警规则，让 Jenkins 的每一个角落都透明可控。

1. 方案选型：Prometheus Plugin vs JMX Exporter

本文采用 Prometheus Plugin，它开箱即用且指标最贴合 CI/CD 场景。

2. 安装并配置 Prometheus Plugin

2.1 安装插件

• 登录 Jenkins → 系统管理 → 插件管理 → 可选插件。
• 搜索 Prometheus metrics，勾选安装并重启 Jenkins。

或者通过 CLI 安装：

jenkins-plugin-cli --plugins prometheus:2.1.0

2.2 配置指标暴露

安装后无需额外配置，插件默认暴露端点：

• URL：http://jenkins.example.com:8080/prometheus
• 格式：Prometheus 文本格式，包含 Job、Node、Executor、Queue 等指标。

可选配置（系统管理 → 系统配置 → Prometheus Metrics）：

• 设置自定义标签（如 instance_name、env）以便在 Prometheus 中区分多个 Jenkins 实例。
• 开启或关闭特定采集器（如 BuildInfoCollector、DiskUsageCollector）。
• 配置路径前缀（默认 /prometheus）。

验证：

curl http://localhost:8080/prometheus

应看到 jenkins_executor_count、jenkins_job_build_duration_seconds_sum 等指标。

2.3 安全控制

生产环境建议限制 /prometheus 端点的访问权限：

• 使用 Jenkins 的 矩阵授权策略 或 角色策略，仅允许监控用户访问。
• 或通过反向代理（Nginx）添加 Basic Auth。
• 注意：如果 Jenkins 本身需要登录，Prometheus 抓取时需携带认证信息（见后文）。

3. 配置 Prometheus 抓取

3.1 未启用安全认证的抓取

scrape_configs:
  - job_name: 'jenkins'
    scrape_interval: 30s
    metrics_path: '/prometheus'
    static_configs:
      - targets: ['jenkins-master:8080']
        labels:
          app: 'jenkins'
          env: 'production'

3.2 启用安全认证的抓取

若 Jenkins 需要登录，需在 Prometheus 中配置 basic_auth。建议在 Jenkins 中创建一个专用监控用户（仅读权限）。

  - job_name: 'jenkins'
    scrape_interval: 30s
    metrics_path: '/prometheus'
    basic_auth:
      username: 'prometheus'
      password: 'your_password'
    static_configs:
      - targets: ['jenkins-master:8080']

如果 Jenkins 使用了 API Token，可放在 password 字段中。

3.3 抓取多个 Jenkins Master（多主）

添加多个 target，并为每个实例设置不同的 instance 标签。

4. 核心监控指标与 PromQL

Prometheus Plugin 暴露的指标以 jenkins_ 或 default_jenkins_ 为前缀（取决于插件版本），主要类别如下：

4.1 构建与 Job

PromQL 示例：

• 最近 5 分钟构建失败数：increase(jenkins_job_builds_total{status="fail"}[5m])
• 平均构建时长：rate(jenkins_job_build_duration_seconds_sum[1h]) / rate(jenkins_job_build_duration_seconds_count[1h])
• 某 Job 最后构建结果为失败：jenkins_job_last_build_result{job="my-app-deploy"} == 2

4.2 队列与执行器

PromQL 示例：

• 队列积压：jenkins_queue_size > 5
• 执行器使用率：jenkins_executor_in_use / jenkins_executor_count
• 无可用执行器：jenkins_executor_free == 0

4.3 节点 (Agent) 状态

PromQL 示例：

• 离线节点：jenkins_node_online == 0
• 在线节点数：jenkins_node_online == 1

4.4 JVM 与系统

PromQL 示例：

• 堆内存使用率：jvm_memory_used_bytes{area="heap"} / jvm_memory_max_bytes{area="heap"} * 100
• GC 耗时速率：rate(jvm_gc_collection_seconds_sum[5m])

5. Grafana 仪表盘推荐

• Jenkins Performance Overview：Dashboard ID 9964（最经典），展示构建趋势、队列、执行器、节点状态、JVM 等。
• Jenkins Prometheus：ID 14764，现代版，整合了 Job 成功/失败率与构建时长百分位。
• Jenkins Master Health：ID 13535，侧重 JVM、磁盘、线程池。
• 自定义 CI/CD 大屏：可加入流水线成功率、平均交付时间等指标，结合 Git、ArgoCD 数据。

导入后选择数据源，变量 instance 对应 Jenkins Master。

6. 告警规则实战

groups:
  - name: jenkins_alerts
    rules:
      - alert: JenkinsDown
        expr: up{job="jenkins"} == 0
        for: 1m
        labels:
          severity: critical
        annotations:
          summary: "Jenkins Master {{ $labels.instance }} 不可达"

      - alert: JenkinsBuildQueueBacklog
        expr: jenkins_queue_size > 10
        for: 15m
        labels:
          severity: warning
        annotations:
          summary: "Jenkins 构建队列积压超过 10 个任务"

      - alert: JenkinsExecutorSaturation
        expr: jenkins_executor_free == 0
        for: 10m
        labels:
          severity: critical
        annotations:
          summary: "所有执行器均在使用中，无空闲执行器"

      - alert: JenkinsNodeOffline
        expr: jenkins_node_online == 0
        for: 2m
        labels:
          severity: critical
        annotations:
          summary: "Jenkins 节点 {{ $labels.node }} 已离线"

      - alert: JenkinsJobFailure
        expr: jenkins_job_last_build_result{job=~".*production.*"} == 2
        for: 1m
        labels:
          severity: critical
        annotations:
          summary: "关键 Job {{ $labels.job }} 最后构建失败"

      - alert: JenkinsHighHeapUsage
        expr: (jvm_memory_used_bytes{area="heap"} / jvm_memory_max_bytes{area="heap"}) * 100 > 85
        for: 10m
        labels:
          severity: warning
        annotations:
          summary: "Jenkins 堆内存使用率超过 85%"

可根据实际项目名称调整告警中的正则过滤。

7. 进阶：多 Master、安全与性能优化

7.1 多 Master 监控

如果有多个 Jenkins 实例（如生产与非生产），分别配置抓取并在 Prometheus 中用不同的 instance 标签。Grafana 面板可复用，通过变量切换。

7.2 安全凭据管理

• 使用 Jenkins 的 Credentials Binding 插件为 Prometheus 抓取生成专用 API Token。
• Prometheus 的 basic_auth 直接填写 API Token 作为密码即可。
• 通过反向代理（如 Nginx）统一处理 TLS 和认证，Prometheus 只需连接代理。

7.3 自定义指标标签

在 Jenkins 系统配置的 Prometheus 插件部分，可以添加额外的静态标签，如 datacenter=dc1，方便在 Grafana 中聚合筛选。还可启用 BuildInfoCollector 的额外维度（如 branch、result），但需注意指标基数。

7.4 性能影响

Prometheus 插件基于内存中的注册表，抓取时仅遍历数据结构，对 Jenkins 性能影响极小。建议 scrape_interval 设为 30-60 秒。

7.5 结合 Pipeline 监控

插件会自动为每个 Pipeline Job 暴露指标。可通过 jenkins_job_build_duration_seconds 的 job 标签筛选特定流水线。若需更细粒度的 Stage 指标，可结合 Pipeline Stage View 插件或自定义 Metric 发布（如通过 prometheus-build-metrics 插件）。

8. 总结

通过 Jenkins Prometheus Plugin，CI/CD 流水线的每一个关键点——构建队列深度、执行器使用率、节点在线状态、Job 成功率——都转化为 Prometheus 生态中的标准化指标。你可以在 Grafana 上直观地监控交付速度，用 Alertmanager 在构建失败或节点宕机时第一时间收到通知。将 Jenkins 的可观测性融入全栈监控体系，意味着软件交付的最后一块拼图也被点亮，真正实现从代码提交到上线运行的全链路透明化。部署它，让自动化构建不再“盲飞”，为持续交付保驾护航。