Troubleshooting Jenkins

Sự cố Jenkins thường biểu hiện giống nhau: build chờ mãi, agent mất kết nối, Pipeline không tiến triển hoặc controller phản hồi chậm. Trang này biến các biểu hiện đó thành một quy trình có thể lặp lại: xác định người chịu trách nhiệm và mức độ ảnh hưởng, giữ timeline, thu bằng chứng chỉ đọc, rồi chỉ thay đổi nhỏ khi giả thuyết đã đủ mạnh.

Mục lụcCopy Anchor Link

• Nguyên tắc và phân loại sự cố
  • Severity, ownership và timeline
  • Bảng phân biệt nhanh
• Decision tree chẩn đoán
• Thu thập bằng chứng chỉ đọc
  • UI, queue và computer
  • Log, process và metrics
  • Support Core và gói escalation
• Queue bị tắc
  • Label không khớp
  • Executor và capacity cạn
• Agent offline
  • Network, authentication và Java
  • Workspace và lỗi phân biệt
• Pipeline treo
  • Timeout, input, lock và step
  • Đọc thread và log mà không che lỗi
• Controller chậm hoặc crash
  • JVM, heap và thread
  • Disk, I/O và plugin
• Thay đổi nhỏ, rollback và xác minh
• Lab sandbox: queue và timeout có chủ đích
• Checklist incident
• Nguồn Jenkins chính thức
• Đọc tiếp

Nguyên tắc và phân loại sự cốCopy Anchor Link

Một triệu chứng không phải là nguyên nhân. Ví dụ, build ở trạng thái Waiting for next available executor có thể do không có node thỏa label, executor đang bận, quota của provisioner đã hết, hoặc controller không kịp provision. Ghi lại câu thông báo nguyên văn, thời điểm theo múi giờ thống nhất và phạm vi bị ảnh hưởng trước khi sửa.

Severity, ownership và timelineCopy Anchor Link

Người nhận incident phải chỉ định incident owner: một người điều phối quyết định, cập nhật trạng thái và giữ bằng chứng. Owner không nhất thiết là người sửa hệ thống. Chỉ định thêm người ghi chép timeline và người liên lạc nếu incident lớn.

Timeline phải có dữ kiện có thể kiểm tra: 10:14 UTC — build #281 bắt đầu chờ label linux-docker; không ghi phỏng đoán như “agent chắc bị hỏng”. Lưu URL build/queue item, build number, node name, phiên bản Jenkins/plugin liên quan và timestamp của log. Khi timestamp giữa controller, agent và hệ thống metrics lệch nhau, dùng một mốc UTC để đối chiếu.

Bảng phân biệt nhanhCopy Anchor Link

Decision tree chẩn đoánCopy Anchor Link

Dùng flow này cho mỗi incident. Một nhánh chỉ dẫn đến giả thuyết, không phải giấy phép thay đổi lớn. Nếu bằng chứng mâu thuẫn, quay lại phạm vi và thu thêm dữ liệu.

direction: down
incident: Triệu chứng + SEV + incident owner
scope: "Phạm vi: 1 build, 1 pool\nhay toàn controller?\nGhi timeline UTC"
executor: Build có executor? {shape: diamond}
queue: Queue label/node/executor?
progress: Stage/step có tiến triển? {shape: diamond}
wait: Input/lock/timeout/I-O?
job: Kiểm tra lỗi nghiệp vụ/log job
evidence: Thu evidence, lập giả thuyết
change: Thay đổi nhỏ, có rollback
verify: Xác minh metric/log/build mới
escalate: "Thiếu evidence hoặc sự cố\ncontroller diện rộng?\nEscalation kèm bundle, timeline, impact"
incident -> scope -> executor
executor -> queue: Không
executor -> progress: Có
progress -> wait: Không
progress -> job: Có
queue -> evidence
wait -> evidence
job -> evidence
evidence -> change -> verify -> escalate

Thu thập bằng chứng chỉ đọcCopy Anchor Link

