Chat Slack 3 giờ sáng: “Kibana chết”. Bạn mở browser, thấy spinner xoay vô tận hoặc trang trắng. Câu hỏi đầu tiên: chết ở layer nào? Browser? Reverse proxy? Kibana server? ES cluster? Disk?

Bài này là một checklist debug có thứ tự, đi từ outermost (browser của user) tới innermost (ES shard state). Mỗi layer có 2-3 thứ cần check, có command verify, có quick fix nếu là lỗi quen thuộc. Khi debug 3 giờ sáng, đừng đoán: chạy checklist.

Mục tiêu bài:

  • Quy trình 7 bước debug Kibana không load
  • Symptom mapping cho mỗi layer
  • Command verify nhanh cho từng tầng
  • Quick fix cho lỗi top 10 hay gặp
  • Khi nào cần rollback vs khi nào fix forward

Phần 1: Mental model

Stack thông thường:

[User Browser]
     |
     v
[CDN / WAF]   (optional)
     |
     v
[Reverse Proxy: Nginx / Traefik / NPM]
     |
     v
[Kibana Server: Node.js, port 5601]
     |
     v
[Elasticsearch: port 9200]
     |
     v
[Disk: data, logs, snapshot]

Lỗi có thể xảy ra ở mọi layer. Triệu chứng “Kibana không load” giấu rất nhiều root cause khác nhau. Quy tắc vàng: debug từ ngoài vào trong, không skip layer.

LayerSymptom điển hình
BrowserTrang trắng, console error, JS bundle fail
CDN/WAF403 / 503, cache stale, captcha
Proxy502 Bad Gateway, 504 Timeout
Kibana”Kibana server is not ready”, redirect loop
ES”Service Unavailable”, red cluster status
DiskOOM, write fail, log rotate fail

Phần 2: Bước 1, Browser

Reproduce + isolate

  • Mở incognito (không cache, không extension)
  • Mở một browser khác (Firefox nếu thường dùng Chrome) để loại trừ extension hỏng
  • Mở từ mạng khác (4G mobile hotspot) để loại trừ vấn đề VPN/proxy

Nếu incognito + browser khác + mobile network đều fail = chắc chắn server-side issue, không phải browser. Nếu chỉ fail trên browser của bạn = clean cache, kiểm tra adblocker.

Mở DevTools

Tab Console:

  • Tìm error đỏ. Thường có 2 nhóm:
    • Failed to load resource: 502/504/timeout -> proxy hoặc Kibana down
    • Uncaught SyntaxError / chunk load failed -> static asset bị cache cũ, hard reload
    • Mixed Content blocked -> HTTPS frontend gọi HTTP backend, proxy config sai
    • CORS policy -> sai allowed origin, hoặc XSRF header missing

Tab Network:

  • Filter Doc, request đầu tiên / hoặc /app/home. Status code nói tất cả:

    • 200: server OK, lỗi ở client. Check Console
    • 301/302 loop: redirect không ngừng, sai server.basePath hoặc proxy header
    • 403: Forbidden, có thể auth method sai hoặc WAF chặn
    • 502: upstream (Kibana) không reach từ proxy
    • 504: Kibana có nhận request nhưng quá lâu không trả

  • Filter Fetch/XHR, xem /api/status, /api/core/capabilities. Nếu cái này fail = Kibana không sẵn sàng.

Phần 3: Bước 2, Proxy

Đa số production có Nginx / Traefik / Cloudflare đứng trước Kibana. Layer này thường là nguyên nhân.

Check log

Nginx:

tail -200 /var/log/nginx/access.log | grep " 5"
tail -200 /var/log/nginx/error.log

Tìm pattern:

upstream timed out (110: Connection timed out) while reading response header
connect() failed (111: Connection refused) while connecting to upstream
upstream sent too big header while reading response header

Connection refused = Kibana không listen trên port mà proxy đang gọi. Verify:

ss -tlnp | grep 5601
curl -sI http://localhost:5601

Timed out = Kibana đang slow hoặc treo. Tăng proxy_read_timeout lên 120s tạm, song song debug Kibana.

too big header = response cookie quá lớn, thường sau SSO redirect. Tăng proxy_buffer_size và proxy_busy_buffers_size.

Check config

Bốn config Nginx quan trọng cho Kibana:

location / {
  proxy_pass http://kibana_upstream:5601;
  proxy_http_version 1.1;
  proxy_set_header Host $host;
  proxy_set_header X-Real-IP $remote_addr;
  proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
  proxy_set_header X-Forwarded-Proto $scheme;
  proxy_buffering off;
  proxy_read_timeout 90s;

  # WebSocket cho server-sent events
  proxy_set_header Upgrade $http_upgrade;
  proxy_set_header Connection "upgrade";
}

