Monitoring & Metrics

Monitoring tốt trả lời hai câu hỏi khác nhau: Jenkins còn phục vụ được không, và hệ thống còn đủ năng lực để build bắt đầu cũng như hoàn tất đúng kỳ vọng không. Trang này biến hai câu hỏi đó thành health check, metrics, dashboard và alert có runbook.

Mục lụcCopy Anchor Link

• Mô hình giám sát
  • Liveness readiness availability và capacity
  • Luồng dữ liệu giám sát
• Health checks HTTP an toàn
  • Chọn tín hiệu đúng mục đích
  • Endpoint authentication và CSRF
  • Tài nguyên và build health
• Prometheus metrics
  • Plugin endpoint và phiên bản
  • Scrape qua TLS và tài khoản tối thiểu
  • Labels và cardinality
  • Queries khởi điểm
• Dashboard và SLI SLO
• Alerting có thể hành động
  • Rule mẫu
  • Giảm alert storm
• Lab local với mock metrics
  • Chuẩn bị dữ liệu mẫu
  • Kiểm tra và đọc kết quả
• Troubleshooting
• Checklist trước khi publish
• Nguồn chính thức
• Đọc tiếp

Mô hình giám sátCopy Anchor Link

Controller nhận HTTP request, giữ cấu hình, queue và trạng thái build. Agent mới là nơi chạy phần lớn workload. Do đó một probe HTTP xanh chỉ là tín hiệu controller còn phản hồi; nó không chứng minh agent, executor, disk, SCM hay Pipeline đang khỏe. Khái niệm controller, queue và executor được giải thích nền tảng trong Kiến trúc Jenkins.

Liveness readiness availability và capacityCopy Anchor Link

Đừng dùng liveness để autoscale hoặc kết luận capacity. Ví dụ /login trả 200 trong khi tất cả agent linux && docker offline; controller sống nhưng hotfix vẫn chờ vô hạn. Ngược lại, queue có thể dài chủ đích trong maintenance hoặc vì giới hạn concurrency, không làm liveness thất bại.

Luồng dữ liệu giám sátCopy Anchor Link

direction: down
U: "Người dùng hoặc webhook"
J: "Jenkins controller"
Q: "Build queue"
A: "Agent và executor"
B: "Pipeline build test"
M: "/prometheus/ nội bộ"
P: "Prometheus scrape qua TLS"
D: "Dashboard và SLO"
R: "Alert rules"
AM: "Alertmanager dedupe route"
O: "On-call và runbook"

U -> J
J -> Q
Q -> A
A -> B
J -> M
M -> P
P -> D
P -> R
R -> AM
AM -> O

Luồng trên tách telemetry ra khỏi luồng build. Prometheus phải là client được cấp quyền tối thiểu trên network nội bộ; không publish endpoint metrics qua Internet chỉ để dashboard có dữ liệu.

Health checks HTTP an toànCopy Anchor Link

Chọn tín hiệu đúng mục đíchCopy Anchor Link

Dùng một probe GET nông cho liveness, ví dụ URL UI chuẩn như https://jenkins.example.internal/login, sau khi đã xác nhận mã phản hồi thực tế qua reverse proxy của tổ chức. Image Docker chính thức thường dùng /login cho healthcheck; đó là kiểm tra HTTP, không phải API contract đầy đủ. Khi chạy Kubernetes, dùng path, initialDelaySeconds, timeout và failure threshold phù hợp với thời gian khởi động thực của controller, thay vì copy ngưỡng từ một cluster khác.

Readiness nên kết hợp ít nhất các điều kiện có chủ đích: controller đã xong startup, route TLS/reverse proxy hoạt động và không có maintenance/quiet-down ngoài kế hoạch. Với Jenkins vanilla, không giả định có một endpoint native duy nhất chứng minh mọi plugin và agent đã sẵn sàng. Một smoke check chỉ đọc trạng thái hoặc một build sandbox đã được phê duyệt có thể là tín hiệu availability sâu hơn, nhưng không nên chạy nó mỗi vài giây như liveness probe.

Endpoint authentication và CSRFCopy Anchor Link