UI, queue và computerCopy Anchor Link

Các đường dẫn sau chỉ dùng để quan sát khi tài khoản của bạn có quyền đọc. Không cần gọi API có credential để thực hiện triage ban đầu.

Lệnh dưới đây chỉ đọc trạng thái của host chạy controller. Chạy từ bastion hoặc console đã được cấp quyền; thay jenkins bằng tên service thực tế nếu khác.

# systemd: xem trạng thái và log gần đây, không thay đổi service
systemctl status jenkins --no-pager
journalctl -u jenkins --since '30 minutes ago' --no-pager

# Docker: xem container và log gần đây, không restart container
docker ps --filter 'name=jenkins'
docker logs --since 30m <jenkins-container>

# Host: xem dung lượng và I/O/CPU tức thời
df -h
df -ih
uptime

journalctl và docker logs có thể chứa URL repository, tên job hoặc dữ liệu nhạy cảm do plugin in ra. Lọc/redact trước khi gửi ra ngoài phạm vi incident; không dùng set -x trong script thu thập vì nó có thể in biến môi trường.

Log, process và metricsCopy Anchor Link

Khi controller chậm, lấy hai hoặc ba thread dump cách nhau 30–60 giây chỉ khi runbook nội bộ cho phép. Các dump cách nhau giúp phân biệt thread đang tiến triển với deadlock hoặc I/O chờ lâu. Chụp Java process bằng công cụ đã được phê duyệt; không tự ý kill -9 JVM để “lấy lại UI”.

Đối chiếu ít nhất các nhóm tín hiệu sau:

• JVM: heap used/max, GC pause, số thread, OutOfMemoryError, thời điểm restart hoặc exit code.
• Disk/I/O: dung lượng và inode của JENKINS_HOME, latency/throughput disk, lỗi No space left on device, filesystem read-only.
• Controller: HTTP latency/error rate, queue length và tuổi item lâu nhất.
• Agent/pool: online count, executor utilization, provisioning failure/quota, reconnect count.
• Pipeline: stage duration theo baseline, bước external gọi đâu và exit/timeout của nó.

Metrics là bằng chứng xu hướng, còn log là bằng chứng sự kiện. Heap tăng đều cùng GC pause dài ủng hộ giả thuyết JVM pressure; queue tăng trong khi toàn bộ executor cùng bận ủng hộ capacity pressure. Một spike đơn lẻ không đủ để kết luận nguyên nhân gốc.

Support Core và gói escalationCopy Anchor Link

Support Core có thể tạo bundle cho người vận hành hoặc Jenkins support. Chỉ tạo theo chính sách truy cập và retention của tổ chức, vì bundle có thể bao gồm cấu hình, log và metadata nhạy cảm. Rà soát quyền truy cập, mã hóa khi truyền và redaction trước khi đính kèm ticket.

Gói escalation nên có:

• Incident owner, severity, phạm vi kinh doanh và timeline UTC.
• URL/bản build, queue reason hoặc node offline cause; tên job có thể pseudonymize nếu cần.
• Jenkins core version, Java version, plugin thay đổi gần nhất và loại triển khai (systemd, container hoặc Kubernetes).
• Log excerpt có timestamp, metrics snapshot/range và thread dump được phép thu thập.
• Các giả thuyết đã loại trừ, thay đổi nhỏ đã làm, kết quả và rollback state.
• Support Core bundle hoặc vị trí lưu nội bộ có kiểm soát truy cập, không gửi credential hay secret thô.

Queue bị tắcCopy Anchor Link

Queue là nơi Jenkins giữ task trước khi cấp executor. Bắt đầu bằng reason ở /queue/, sau đó đối chiếu expression của job với labels trên /computer/. Xem giải thích nền tảng về controller và queue trong Kiến trúc Jenkins, và quy tắc định tuyến trong Labels & Executors.

Label không khớpCopy Anchor Link

