Quan sát hệ thống giám sát

Hệ thống giám sát cũng phải được giám sát. Tài liệu này định nghĩa metric, log, trace và cảnh báo nội bộ của collector, cùng cách quan sát agent từ phía collector.

7 phút đọcCập nhật 02/10/2026access-hub-collector, docs/10-observability.md

1. Điểm cuối chuẩn (mọi vai trò, NFR-15)

Endpoint	Ý nghĩa
/healthz	Tiến trình còn sống (liveness), luôn nhanh, không kiểm tra phụ thuộc
/readyz	Sẵn sàng nhận tải (readiness): Redis, bus, TSDB, registry đã nạp. Trả 503 khi đang tắt êm để LB rút node
/metrics	Định dạng Prometheus, chỉ mở trong mạng nội bộ

2. Metric của collector

Tiền tố ahc_. Các nhóm chính:

Metric	Loại	Nhãn	Ý nghĩa
ahc_ingest_requests_total	counter	endpoint, code	Số request từ agent
ahc_ingest_duration_seconds	histogram	endpoint	Độ trễ xử lý, mục tiêu p99 dưới 250 ms
ahc_ingest_decoded_bytes	histogram		Kích thước sau giải nén
ahc_samples_accepted_total, ahc_samples_dropped_total	counter	reason	Mẫu nhận và bị bỏ (cửa sổ thời gian, nhãn, giới hạn series)
ahc_series_limit_dropped_total	counter		Series bị bỏ do vượt max_series
ahc_agents_online, ahc_agents_registered	gauge		Số agent đang online, đã đăng ký
ahc_registry_lookups_total	counter	result (mem, redis, hub, miss)	Tỷ lệ trúng cache
ahc_auth_failures_total	counter	reason	Token sai, thu hồi, hết hạn
ahc_bus_depth	gauge	shard	Độ sâu hàng đợi, tín hiệu quá tải sớm nhất
ahc_bus_publish_errors_total	counter
ahc_tsdb_write_duration_seconds	histogram		Độ trễ ghi remote-write
ahc_tsdb_write_errors_total	counter	class (temporary, permanent)
ahc_rules_eval_seconds	histogram		Thời gian đánh giá luật cho một lô (COL-8)
ahc_rules_samples_evaluated_total	counter		Mẫu được đánh giá với ít nhất một luật
ahc_alert_states	gauge	phase	Số cặp luật-máy-series theo pha (pending, firing, no_data)
ahc_alert_transitions_total	counter	to	Chuyển trạng thái: opened, resolved, reminder, no_data
ahc_rules_loaded, ahc_rules_invalid	gauge		Luật đã biên dịch đang chạy, luật bị từ chối ở lần đồng bộ gần nhất
ahc_rules_rejected_total	counter	reason	Luật không qua kiểm tra (unknown_metric, operator, matcher, label, scope, recover, ...), đếm một lần cho mỗi id@version
ahc_rules_sync_total	counter	result (ok, error)	Lần kéo luật từ Access Hub
ahc_rules_last_sync_timestamp_seconds, ahc_rules_since	gauge		Lần đồng bộ thành công gần nhất và con trỏ since
ahc_rules_snapshot_total	counter	kind (rules, state), result	Ghi snapshot luật và trạng thái
ahc_rules_events_retry	gauge		Sự kiện cảnh báo chưa vào được outbox, chờ thử lại
ahc_events_emitted_total	counter	type	Gồm alert.flapping, group_down, group_update, group_resolved (COL-9)
ahc_events_suppressed_total	counter	reason	Sự kiện phát với suppressed=true (COL-9)
ahc_alert_flaps_total	counter	to	Vào và ra flapping: entered, exited (COL-9)
ahc_alert_flap_events_dropped_total	counter		alert.opened và alert.resolved bị giữ lại khi đang flapping (COL-9)
ahc_alerts_flapping	gauge		Số cặp luật-máy-series đang flapping (COL-9)
ahc_groups_open	gauge		Nhóm group_down đang mở (COL-9)
ahc_silences_active	gauge		Silence đang có hiệu lực ngay lúc này (COL-9)
ahc_silences_sync_total	counter	result	Lần kéo GET /silences (COL-9)
ahc_silences_last_sync_timestamp_seconds	gauge		Lần kéo silence thành công gần nhất (COL-9)
ahc_silences_since	gauge		Con trỏ sync_version silence hiện tại (COL-9)
ahc_checks_sync_total	counter	result	Lần kéo GET /checks (COL-20)
ahc_checks_last_sync_timestamp_seconds	gauge		Lần kéo check thành công gần nhất (COL-20)
ahc_checks_since	gauge		Con trỏ sync_version check hiện tại (COL-20)
ahc_checks_loaded	gauge		Check trung tâm hợp lệ và đang bật (COL-20)
ahc_checks_invalid	gauge		Check bị bỏ vì sai ở lần kéo gần nhất (COL-20)
ahc_checks_truncated_servers	gauge		Máy bị cắt về 50 check ở lần kéo gần nhất (COL-20)
ahc_outbox_depth, ahc_outbox_oldest_age_seconds	gauge		Độ sâu và tuổi sự kiện cũ nhất chờ gửi
ahc_outbox_dead_letter_total	counter
ahc_accesshub_requests_total, ahc_accesshub_duration_seconds	counter, histogram	endpoint, code	Gọi sang Access Hub
ahc_shard_owned	gauge		Số shard worker đang sở hữu
ahc_clock_skew_seconds	gauge		Độ lệch đồng hồ với Access Hub
ahc_agent_versions	gauge	version	Phân bố phiên bản agent
ahc_active_series_total	gauge		Tổng series đang hoạt động (ước lượng)

