18.9.7 日志与监控体系建设建议

日志与监控体系建设应以可追溯、可定位、可预警为目标，覆盖 Jenkins 控制器、构建节点、流水线执行与依赖系统。建议采用“分层日志 + 指标监控 + 告警联动”的闭环，统一目录、规范命名、设置滚动与保留策略，避免磁盘占满导致服务异常。

日志分层与目录规范（示例）#

系统级日志：/var/log/syslog、/var/log/messages、/var/log/journal/
Jenkins 应用日志：/var/log/jenkins/jenkins.log
构建日志：$JENKINS_HOME/jobs/<job>/builds/<build>/log
插件与外部集成日志：$JENKINS_HOME/logs/（日志记录器）

日志滚动配置（systemd + logrotate）#

# /etc/logrotate.d/jenkins
/var/log/jenkins/jenkins.log {
  daily
  rotate 14
  compress
  missingok
  notifempty
  copytruncate
}

# 验证 logrotate 是否生效
logrotate -d /etc/logrotate.d/jenkins
# 强制执行一次轮转
logrotate -f /etc/logrotate.d/jenkins

Jenkins 日志记录器（Log Recorder）#

在 Jenkins UI 中配置“管理 Jenkins -> 系统日志 -> 添加日志记录器”
示例记录器名称：pipeline-debug
Logger：org.jenkinsci.plugins.workflow
级别：FINE

作用：定位 Pipeline 解析与执行中的细节错误，如 stage 失败、脚本语法异常等。

日志采集与结构化解析（ELK/EFK 示例）#

以 Filebeat 为例采集 Jenkins 控制器日志和构建日志：

# 安装 Filebeat（Ubuntu）
apt-get update && apt-get install -y filebeat

# /etc/filebeat/filebeat.yml
filebeat.inputs:
  - type: log
    enabled: true
    paths:
      - /var/log/jenkins/jenkins.log
      - /var/lib/jenkins/jobs/*/builds/*/log
    fields:
      service: jenkins
      logtype: build
    multiline.pattern: '^\s'
    multiline.match: after

output.elasticsearch:
  hosts: ["http://elk.example.com:9200"]

# 启动并检查状态
systemctl enable --now filebeat
systemctl status filebeat

预期效果：ELK 中可按 service:jenkins、logtype:build 检索日志；多行异常堆栈被合并。

监控指标采集（Prometheus + Jenkins Exporter）#

安装 Jenkins Exporter 插件#

在 Jenkins 插件管理中安装：Prometheus metrics
访问指标端点：http://jenkins.example.com/prometheus

# Prometheus scrape 配置示例
scrape_configs:
  - job_name: 'jenkins'
    static_configs:
      - targets: ['jenkins.example.com:8080']
    metrics_path: /prometheus

关键指标与告警示例#

# Alertmanager 规则示例（规则片段）
groups:
- name: jenkins.rules
  rules:
  - alert: JenkinsDown
    expr: up{job="jenkins"} == 0
    for: 2m
    labels:
      severity: critical
    annotations:
      summary: "Jenkins不可用"
      description: "Jenkins实例连续2分钟无响应"

  - alert: JenkinsQueueHigh
    expr: jenkins_queue_size > 20
    for: 5m
    labels:
      severity: warning
    annotations:
      summary: "Jenkins队列积压"
      description: "队列长度超过20，持续5分钟"

建议监控指标：
- up（可用性）
- jenkins_queue_size（队列长度）
- jenkins_executor_utilization（并发使用率）
- process_resident_memory_bytes、jvm_gc_pause_seconds（资源与 GC）
- jenkins_plugins_active（插件状态）

流水线日志规范与关键标记（示例）#

pipeline {
  agent any
  stages {
    stage('Build') {
      steps {
        echo "BUILD_START job=${env.JOB_NAME} build=${env.BUILD_NUMBER}"
        sh 'mvn -v'
      }
    }
    stage('Test') {
      steps {
        echo "TEST_START"
        sh 'mvn test'
      }
    }
  }
  post {
    failure {
      echo "BUILD_FAIL error_stage=${env.STAGE_NAME}"
    }
    success {
      echo "BUILD_SUCCESS"
    }
  }
}

作用：日志检索时可通过 BUILD_START/BUILD_FAIL 快速定位流程阶段。

常见故障排查（日志与监控视角）#

磁盘占满导致 Jenkins 无法写日志

df -h /var/log /var/lib/jenkins
du -sh /var/lib/jenkins/jobs/*/builds | sort -h | tail

处理：清理旧构建日志或缩短保留策略。

构建日志缺失或采集不到

# 检查构建日志文件是否存在
ls -l /var/lib/jenkins/jobs/<job>/builds/<build>/log
# 检查 Filebeat 是否匹配路径
filebeat test config -c /etc/filebeat/filebeat.yml

监控指标端点返回 403

curl -I http://jenkins.example.com/prometheus
# 如果返回 403，检查权限或启用匿名读取

解决：在 Jenkins 安全策略中允许 Prometheus 读取，或使用 Token。

练习与验证#

练习 1：构建失败定位
- 人为在 Pipeline 中添加 sh 'exit 1'
- 通过 ELK 搜索 BUILD_FAIL，定位失败 stage
- 记录耗时与失败原因
练习 2：告警联动
- 在 Prometheus 中临时设定 jenkins_queue_size > 0 告警
- 验证 Alertmanager 是否推送通知
- 使用告警中的链接跳转到日志检索页
练习 3：日志滚动验证
- 通过 logrotate -f 强制轮转
- 验证 /var/log/jenkins/jenkins.log.1.gz 是否生成

建议的运行规范#

每季度审查日志量、告警有效性与误报率
关键字段脱敏（token/密码）
构建日志按项目与周期归档
复盘异常事件并更新运维 SOP
告警与日志关联：从告警一键跳转到相关日志检索（减少 MTTR）