Jenkins thường bảo vệ UI, API và metrics bằng authentication/authorization. Probe và scraper chỉ cần đọc endpoint, dùng một service account riêng và quyền tối thiểu. Giới hạn ingress sao cho chỉ load balancer, kubelet hoặc Prometheus đã biết mới chạm được controller; áp dụng TLS đến điểm phù hợp với mô hình proxy của tổ chức.

CSRF protection (Jenkins crumb) bảo vệ request thay đổi trạng thái như POST. Một GET health/metrics không nên tắt CSRF, thêm crumb exemption hoặc mở anonymous access để "cho chạy probe". Nếu script vận hành thực sự phải gọi API ghi, lấy crumb theo tài liệu Jenkins, dùng token của service account và giới hạn quyền; không tái dùng cơ chế đó cho health check.

# Chỉ chạy từ máy quản trị hoặc network monitoring được cho phép.
# Không ghi token vào shell history, source repository hay output CI.
export JENKINS_URL='https://jenkins.example.internal'
export JENKINS_SCRAPER_USER='prometheus-scraper'
export JENKINS_SCRAPER_TOKEN='<read-from-secret-manager>'

curl --fail --silent --show-error \
  --user "${JENKINS_SCRAPER_USER}:${JENKINS_SCRAPER_TOKEN}" \
  "${JENKINS_URL}/prometheus/" \
  | head -n 20

Lệnh trên là kiểm tra có xác thực với giá trị minh họa, không phải cách lưu secret. Trong production, để Prometheus đọc password_file nằm trên filesystem được bảo vệ hoặc cơ chế secret của platform; không đặt token thẳng trong YAML, label hoặc annotation.

Tài nguyên và build healthCopy Anchor Link

Theo dõi controller và agent tách riêng. Trên controller, theo dõi JVM/heap (used, max, GC pause), CPU, process restart/uptime, filesystem chứa JENKINS_HOME, free bytes/inodes, latency HTTP và lỗi reverse proxy. Heap tăng liên tục sau full GC, disk/inode gần đầy hoặc pause GC dài đều có thể làm UI và scheduler chậm trước khi tiến trình chết.

Trên agent, theo dõi trạng thái online/offline, offline cause, executor defined/online/busy/idle, CPU/RAM, disk/inodes của workspace và cache, I/O wait, network và provisioning/quota của agent động. Phân tách theo pool label: executor rảnh ở windows không giải quyết job đòi linux && docker. Xem cách diễn giải labels và executors tại Labels & Executors.

Build health là outcome theo job/Pipeline: queue wait, runtime, tỷ lệ FAILURE/UNSTABLE/ABORTED, test failure, stage chậm, build bị kẹt và artifact/storage lỗi. Nó là tín hiệu chất lượng dịch vụ CI, khác với "JVM còn chạy". Baseline hữu ích là so sánh p50/p95 với chính workload cùng branch/pool trong một cửa sổ thời gian, không trộn nightly nặng với hotfix.

Prometheus metricsCopy Anchor Link

Plugin endpoint và phiên bảnCopy Anchor Link

Prometheus Metrics Plugin (prometheus) xuất metrics của plugin và của Metrics Plugin ở endpoint mặc định /prometheus/. Endpoint cấu hình khác được phép, nhưng scraper phải dùng đúng path và dấu / cuối; thiếu slash có thể nhận 302, một số scraper không theo redirect như mong đợi.

Các metrics plugin-specific thường có ci_jenkins_up, ci_jenkins_executors_queue_length, ci_jenkins_executors_busy, ci_jenkins_nodes_online và build counters. Collector per-build thêm label số build cho mọi run giữ lại; đây là nguồn cardinality và chi phí scrape/storage đáng kể. Chỉ bật nó khi có use case và giới hạn tuổi hoặc số build mỗi job.

Scrape qua TLS và tài khoản tối thiểuCopy Anchor Link

Bật authentication cho Prometheus endpoint nếu mô hình quyền của bạn yêu cầu. Plugin có tùy chọn này và dùng quyền Metrics/View; cấp quyền đó cho service account scrape, không cấp Overall/Administer. Kiểm tra quyền thực tế của plugin/version đang dùng bằng account test trước khi áp dụng vào Prometheus.