Chỉ số về agent (từ AgentStats trong mỗi lô): số mẫu bị bỏ do đệm đầy, độ dài hàng đợi đĩa, số lần thử lại, thời gian thu thập. Được ghi vào TSDB dưới dạng metric agent_* để hiển thị trên tab sức khỏe và để quản trị viên tự chẩn đoán agent.

3. Log

• JSON một dòng, các trường cố định: ts, level, msg, request_id, role, agent_id, company_id, server_id, endpoint, code, duration_ms.
• request_id lấy từ X-Request-Id của agent (hoặc sinh mới), xuất hiện ở log collector, log Access Hub khi gọi chuyển tiếp và có thể tra chéo.
• Mức mặc định info. Ở info, request thành công không log từng dòng ở ingest (quá nhiều ở 300 req/s), chỉ log lỗi và mẫu lấy tỷ lệ (1%). Chế độ debug cho từng agent có thể bật tạm qua API admin (log_level theo agent) trong thời gian giới hạn.
• Không bao giờ log token, License, header Authorization, nội dung body đầy đủ.
• Tràn log: giới hạn tốc độ log theo khóa (cùng lỗi lặp lại được gộp và kèm bộ đếm).

4. Trace

OpenTelemetry (OTLP) tùy chọn, tắt mặc định. Bật khi cần chẩn đoán độ trễ: span quanh ingest -> registry -> bus -> tsdb write, và quanh cuộc gọi sang Access Hub. Lấy mẫu theo tỷ lệ cấu hình.

5. Cảnh báo nội bộ (mẫu luật cho vận hành)

Đóng gói thành bộ luật Prometheus/vmalert deploy/alerts/collector.rules.yaml.

Cảnh báo	Điều kiện gợi ý	Mức
IngestDown	Không node ingest nào sẵn sàng 2 phút	critical
IngestLatencyHigh	p99 ahc_ingest_duration_seconds trên 250 ms trong 10 phút	warning
BusDepthGrowing	ahc_bus_depth tăng liên tục 5 phút	warning
TsdbWriteErrors	Tỷ lệ lỗi ghi trên 1% trong 5 phút	critical
OutboxBacklog	ahc_outbox_oldest_age_seconds trên 300	warning; trên 3.600 thì critical
DeadLetter	ahc_outbox_dead_letter_total tăng	critical
RegistryMissSpike	Tỷ lệ miss vượt 5%	warning
AuthFailureSpike	ahc_auth_failures_total tăng đột biến	warning (có thể là tấn công)
SeriesSpike	ahc_active_series_total tăng hơn 30% trong 1 giờ	warning
ClockSkew	Lệch trên 5 giây	warning
AgentsOfflineRatio	Tỷ lệ agent offline vượt 20%	critical
CertExpiry	Chứng chỉ TLS của endpoint agent còn dưới 14 ngày	warning

Nguyên tắc chống vòng lặp: cảnh báo về chính hệ thống giám sát không được phụ thuộc duy nhất vào hệ thống đó. Cần một kênh độc lập (ví dụ một kiểm tra bên ngoài đơn giản hoặc vmalert riêng gửi thẳng thông báo) để biết khi cả collector sập.

6. Bảng điều khiển

Cung cấp sẵn dashboard Grafana JSON trong deploy/grafana/: Tổng quan ingest, Sức khỏe worker và bus, TSDB, Outbox và Access Hub, Đội agent (phiên bản, tỷ lệ online, top agent bị bỏ mẫu).

7. Trang trạng thái trong Access Hub

Trang quản trị collector của Access Hub (HUB-15, và bản rút gọn ở GĐ 1) hiển thị từ heartbeat và GET /internal/v1/status: phiên bản, vai trò, số agent, tốc độ ingest, độ sâu outbox, độ lệch đồng hồ, thời gian heartbeat gần nhất. Cảnh báo cho quản trị viên khi heartbeat mất.