Thiếu Upgrade + Connection header = WebSocket fail, Kibana sẽ load chậm hoặc treo ở splash screen.

Cloudflare specific

Nếu dùng Cloudflare:

  • Always Use HTTPS ON, nhưng origin Kibana là HTTP -> fix bằng Origin Rules hoặc đổi origin sang HTTPS
  • Page Rules cache *.js -> hard refresh fail. Disable cache cho path Kibana
  • WAF rule chặn POST với XSRF header -> add exception

Phần 4: Bước 3, Kibana server

Status endpoint

Test trực tiếp Kibana, bypass proxy:

curl -sS http://localhost:5601/api/status | jq

Response chuẩn:

{
  "name": "kibana-node-1",
  "uuid": "...",
  "version": {"number": "8.13.0", "build_hash": "..."},
  "status": {
    "overall": {"level": "available", "summary": "All services are available"},
    "core": { "...": "..." },
    "plugins": { "...": "..." }
  }
}

Nếu overall.level là degraded hoặc unavailable, status sẽ list plugin nào đang fail. Đây là vàng debug.

Log Kibana

journalctl -u kibana -n 200 --no-pager
# Hoặc Docker:
docker logs kibana --tail 200
# Hoặc file:
tail -200 /var/log/kibana/kibana.log

Top 5 error message hay gặp:

Log messageRoot causeFix
Unable to retrieve version information from Elasticsearch nodesKhông kết nối được ESCheck ES URL + auth
License is not availableLicense expired hoặc disconnect ESRenew license / verify ES
Optimize failed (lần đầu start)Disk full hoặc CPU thấpFree disk, tăng heap
EADDRINUSE: address already in use :::5601Có process khác chiếm portlsof -i :5601, kill
Health check failed cho pluginPlugin lỗi (vd: alerting)Disable plugin hoặc reinstall

Memory + CPU

ps aux | grep -E "node|kibana" | head -5
top -bn1 | head -20

Kibana node process thường 1.5-2 GB RAM. Nếu thấy 4+ GB = memory leak hoặc heap quá lớn. Restart và monitor.

CPU 100% kéo dài = thường do plugin Reporting (Chromium) hoặc Alert rule overload. Disable plugin nghi vấn để isolate.

Phần 5: Bước 4, Elasticsearch

Kibana phụ thuộc 100% vào ES. ES có vấn đề = Kibana down.

Cluster health

curl -sS -u elastic:password "http://es:9200/_cluster/health?pretty"
{
  "cluster_name": "...",
  "status": "yellow",
  "timed_out": false,
  "number_of_nodes": 3,
  "active_primary_shards": 234,
  "active_shards": 432,
  "unassigned_shards": 6
}
StatusÝ nghĩaHành động
greenOKKibana không xuống do ES
yellowPrimary OK, replica thiếuKibana vẫn chạy, có thể slow
redCó primary mấtKibana có thể không start được nếu .kibana index ảnh hưởng

Nếu red:

curl -sS "http://es:9200/_cluster/allocation/explain?pretty"

Trả lý do shard không assign được. Top reason: node disk vượt 95% (high watermark), node mới chưa join, allocation filter sai.

.kibana index health

Kibana lưu saved object trong .kibana_*. Nếu index này có vấn đề, Kibana không khởi động.

curl -sS "http://es:9200/_cat/indices/.kibana*?v"
curl -sS "http://es:9200/_cluster/health/.kibana*?level=indices&pretty"

Nếu .kibana ở status red, fix ưu tiên cao nhất. Nếu primary shard .kibana đã mất hẳn, phải restore từ snapshot.

Disk space

ES tự shutdown write khi vượt watermark. Default:

  • low: 85% (ngừng nhận shard mới)
  • high: 90% (move shard khỏi node)
  • flood_stage: 95% (chuyển index thành read-only)
curl -sS "http://es:9200/_cat/allocation?v"
shards disk.indices disk.used disk.avail disk.total disk.percent
   234        45gb     78gb       12gb       90gb         86

Nếu thấy disk.percent 90+: xử lý ngay (xoá log cũ, force merge, snapshot rồi delete index).

Khẩn cấp nhất là bỏ flag flood_stage read-only:

curl -sS -XPUT "http://es:9200/.kibana*/_settings" \
  -H 'Content-Type: application/json' \
  -d '{"index.blocks.read_only_allow_delete": null}'

(Sau khi đã clear disk, không trước.)

Phần 6: Bước 5, Auth và SSO

Kibana load trắng + chuyển hướng vô tận đến IdP = SSO config lỗi.

Triệu chứng + fix:

