Chuyển tới nội dung chính

Giám sát và nhật ký

Tài liệu cho người theo dõi hệ thống: log của gateway, sự kiện đăng nhập, giới hạn tốc độ, audit trong backend, số đo cho Prometheus và màn hình giám sát. Mọi request vào stack đi qua gateway APISIX, nên log của gateway là bản ghi truy cập chính. Sự kiện đăng nhập nằm ở Keycloak. Cài đặt và các lệnh dxos ở Cài đặt và vận hành.

Log của gateway​

Mỗi request là một dòng JSON trên stdout của container apisix.

TrườngÝ nghĩa
timeThời điểm, ISO 8601
remote_addrĐịa chỉ client
host, method, uriTên miền, phương thức, đường dẫn (không có query string)
status, request_timeMã trả về, thời gian xử lý (giây)
upstream_addr, upstream_timeDịch vụ phía sau xử lý request và thời gian của nó
bytes_sentSố byte trả về
request_idMã của request, cũng nằm trong header X-Request-Id của response
cf_rayMã request do proxy phía trước gắn vào, trống khi vào trực tiếp
user_agentTrình duyệt hoặc ứng dụng gọi

Backend ghi request_id này vào log của nó (trong [...] sau mức log).

remote_addr là địa chỉ trong header CF-Connecting-IP khi một proxy phía trước đặt nó, và là IP của client trong mạng khi vào trực tiếp. Header chỉ được tin khi request đến từ mạng Docker (172.16.0.0/12) hoặc loopback. Ở máy có dải Docker khác thì sửa real_ip_from trong apisix/config.yaml.

Log của container còn có dòng không phải JSON (cảnh báo khi khởi động, error log của nginx), nên jq đọc từng dòng và bỏ qua dòng lỗi bằng fromjson?. Kiểm tra sức khỏe của container gửi một request từ 127.0.0.1 (đường dẫn /, mã 400) mỗi 10 giây. Các ví dụ dưới loại dòng này. Ví dụ (cần jq, cài bằng apt install jq nếu máy chủ chưa có):

cd deploy
docker compose logs apisix --since 1h --no-log-prefix | jq -cR 'fromjson? | select(.status >= 400 and .remote_addr != "127.0.0.1")'
docker compose logs apisix --no-log-prefix | jq -cR --arg id "<mã từ header X-Request-Id>" 'fromjson? | select(.request_id == $id)'

Giữ log​

Docker xoay vòng log theo dung lượng: gateway 10 tệp 100 MB, các dịch vụ khác 5 tệp 20 MB. Log mất khi container bị tạo lại. Truy vết lâu dài cần dùng sự kiện của Keycloak (90 ngày) và dữ liệu nghiệp vụ trong database.

Sự kiện đăng nhập của Keycloak​

Admin Console (mở theo Cài đặt và vận hành) → realm dxos → Events:

  • User events: đăng nhập, đăng nhập sai, đăng xuất, đổi hoặc đặt lại mật khẩu, tài khoản bị khóa; kèm IP và client; giữ 90 ngày.
  • Admin events: thao tác quản trị trong Keycloak, kèm nội dung thay đổi.

Sau 5 lần đăng nhập sai, tài khoản bị khóa tạm 1 phút, mỗi lần sai tiếp theo tăng thêm 1 phút, tối đa 15 phút. Hai lần sai cách nhau dưới 1 giây cũng khóa 1 phút (kiểm tra đăng nhập nhanh của Keycloak), nên script đăng nhập thử cần chờ giữa các lần. Một địa chỉ đăng nhập sai từ 10 lần trong 10 phút thì monitor báo vào kênh quản trị khi có webhook (ngưỡng ở monitor.alert.login-failed-*). Sự kiện đăng nhập sai của Keycloak không ghi tên tài khoản, nên chưa có cảnh báo theo tài khoản. Gỡ khóa sớm: Users → chọn người dùng → tắt công tắc Temporarily locked.

IP trong sự kiện theo cùng quy tắc với remote_addr ở phần log của gateway.

Giới hạn tốc độ​

Gateway đếm theo IP thật của client (xem phần log), vượt ngưỡng thì trả 429 kèm X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset. Backend đếm thêm theo người dùng (sub của token), vượt ngưỡng thì trả 429 kèm Retry-After. Request có token sai nhận 401 mà không bị đếm.