Dấu hiệu điển hình là queue reason nói không có node phù hợp, trong khi có executor rảnh ở node khác. So sánh toàn bộ label expression, không chỉ một từ trong đó: linux && docker && jdk21 không thể chạy trên node chỉ có linux docker.

Không dùng agent any làm cách chữa mặc định. Nó có thể vô tình đưa build release vào node không có toolchain hoặc boundary phù hợp. Đọc Pipeline agents trước khi thay agent directive.

Executor và capacity cạnCopy Anchor Link

Nếu có node khớp và online nhưng mọi executor đều bận, đây là saturation. Đối chiếu thời gian chạy với baseline: một executor “bận” 20 phút có thể là build bình thường, nhưng toàn pool kéo dài gấp nhiều lần baseline cần điều tra Pipeline hoặc external dependency.

1. Ghi số executor bận/rảnh theo từng label pool, queue age và top job chiếm slot.
2. Kiểm tra job có giới hạn concurrency, throttle, lock hoặc upstream dependency không.
3. Phân biệt pool hết capacity với controller chậm: pool hết capacity vẫn có UI/log phản hồi bình thường và executor thực sự chạy build; controller chậm thường làm nhiều thao tác cùng trễ.
4. Chỉ tăng capacity khi có headroom CPU/RAM/disk và workload cho phép concurrency. Lập change có sizing, expiry/rollback và owner.

Agent offlineCopy Anchor Link

Agent offline là vấn đề kết nối hoặc lifecycle của node; nó khác với node online nhưng không có executor rảnh. Ghi offline cause ở /computer/, phương thức launch (inbound, SSH, container/Kubernetes) và thời điểm disconnect đầu tiên. Tổng quan agents cung cấp mô hình controller–agent; các cách dùng agent trong Pipeline nằm ở Pipeline agents.

Network, authentication và JavaCopy Anchor Link

Kiểm tra theo thứ tự gần nguồn lỗi nhất. Nếu controller không thấy agent kết nối, kiểm tra endpoint/network trước; nếu connection bị từ chối sau khi kết nối, kiểm tra authentication/agent secret theo cơ chế nội bộ mà không hiển thị secret; nếu channel mở rồi đóng, kiểm tra log Java/launcher và tương thích version.

Với agent chạy service, chỉ đọc log dịch vụ trước:

# Ví dụ host agent dùng systemd: tên service tùy cài đặt
systemctl status jenkins-agent --no-pager
journalctl -u jenkins-agent --since '30 minutes ago' --no-pager
java -version

# Ví dụ agent container: chỉ xem trạng thái và log
docker ps --filter 'name=jenkins-agent'
docker logs --since 30m <agent-container>

Không sao chép command line chứa -secret, JNLP secret hay biến môi trường nhạy cảm vào ticket. Khi cần chứng minh cấu hình, dùng tên secret reference hoặc fingerprint đã được chính sách cho phép.

Workspace và lỗi phân biệtCopy Anchor Link

Agent Online không khẳng định workspace dùng được. Một build có thể fail ở checkout hoặc step đầu do permission, full disk, stale mount hoặc đường dẫn workspace biến mất. Đây là lỗi sau khi đã schedule, nên không chữa bằng cách sửa label hay tăng executor.

Chỉ dọn workspace theo runbook đã duyệt và sau khi lưu build log/evidence; không xóa hàng loạt workspace để che một lỗi permission hay đầy disk. Nếu cần rollback image/template, ưu tiên phiên bản agent đã biết hoạt động và xác minh bằng canary.

Pipeline treoCopy Anchor Link

Pipeline “treo” chỉ nên được gọi khi có executor nhưng stage/step không có tiến triển ngoài thời lượng dự kiến. Mở build page, xác định stage cuối có timestamp và xem console log từ điểm đó. Hành vi xử lý lỗi và timeout có thể đối chiếu trong Pipeline error handling, còn cấu trúc Pipeline ở Tổng quan Pipeline.

Timeout, input, lock và stepCopy Anchor Link