Triệu chứngCauseFix
Vòng lặp redirect loginCookie domain sai, hoặc xpack.security.session.idleTimeout quá ngắnTăng idleTimeout, set cookie domain đúng
Forbidden sau loginRole không có Kibana privilegeAdd role với kibana_user minimum
Invalid certificateTLS cert giữa Kibana ES self-signedAdd ca.crt vào elasticsearch.ssl.certificateAuthorities
SAML không trả vềclock skew giữa Kibana và IdPSync NTP, tăng clock_skew setting

Test bằng built-in user

Tạm thời disable SSO, login bằng user nội bộ elastic để kiểm tra ngoài SSO ra Kibana có chạy không. Nếu chạy = vấn đề là SSO config, không phải Kibana.

# Trong elasticsearch.yml
xpack.security.authc.realms.saml.saml1.enabled: false

Restart Kibana, login với elastic + password.

Phần 7: Bước 6, System resource

File descriptor

ES + Kibana cần FD cao, default Linux 1024 không đủ.

cat /proc/$(pidof java)/limits | grep "Max open files"
cat /proc/$(pidof node)/limits | grep "Max open files"

Nên là 65535 trở lên. Fix:

# /etc/security/limits.conf
elasticsearch soft nofile 65535
elasticsearch hard nofile 65535
kibana soft nofile 65535
kibana hard nofile 65535

Inode

Disk còn dung lượng nhưng vẫn No space left on device? Hết inode.

df -i

Inode hết = quá nhiều file nhỏ (thường là log Kibana không rotate). Fix: xoá log cũ hoặc setup logrotate.

Swap

ES không nên dùng swap. Verify:

sysctl vm.swappiness
# Nên là 1 hoặc 0

Set:

sudo sysctl -w vm.swappiness=1
echo 'vm.swappiness=1' | sudo tee -a /etc/sysctl.conf

Hoặc bật bootstrap.memory_lock: true trong elasticsearch.yml (cần raise ulimit memlock).

Phần 8: Bước 7, Network giữa nodes

Multi-node cluster có thể bị split-brain hoặc network partition.

# Từ Kibana node, ping ES
curl -sS --connect-timeout 5 http://es-master-1:9200
curl -sS --connect-timeout 5 http://es-master-2:9200
curl -sS --connect-timeout 5 http://es-master-3:9200

Nếu 2/3 master unreachable, ES không elect được master, Kibana không kết nối được.

Check security group / firewall:

nc -zv es-master-1 9200
nc -zv es-master-1 9300  # Transport port giữa ES nodes

Port 9300 phải mở giữa các ES node với nhau.

Phần 9: Story thực tế

Một lần dự án internal trước đây mình maintain bị Kibana down sáng thứ Hai. Triệu chứng: trang trắng, console báo Network Error cho /api/status.

Quy trình debug đã chạy:

  1. Browser: incognito + Firefox cùng fail = không phải client
  2. Proxy log: Nginx báo upstream timed out. Curl trực tiếp Kibana port: Connection refused. Vậy Kibana process chết.
  3. Kibana log: Cannot find module 'lodash'. Trời ơi.
  4. Root cause: Backup script đêm chạy rm -rf trong /var/lib/kibana/ thay vì /var/backups/kibana/ (path bug). Xoá luôn node_modules.
  5. Fix: reinstall Kibana từ apt, restore data từ snapshot ES, restart. Up trong 25 phút.
  6. Postmortem: backup script được sửa, thêm set -euo pipefail, thêm dry-run flag, test trong staging trước.

Bài học: log không nói dối. Đừng đoán, đọc log cho đến khi tìm thấy chuỗi đầu tiên không bình thường, từ đó lần ngược.

Cheatsheet

LayerQuick check
BrowserDevTools Console + Network. Incognito test
Proxytail /var/log/nginx/error.log
Kibana portcurl http://localhost:5601/api/status
Kibana logjournalctl -u kibana -n 200
ES healthcurl http://es:9200/_cluster/health?pretty
.kibana indexcurl http://es:9200/_cat/indices/.kibana*?v
Diskdf -h && df -i
Allocationcurl http://es:9200/_cluster/allocation/explain?pretty
FD limitcat /proc/$(pidof node)/limits
Networknc -zv es-host 9200

Lời kết

Kibana không load là một symptom, không phải root cause. Đi qua checklist 7 layer là cách duy nhất để locate vấn đề mà không lãng phí 2 giờ đoán mò. Save bài này, in ra, dán cạnh laptop runbook.

Bài tiếp theo trong series Kibana từ A đến Z chuyển từ “Kibana không lên” sang “Kibana lên nhưng query chậm”. Đi sâu vào ES profiler API, slow log, shard distribution và những thứ cần biết khi query 30 giây mới trả về kết quả, dù data chỉ vài GB.