Giao diện

Câu hỏi thường gặp (FAQ) — Telemetry Prometheus ​

Cài đặt ​

Bắt buộc phải cài Prometheus server không? ​

Có. Plugin này chỉ expose metrics — nó cần Prometheus server scrape dữ liệu định kỳ. Nếu không có Prometheus, metrics vẫn được tạo nhưng không ai thu thập.

Cách cài nhanh với Docker:

bash
docker run -d --name prometheus \
  -p 9090:9090 \
  -v ./prometheus.yml:/etc/prometheus/prometheus.yml \
  prom/prometheus

Plugin này có cần plugin-telemetry không? ​

Có. Plugin đăng ký Prometheus reader với app.telemetry.metric, hệ thống này được cung cấp bởi plugin-telemetry. Bật plugin-telemetry trước, sau đó bật plugin-telemetry-prometheus.

Nên dùng chế độ Internal hay Standalone? ​

Tiêu chíInternalStandalone
Cài đặtĐơn giản, không cần mở portCần mở thêm port
Bảo mậtDùng chung middleware, dễ thêm authCần bảo mật riêng
Hiệu suấtChia sẻ resources với ứng dụngTách biệt, không ảnh hưởng ứng dụng
Khuyến nghịĐa số trường hợpKhi cần tách biệt traffic

Cấu hình ​

Làm sao thay đổi port của standalone server? ​

Đặt biến môi trường:

bash
TELEMETRY_PROMETHEUS_PORT=8888

Sau đó cập nhật Prometheus scrape config trỏ đến port mới.

Metrics endpoint có cần authentication không? ​

Mặc định không — plugin đặt ACL là public. Nếu muốn yêu cầu auth:

  1. Xóa dòng this.app.acl.allow('prometheus', 'metrics', 'public') trong plugin tùy chỉnh
  2. Hoặc dùng reverse proxy (Nginx) thêm basic auth phía trước

Scrape interval nên đặt bao nhiêu? ​

Môi trườngInterval khuyến nghịLý do
Development5-10sXem kết quả nhanh khi debug
Staging15sCân bằng độ chính xác và tải
Production15-30sGiảm tải cho cả ứng dụng và Prometheus

Xử lý sự cố ​

Prometheus target hiển thị "DOWN"? ​

Kiểm tra theo thứ tự:

  1. Network: Server Prometheus có kết nối được đến Digiforce server không?
    bash
    # Từ máy Prometheus
curl http://digiforce-server:13000/api/prometheus:metrics
  2. Plugin đã bật: Vào Plugin Manager kiểm tra plugin-telemetry-prometheus đang active
  3. Firewall: Port 13000 (internal) hoặc 9464 (standalone) có mở không?
  4. URL đúng: Kiểm tra metrics_path trong scrape config khớp với chế độ đang dùng

Endpoint trả về lỗi # failed to export metrics? ​

Lỗi này xảy ra khi this.collect() thất bại trong InternalPrometheusExporter. Nguyên nhân có thể:

  • Metric reader chưa khởi tạo xong — đợi vài giây sau khi server khởi động
  • Có metric bị lỗi trong quá trình thu thập — kiểm tra log server để xem chi tiết errors

Metrics không cập nhật giá trị mới? ​

  • Counter metrics chỉ tăng — nếu không có request mới, giá trị giữ nguyên
  • Gauge metrics (CPU, memory) cập nhật theo chu kỳ exportIntervalMillis (mặc định 60s)
  • Kiểm tra Prometheus UI: Graph → nhập metric name → xem có dữ liệu mới không

Restart server thì metrics có bị reset không? ​

Có. Counter metrics sẽ reset về 0 khi restart. Prometheus xử lý tình huống này bằng cách:

  • Hàm rate() tự động phát hiện counter reset
  • Giá trị increase() vẫn tính đúng sau reset
  • Gauge metrics sẽ có giá trị mới ngay khi thu thập lại

Quá nhiều metrics gây chậm scrape? ​

Nếu endpoint /metrics trả về chậm (> 5s):

  • Giảm số lượng custom metrics không cần thiết
  • Tăng scrape_timeout trong Prometheus config
  • Cân nhắc chuyển sang standalone server để không ảnh hưởng ứng dụng
  • Kiểm tra xem có metric nào tạo quá nhiều label combinations không (cardinality explosion)