timeout là guardrail, không thay thế chẩn đoán. Đặt timeout ở scope phù hợp và để build kết thúc rõ là ABORTED/FAILURE; đừng nuốt lỗi bằng try/catch hoặc catchError rồi báo xanh. Đối với input, ghi người duyệt và lý do vào thay đổi/ticket, không đưa URL có token vào message.

Đọc thread và log mà không che lỗiCopy Anchor Link

Nếu nhiều Pipeline cùng kẹt trong cùng step/plugin, mở rộng phạm vi sang controller/plugin. Nếu chỉ một build kẹt ở một external endpoint, bắt đầu ở dependency và agent mạng. So sánh ba mốc: lúc stage bắt đầu, lần log cuối và thời điểm metric đổi. Điều này phân biệt step im lặng nhưng còn chạy với step không còn tiến trình.

Các lỗi cần được giữ nguyên trạng thái:

• timeout phải ghi thông báo có action, không tự retry vô hạn.
• input cần owner/approver rõ ràng và expiry phù hợp.
• lock cần định danh resource và holder có thể truy vết.
• Retry chỉ dành cho failure tạm thời đã biết; log đủ attempt và failure cuối.
• Một Pipeline phải fail trung thực nếu test/deploy thất bại. Không đổi kết quả thành SUCCESS chỉ để giảm alert.

Controller chậm hoặc crashCopy Anchor Link

Khi UI, queue và nhiều build cùng chậm, coi đây là incident controller hoặc hạ tầng chung cho đến khi dữ liệu bác bỏ. Bắt đầu bằng availability, service/container log, timeline restart và tài nguyên host. Tài liệu cài Jenkins bằng Docker và cài Jenkins trên Linux mô tả bối cảnh triển khai thường gặp; chúng không thay thế runbook khôi phục của tổ chức.

JVM, heap và threadCopy Anchor Link

JVM heap không phải là toàn bộ memory của host/container. Đối chiếu memory limit, process RSS, native memory và các sidecar nếu có. Tăng -Xmx khi container không có memory headroom có thể làm container bị OOM kill, nên mọi thay đổi heap phải có baseline, giới hạn, rollback và quan sát sau triển khai.

Disk, I/O và pluginCopy Anchor Link

JENKINS_HOME hết byte hoặc inode có thể làm controller không ghi queue/config/build metadata. Disk latency cao có thể nhìn giống JVM freeze vì nhiều thread chờ filesystem. Đừng xóa build history, artifact hoặc plugin để giải phóng chỗ trong lúc chưa có retention plan và backup/approval.

Plugin là giả thuyết hợp lý khi stack trace/logger chỉ rõ namespace plugin hoặc lỗi bắt đầu ngay sau cập nhật. Nó không phải bằng chứng chỉ vì plugin “mới cài”. Ghi plugin ID/version, Jenkins LTS/Java version, stack trace đã redact và mốc thay đổi. Trong maintenance window hoặc canary được phê duyệt, rollback về phiên bản đã biết hoạt động; xác minh health, queue và một build đại diện. Nếu crash lặp lại hoặc nghi OOM/data corruption, escalation ngay kèm bundle thay vì thử nâng/hạ nhiều plugin.

Thay đổi nhỏ, rollback và xác minhCopy Anchor Link

Một thay đổi tốt chỉ kiểm tra một giả thuyết: sửa một label contract, khôi phục một agent template, đặt timeout cho một step hoặc rollback một plugin đã xác định. Trước khi thực hiện, ghi owner, cửa sổ thay đổi, tác động dự kiến và điều kiện rollback.

Sau thay đổi, không chỉ nhìn build “xanh”. So sánh với baseline ít nhất: queue age/length, executor utilization, latency/error rate controller, reconnect agent và log mới trong một khoảng quan sát phù hợp. Cập nhật timeline bằng kết quả, giữ evidence, rồi quyết định đóng incident hay escalation. Nếu thay đổi làm tác động tăng hoặc tiêu chí không đạt, rollback ngay theo kế hoạch và ghi lại.

Lab sandbox: queue và timeout có chủ đíchCopy Anchor Link