Ví dụ sau chỉ là cấu hình tham khảo. Tên DNS, CA, server name và file token đều là giá trị minh họa; file token phải được mount read-only với quyền đọc chỉ cho tiến trình Prometheus. static_configs chỉ chứa địa chỉ private hay service DNS nội bộ, không dùng IP public.

scrape_configs:
  - job_name: jenkins-controller
    scheme: https
    metrics_path: /prometheus/
    scrape_interval: 30s
    scrape_timeout: 10s
    basic_auth:
      username: prometheus-scraper
      password_file: /etc/prometheus/secrets/jenkins-scraper-token
    tls_config:
      ca_file: /etc/prometheus/ca/internal-ca.pem
      server_name: jenkins.example.internal
    static_configs:
      - targets:
          - jenkins.example.internal:443
        labels:
          environment: staging
          service: jenkins-controller

Ngoài TLS, giới hạn network theo allowlist/security group/NetworkPolicy từ Prometheus đến controller và theo ingress từ proxy đến endpoint. Đừng dùng insecure_skip_verify: true để "sửa" lỗi chứng chỉ; sửa CA, SAN hoặc server_name. Không expose /prometheus/, API token, basic-auth header hoặc file secret ra Internet, dashboard public, repository hay console log.

Labels và cardinalityCopy Anchor Link

Label làm một metric có ngữ cảnh, nhưng mỗi tổ hợp label là một time series. Giữ labels ổn định, ít giá trị và có ích cho câu hỏi vận hành: environment, controller, pool hoặc job đã được chuẩn hóa. Đặt external labels ở Prometheus khi chúng là thuộc tính scrape; không sao chép cùng giá trị vào mọi collector nếu không cần.

Tránh labels có giá trị gần như vô hạn hoặc chứa dữ liệu nhạy cảm: build number, commit SHA, branch/PR name không giới hạn, timestamp, workspace path, URL đầy query string, parameter đầu vào, username, email, token hoặc secret. Plugin cảnh báo rõ rằng thêm build parameters và per-build metrics có thể tạo cardinality cao. Nếu cần truy vết một build, dùng URL build/log có kiểm soát quyền thay vì biến từng run thành series lâu dài.

Queries khởi điểmCopy Anchor Link

Các query dưới đây giả sử namespace ci; thay toàn bộ tiền tố sau khi xem output thật. Nếu metric có labels khác dự kiến, sửa aggregation theo label đang tồn tại thay vì thêm label bịa ra.

# Controller báo chưa sẵn sàng nhận request theo collector của plugin.
ci_jenkins_up == 0

# Số item đã có thể chạy nhưng đang đợi executor trống.
sum(ci_jenkins_executors_queue_length)

# Tỷ lệ executor bận: dùng cùng scope controller/pool khi labels có mặt.
sum(ci_jenkins_executors_busy)
  / clamp_min(sum(ci_jenkins_executors_online), 1)

# Tốc độ build failure trong 15 phút; phân nhóm job chỉ khi label job ổn định.
sum by (job) (increase(ci_jenkins_builds_failed_build_count[15m]))

# Job có kết quả last build không thành công theo boolean của plugin.
max by (job) (ci_jenkins_builds_last_build_result == 0)

JVM, GC và process metric do Metrics Plugin xuất ra có thể đổi tên theo plugin/version. Khám phá bằng cách tìm jvm, heap, gc, process trong endpoint hoặc metric browser trước; dashboard phải tham chiếu tên đã scrape được, không sao chép một tên từ hệ khác.

Dashboard và SLI SLOCopy Anchor Link

Thiết kế dashboard theo người đang điều tra, không chỉ theo danh sách metric. Mỗi panel cần khoảng thời gian, scope controller/pool và liên kết đến runbook hoặc Jenkins UI liên quan.

SLI là phép đo, SLO là mục tiêu được đồng thuận; cả hai cần phạm vi và cửa sổ rõ ràng. "Queue dưới 5 phút" chỉ có ý nghĩa khi nói rõ pool nào, build nào và có loại trừ maintenance đã thông báo hay không. Dashboard nên cho drill-down từ panel queue sang Build Queue, Nodes và log; phần log/diagnostic được xử lý riêng tại tài liệu quản trị khi trang đó hoàn thiện.

Alerting có thể hành độngCopy Anchor Link

