Hướng dẫn cài đặt — Telemetry Prometheus

Yêu cầu

Thành phần	Yêu cầu
Digiforce Server	Đang chạy với `plugin-telemetry` đã kích hoạt
Prometheus Server	Đang hoạt động và có thể kết nối từ Digiforce (hoặc ngược lại)
Grafana	(Tùy chọn) Để tạo dashboard hiển thị metrics

Bước 1: Kích hoạt plugin

Vào Settings → Plugin Manager, tìm plugin-telemetry-prometheus và bật. Plugin này yêu cầu plugin-telemetry đã được bật trước.

Hoặc kích hoạt qua dòng lệnh:

bash

yarn pm enable plugin-telemetry-prometheus

Bước 2: Chọn chế độ hoạt động

Chế độ Internal (khuyên dùng cho đa số trường hợp)

Không cần cấu hình thêm. Metrics sẽ được expose tại:

GET http://your-server:13000/api/prometheus:metrics

Plugin tạo resource prometheus với action metrics, ACL cho phép truy cập công khai (public).

Chế độ Standalone Server

Thêm biến môi trường vào .env:

bash

# Bật standalone Prometheus server
TELEMETRY_PROMETHEUS_SERVER=on

# Port cho Prometheus server (mặc định: 9464)
TELEMETRY_PROMETHEUS_PORT=9464

Metrics sẽ được expose tại:

GET http://your-server:9464/metrics

Bước 3: Cấu hình Prometheus scrape

Thêm target vào file cấu hình Prometheus:

Với chế độ Internal

yaml

# prometheus.yml
scrape_configs:
  - job_name: 'digiforce'
    scrape_interval: 15s
    metrics_path: '/api/prometheus:metrics'
    static_configs:
      - targets: ['digiforce-server:13000']
        labels:
          environment: 'production'

Với chế độ Standalone Server

yaml

# prometheus.yml
scrape_configs:
  - job_name: 'digiforce'
    scrape_interval: 15s
    metrics_path: '/metrics'
    static_configs:
      - targets: ['digiforce-server:9464']
        labels:
          environment: 'production'

Bước 4: Kiểm tra

Kiểm tra endpoint trả về metrics

bash

# Chế độ Internal
curl http://localhost:13000/api/prometheus:metrics

# Chế độ Standalone
curl http://localhost:9464/metrics

Kết quả mong đợi — dạng text Prometheus:

# HELP process_cpu_percent Process CPU usage percentage
# TYPE process_cpu_percent gauge
process_cpu_percent 12.5
# HELP http_request_count Total number of HTTP requests
# TYPE http_request_count counter
http_request_count{app="main",method="GET",path="/api/users:list",status_code="200"} 42

Kiểm tra Prometheus đã scrape thành công

Mở Prometheus UI (http://prometheus:9090), vào Status → Targets. Target digiforce phải hiển thị trạng thái UP.

Bước 5: Tạo Grafana dashboard (tùy chọn)

Sau khi Prometheus thu thập dữ liệu, kết nối Grafana với Prometheus và tạo dashboard:

Một số PromQL hữu ích:

Panel	PromQL
Request rate (req/s)	`rate(http_request_count[5m])`
Thời gian xử lý trung bình	`rate(http_request_cost_sum[5m]) / rate(http_request_cost_count[5m])`
CPU usage	`process_cpu_percent`
Memory usage	`process_memory_mb`
Active requests	`http_request_active`

Chi tiết kỹ thuật

Cách plugin đăng ký với telemetry

InternalPrometheusExporter

Lớp này kế thừa PrometheusExporter từ OpenTelemetry nhưng:

Đặt preventServerStart: true để không chạy server riêng
Đăng ký resource prometheus với action metrics trên server Digiforce
Khi nhận request, gọi this.collect() để thu thập metrics rồi serialize bằng PrometheusSerializer

Lưu ý quan trọng

Endpoint metrics là public — bất kỳ ai biết URL đều xem được. Trong production, nên giới hạn bằng firewall hoặc reverse proxy
Nếu dùng cả plugin-telemetry và plugin-telemetry-prometheus, metrics từ cả hai sẽ được gộp chung
Standalone server phù hợp khi muốn tách biệt traffic monitoring và traffic ứng dụng
Restart server không làm mất cấu hình nhưng sẽ reset các counter metrics về 0