Lab này chỉ dành cho Jenkins sandbox tách production. Trước khi chạy, tạo hoặc kiểm tra một agent sandbox riêng mang label troubleshooting-lab tại /computer/; built-in node phải giữ 0 executor. Không chạy lab input nếu không có agent mang label này, và không gán label đó cho agent production. Với môi trường local, có thể thay bằng một label sandbox riêng tương đương đã kiểm tra, nhưng không dùng any cho lab có input vì nó giữ executor. Lab tạo hai failure dễ nhận biết mà không cần credential thật: label không tồn tại làm build chờ queue, và input có timeout làm build kết thúc rõ ràng. Dùng job riêng như troubleshooting-lab; không chạy trên job release.

pipeline {
  agent none

  stages {
    stage('Queue: label không tồn tại') {
      agent { label 'lab-unavailable' }
      options { timeout(time: 2, unit: 'MINUTES') }
      steps {
        echo 'Nếu không có agent mang lab-unavailable, stage sẽ chờ trong queue.'
      }
    }
  }
}

1. Xác nhận sandbox không có node nào mang label lab-unavailable; ghi lại /computer/ trước khi chạy.
2. Lưu Jenkinsfile vào troubleshooting-lab và chạy một build. Mở /queue/ và Console Log trong lúc build chờ.
3. Kết quả mong đợi: queue reason cho biết không có node phù hợp; sau hai phút, build kết thúc ABORTED do timeout. Đây là timeout có chủ đích, không phải controller failure.
4. Lưu URL build, reason và timestamp vào ghi chú lab. Hủy build sớm chỉ nếu cần giải phóng sandbox; không thay đổi labels của production agent.

Để mô phỏng input chờ duyệt, thay stage trên bằng stage ràng buộc vào agent sandbox đã kiểm tra. Nếu /computer/ không hiển thị agent Online mang label troubleshooting-lab, dừng lab thay vì đổi sang built-in node hoặc any.

pipeline {
  agent { label 'troubleshooting-lab' }

  stages {
    stage('Input có expiry') {
      steps {
        timeout(time: 2, unit: 'MINUTES') {
          input message: 'Lab only: xác nhận bạn đã quan sát trạng thái chờ', ok: 'Tiếp tục'
        }
        echo 'Chỉ chạy khi một người đã duyệt input.'
      }
    }
  }
}

Kết quả mong đợi: UI hiển thị action chờ duyệt; nếu không duyệt trong hai phút, build là ABORTED với dấu vết timeout. Nếu duyệt, log đi đến Chỉ chạy.... So sánh lab này với queue lab: lab input đã giữ executor, còn queue lab chưa được cấp executor. Sau lab, giữ build record để học tập theo retention policy; chỉ xóa job sandbox khi owner sandbox cho phép.

Checklist incidentCopy Anchor Link

• Có severity, incident owner, phạm vi và timeline UTC.
• Đã phân biệt queue trước executor với Pipeline sau executor.
• Đã ghi queue reason, labels, agent state/offline cause hoặc stage/step cuối.
• Đã thu log/metrics chỉ đọc và redact dữ liệu nhạy cảm.
• Đã kiểm tra JVM/heap/thread hoặc disk/I/O khi phạm vi là controller.
• Support Core bundle, nếu có, được lưu/chia sẻ theo chính sách và không chứa secret thô.
• Mọi thay đổi có giả thuyết, owner, rollback và tiêu chí xác minh.
• Không restart, xóa dữ liệu, tắt plugin hoặc che failure một cách mù quáng.
• Đã cập nhật timeline, kết quả xác minh và quyết định đóng/escalate.

Nguồn Jenkins chính thứcCopy Anchor Link

• Jenkins: Managing Nodes
• Jenkins: Using agents
• Jenkins Pipeline Syntax: timeout và input
• Jenkins: Managing plugins
• Jenkins: System Administration
• Jenkins: Scaling
• Support Core plugin

Đọc tiếpCopy Anchor Link