Alert tốt có owner, tác động, ngưỡng, duration, severity và runbook. Cảnh báo availability khi người dùng bị ảnh hưởng; cảnh báo capacity khi có nguy cơ vi phạm SLO; dùng ticket hoặc dashboard cho tín hiệu cần theo dõi nhưng chưa cần đánh thức on-call.

Rule mẫuCopy Anchor Link

File bên dưới không áp dụng rule thật. controller, namespace và runbook URL đều là giá trị minh họa; kiểm tra tên metric và scope labels trên Prometheus trước khi nạp vào bất kỳ Alertmanager nào.

groups:
  - name: jenkins-baseline-example
    rules:
      - alert: JenkinsControllerUnavailable
        expr: ci_jenkins_up == 0
        for: 5m
        labels:
          severity: critical
          service: jenkins-controller
        annotations:
          summary: "Jenkins controller {{ $labels.instance }} không sẵn sàng"
          runbook_url: "https://runbooks.example.internal/jenkins/controller-unavailable"

      - alert: JenkinsExecutorQueueSustained
        expr: sum(ci_jenkins_executors_queue_length) > 5
        for: 15m
        labels:
          severity: warning
          service: jenkins-controller
        annotations:
          summary: "Queue Jenkins duy trì trên 5 item trong 15 phút"
          runbook_url: "https://runbooks.example.internal/jenkins/queue-capacity"

      - alert: JenkinsNoAgentsOnline
        expr: sum(ci_jenkins_nodes_online) < 1
        for: 10m
        labels:
          severity: critical
          service: jenkins-controller
        annotations:
          summary: "Không còn Jenkins agent online"
          runbook_url: "https://runbooks.example.internal/jenkins/agents-offline"

Ngưỡng > 5, 5m, 15m và 10m là điểm bắt đầu, không phải chuẩn chung. Chọn chúng từ baseline và SLO: một queue nightly dài 15 phút có thể bình thường, nhưng hotfix queue 5 phút có thể là critical. Với disk, alert warning trước khi hết headroom và critical trước ngưỡng có thể làm controller/agent không ghi được dữ liệu; dựa trên tốc độ đầy disk thay vì chỉ một phần trăm tĩnh nếu có dữ liệu.

Mỗi runbook nên bắt đầu bằng: xác nhận alert còn firing, xem dashboard đúng controller/pool, đọc Build Queue và offline cause, kiểm tra thay đổi gần đây, rồi mới chọn hành động khôi phục. Runbook phải nêu điều không được làm, ví dụ không restart controller để chữa thiếu executor và không mở anonymous metrics để chữa scrape 401.

Giảm alert stormCopy Anchor Link

• Route Alertmanager theo service, environment, controller và severity; group các alert cùng nguyên nhân để một controller down không gửi hàng trăm alert job/agent phụ.
• Dùng inhibition: khi JenkinsControllerUnavailable critical firing, ức chế alert queue/agent phụ thuộc cùng controller. Không ức chế alert disk hoặc security độc lập chỉ vì controller có vấn đề.
• Thêm for để loại spike scrape ngắn, repeat_interval hợp lý và maintenance silence có thời hạn, lý do và owner. Không xóa rule để dập noise.
• Alert trên triệu chứng có tác động (queue age/SLO, toàn bộ pool offline, disk nguy hiểm), không alert từng job failure mặc định. Job quan trọng có thể có rule riêng và owner rõ ràng.
• Dedupe dựa trên labels ổn định. Không thêm build_number, commit hay timestamp vào alert labels; chúng phá grouping và tạo một notification cho mỗi run.

Lab local với mock metricsCopy Anchor Link

Lab này chỉ kiểm tra định dạng exposition và cách đọc metric; nó không chạm Jenkins, Prometheus production, token hay alert thật. Cần Docker để chạy promtool trong container tạm. Nếu không có Docker, chạy cùng file bằng một bản promtool đã cài local.

Chuẩn bị dữ liệu mẫuCopy Anchor Link

mkdir -p /tmp/jenkins-monitoring-lab
cd /tmp/jenkins-monitoring-lab