Nơi đếmĐường dẫnNgưỡng mỗi phút
Gateway, mỗi IP/realms/<realm>/login-actions/* và /realms/<realm>/protocol/openid-connect/token (chung một bộ đếm)120
Gateway, mỗi IP/api/* (request có token hợp lệ)600
Gateway, mỗi IP/api/v1/system/status (công khai)Xem deploy/apisix/common.yaml
Backend, mỗi người dùngMọi /api/**300

Bộ đếm của backend nằm trong bộ nhớ nên về 0 khi backend khởi động lại. RATE_LIMIT_ENABLED=false trong deploy/.env tắt phần của backend, dùng khi thử tải. Đổi ngưỡng của gateway ở count của limit-count trong deploy/apisix/common.yaml rồi chạy docker compose up -d --force-recreate apisix-config && docker compose restart apisix để gateway nạp lại. Nhiều người dùng chung một IP (mạng di động) cùng dùng bộ đếm, nên thấy 429 trong thao tác thường ngày thì tăng ngưỡng. Mỗi lần đăng nhập tốn hai request (form và token), nên script đăng nhập hơn 60 tài khoản trong một phút từ một máy sẽ chạm giới hạn; chờ một phút hoặc chạy cách nhau. Giới hạn này chỉ chặn lượng request lớn từ một địa chỉ; đoán mật khẩu từng tài khoản do khóa tạm của Keycloak xử lý.

Audit trong backend​

Bảng audit_log (chỉ thêm, database từ chối sửa hoặc xóa) ghi lần truy cập bị từ chối và thao tác quản trị. Bảng không ghi mật khẩu, token hay nội dung request. Mỗi bản ghi có người thực hiện (sub, tên, vai, client của token), ip, request_id, method và đường dẫn. request_id là giá trị X-Request-Id của gateway, nên nối được với dòng log gateway (request_id) và log backend (trong [...] sau mức log).

Hành độngKhi nào
ACCESS_DENIEDRequest nhận 403
AUTH_FAILEDBackend từ chối token đã tới nó (token không tới được backend nếu gateway đã từ chối)
SERVER_ERRORBackend trả 500, 502 hoặc 503; outcome là FAILED, metadata có mã trả về và tên lớp ngoại lệ (không có thông điệp lỗi)
ADMIN_ACTION_FAILEDADMIN thực hiện thao tác thay đổi (POST, PUT, PATCH, DELETE) bị từ chối vì lý do nghiệp vụ (409, 422); outcome là FAILED
MODEL_* (MODEL_APPLIED, MODEL_ROLLED_BACK, MODEL_RESUMED, MODEL_ABANDONED)Áp dụng, quay về, tiếp tục hoặc hủy bỏ mô hình thành công, kể cả lần bootstrap (người thực hiện Bootstrap); target_type là MODEL, target_id là tên mô hình, metadata có version, status, runId, actorName; lần unchanged hay bị từ chối không ghi
USER_* (tạo, khóa, mở, đặt lại mật khẩu, gán và gỡ vai, thêm và bỏ đơn vị)ADMIN đổi tài khoản ở tab Người dùng; target_id là mã người dùng, metadata có tên đăng nhập và mô hình, vai hoặc đơn vị; không có mật khẩu

Thay đổi tài khoản làm thẳng ở Keycloak Admin Console không vào audit_log; tra ở sự kiện quản trị của Keycloak (Events, Admin events; giữ 90 ngày), có tài khoản người thực hiện.

Thay đổi trên từng bản ghi nằm ở engine.record_event, lịch sử áp dụng mô hình ở engine.apply_run và engine.apply_step. Đăng nhập và đổi mật khẩu nằm ở sự kiện của Keycloak. Mỗi địa chỉ client có tối đa 20 bản ghi mỗi loại ACCESS_DENIED, AUTH_FAILED, SERVER_ERROR hoặc ADMIN_ACTION_FAILED mỗi phút (audit.denied.max-per-minute trong application.yaml). Số bản ghi bị bỏ qua nằm trong metadata.suppressed của bản ghi đầu phút kế tiếp.

ADMIN tra cứu qua API (GET /api/v1/audit-logs), lọc theo actor (user id hoặc username), action, outcome, from, to:

GET /api/v1/audit-logs?outcome=DENIED&from=2026-10-23T00:00:00Z&size=50

Hoặc truy vấn trực tiếp:

cd deploy
docker compose exec postgres sh -c 'psql -U "$POSTGRES_USER" -d "${POSTGRES_DB:-dxos}" -c "select occurred_at, action, outcome, actor_name, ip, path from audit_log order by id desc limit 20"'

Bản ghi được giữ không giới hạn thời gian và trigger chặn xóa. Chạy lâu thì theo dõi dung lượng bảng.

Số đo cho Prometheus​

Dịch vụ lõi xuất số đo vận hành theo định dạng Prometheus ở GET /actuator/prometheus của cổng 8081 trong mạng Docker, để Prometheus, Grafana Agent hoặc công cụ tương tự đọc. Công cụ giám sát bên ngoài là tùy chọn: stack không kèm Prometheus hay Grafana.

Truy cập:

  • Cổng API không chuyển đường dẫn /actuator ra ngoài, nên endpoint chỉ đọc được từ trong mạng Docker của stack.
  • Endpoint đòi HTTP Basic với người dùng metrics và mật khẩu METRICS_PASSWORD trong deploy/.env; make_env.sh sinh mật khẩu ngẫu nhiên, và để trống thì endpoint đóng với mọi người.
  • Chỉ endpoint này và /actuator/health được mở; các endpoint khác của Actuator không mở.

Số đo do dịch vụ lõi tính từ cơ sở dữ liệu mỗi 30 giây (đổi bằng METRICS_REFRESH_MS, tính bằng mili giây), nên một lần đọc không truy vấn dữ liệu. Nhãn chỉ là tên mô hình, tên thực thể, trạng thái và kết quả áp dụng do các tệp mô hình khai báo, không bao giờ là hồ sơ, người dùng hay chữ tự do, nên số chuỗi theo số mô hình chứ không theo số hồ sơ.

Số đoKiểuNhãnÝ nghĩa
dxos_recordsgaugemodel, entity, statusSố hồ sơ của thực thể có quy trình theo trạng thái; trạng thái chưa có hồ sơ vẫn hiện số 0
dxos_records_overduegaugemodel, entitySố hồ sơ mà người xử lý đã quá hạn
dxos_outbox_pendinggaugekhôngSố sự kiện gửi ra ngoài chưa chuyển được
dxos_outbox_retryinggaugekhôngSố sự kiện chưa chuyển được và đã thử lỗi ít nhất một lần
dxos_outbox_oldest_age_secondsgaugekhôngTuổi của sự kiện chưa chuyển cũ nhất, bằng giây; 0 khi hàng đợi trống
dxos_model_applies_totalcounterresult (done, failed)Số lần áp dụng tệp mô hình theo kết quả, tính từ lịch sử áp dụng
dxos_modelsgaugekhôngSố mô hình đang chạy

Dịch vụ cũng xuất các số đo chuẩn của JVM, cơ sở dữ liệu và HTTP (jvm_*, hikaricp_*, http_server_requests_*); nhãn uri của chúng là mẫu đường dẫn như /api/v1/data/{model}/{entity}, không chứa mã hồ sơ.

Thử đọc từ máy chủ của stack:

cd deploy
PASSWORD=$(grep '^METRICS_PASSWORD=' .env | cut -d= -f2)
docker compose exec backend wget -qO- --header "Authorization: Basic $(printf 'metrics:%s' "$PASSWORD" | base64 -w0)" http://localhost:8081/actuator/prometheus | grep '^dxos_'

Cấu hình Prometheus chạy trong cùng mạng Docker của stack (container tham gia mạng <tên-dự-án>_default, xem bằng docker network ls):

scrape_configs:
- job_name: dxos
metrics_path: /actuator/prometheus
scrape_interval: 30s
basic_auth:
username: metrics
password_file: /etc/prometheus/dxos-metrics-password
static_configs:
- targets: ["backend:8081"]

Tệp dxos-metrics-password chứa mật khẩu trên một dòng, không có ký tự xuống dòng ở cuối.

Truy vấn Grafana tham khảo, mỗi dòng là một panel:

PanelTruy vấn
Hồ sơ theo trạng tháisum by (model, entity, status) (dxos_records)
Hồ sơ quá hạnsum by (model, entity) (dxos_records_overdue)
Tuổi hàng đợi sự kiệndxos_outbox_oldest_age_seconds
Sự kiện chưa chuyển đượcdxos_outbox_pending và dxos_outbox_retrying
Lần áp dụng thất bại trong 24 giờincrease(dxos_model_applies_total{result="failed"}[24h])

Quy tắc cảnh báo gợi ý:

groups:
- name: dxos
rules:
- alert: DxosRecordsOverdue
expr: sum by (model, entity) (dxos_records_overdue) > 0
for: 15m
- alert: DxosEventQueueStuck
expr: dxos_outbox_oldest_age_seconds > 600
for: 5m
- alert: DxosApplyFailed
expr: increase(dxos_model_applies_total{result="failed"}[1h]) > 0

Màn hình giám sát​

Dịch vụ monitor gom log gateway, audit_log, sự kiện đăng nhập của Keycloak và trạng thái dịch vụ vào một màn hình /monitor/ cho ADMIN, kèm cảnh báo qua webhook khi có cấu hình. Cách đọc, truy vết một sự cố, dữ liệu, cảnh báo và cấu hình ở backend/dx-monitor/README.md.