cat > jenkins.prom <<'EOF'
# HELP ci_jenkins_up Jenkins ready to receive requests
# TYPE ci_jenkins_up gauge
ci_jenkins_up 1
# HELP ci_jenkins_executors_queue_length Items waiting for a free executor
# TYPE ci_jenkins_executors_queue_length gauge
ci_jenkins_executors_queue_length 7
# HELP ci_jenkins_executors_busy Busy Jenkins executors
# TYPE ci_jenkins_executors_busy gauge
ci_jenkins_executors_busy 3
# HELP ci_jenkins_executors_online Online Jenkins executors
# TYPE ci_jenkins_executors_online gauge
ci_jenkins_executors_online 4
# HELP ci_jenkins_nodes_online Online Jenkins nodes
# TYPE ci_jenkins_nodes_online gauge
ci_jenkins_nodes_online 2
EOF

docker run --rm \
  -v "$PWD:/work:ro" \
  prom/prometheus:latest \
  promtool check metrics /work/jenkins.prom

Không dùng tag latest cho hạ tầng production; ở đây nó chỉ làm lab local ngắn gọn. Khi tự động hóa lab/CI, pin image digest hoặc version đã phê duyệt.

Kiểm tra và đọc kết quảCopy Anchor Link

1. Kết quả SUCCESS từ promtool nghĩa là file mock tuân thủ Prometheus text exposition format; nó không chứng minh Jenkins plugin đã được cài.
2. Giá trị queue là 7, nên rule mẫu sum(ci_jenkins_executors_queue_length) > 5 có điều kiện đúng. Nó chỉ firing sau khi duy trì đủ for: 15m trong Prometheus thật.
3. Tỷ lệ executor bận từ mock là 3 / 4 = 0.75. Đây là dấu hiệu cần quan sát cùng queue age, CPU, disk và lý do queue, không tự động là một alert critical.
4. Để chuyển sang sandbox Jenkins, cài plugin đã được phê duyệt, đặt namespace ci, bật authentication, scrape từ Prometheus nội bộ rồi so sánh tên metric thật với mock. Không copy secret hoặc endpoint sandbox sang production.

TroubleshootingCopy Anchor Link

Checklist trước khi publishCopy Anchor Link

• Phân biệt liveness, readiness, availability và capacity; probe HTTP không được dùng thay queue/agent/build health.
• Health check đã thử qua route TLS/proxy thực tế, có timeout/threshold phù hợp startup và không nới auth/CSRF chỉ vì probe.
• Controller JVM/heap/GC, JENKINS_HOME disk/inodes và agent CPU/RAM/disk/I/O đều có owner/panel.
• Queue, executor và agent offline được xem theo pool label; build outcome và runtime được đo riêng với health HTTP.
• Plugin ID, version, Jenkins LTS compatibility, endpoint, namespace và collectors tùy chọn đã xác minh trên sandbox.
• Prometheus scrape dùng TLS, private network allowlist, service account quyền tối thiểu và secret file/secret manager; metrics không public.
• Labels không chứa secret hay giá trị động; per-build/parameter metrics có giới hạn cardinality và retention.
• Dashboard có controller, queue, agent, pipeline và storage; mỗi SLI/SLO có scope, cửa sổ và owner.
• Alert có threshold, duration, severity, dedupe/grouping, inhibition hợp lý và URL runbook đã review; có kế hoạch silence maintenance có hạn.
• Lab/mock hoặc sandbox đã xác nhận exposition format, scrape path slash cuối và kết quả query trước rollout.

Nguồn chính thứcCopy Anchor Link

• Jenkins Prometheus Metrics Plugin — endpoint, phiên bản đang phát hành và cấu hình plugin.
• Prometheus Plugin README — endpoint mặc định, slash cuối và metrics do plugin xuất.
• Jenkins Metrics Plugin — metrics nền tảng được Prometheus plugin đưa ra.
• Jenkins Security: CSRF Protection — crumbs cho thao tác thay đổi trạng thái.
• Jenkins Managing Nodes — node, agent và executor để điều tra capacity.
• Prometheus Configuration — scrape_configs, TLS và service discovery.
• Prometheus Alerting Rules và Alertmanager Configuration — duration, grouping, routing và inhibition.
• Prometheus Instrumentation Best Practices — tên metric và kiểm soát cardinality.

Đọc tiếpCopy Anchor Link