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

Yêu cầu hệ thống

Thành phần	Yêu cầu
Digiforce Server	Đang chạy và hoạt động bình thường
OpenTelemetry Collector	(Tùy chọn) Jaeger, Grafana Tempo, hoặc OTLP Collector
Network	Server phải kết nối được đến collector endpoint

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

Vào Settings → Plugin Manager, tìm plugin-telemetry và bật lên. Sau khi kích hoạt, plugin sẽ đăng ký metric reader với hệ thống telemetry của ứng dụng.

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

bash

yarn pm enable plugin-telemetry

Bước 2: Cấu hình biến môi trường

Thêm các biến sau vào file .env của ứng dụng:

bash

# Bật telemetry
TELEMETRY_ENABLED=true

# Tên service hiển thị trong traces và metrics
TELEMETRY_SERVICE_NAME=digiforce-app

# Loại processor cho traces: batch (khuyên dùng) hoặc simple
TELEMETRY_TRACE_PROCESSOR=batch

# URL của OTLP Collector để gửi metrics qua HTTP
TELEMETRY_HTTP_URL=http://localhost:4318/v1/metrics

# Ngưỡng ghi nhận thời gian request (ms) — request nhanh hơn sẽ bị bỏ qua
TELEMETRY_HTTP_RECORD_THRESHOLD=0

Mẹo

Đặt TELEMETRY_HTTP_RECORD_THRESHOLD lớn hơn 0 (ví dụ 500) để chỉ ghi nhận những request chậm, giảm lượng dữ liệu metrics trong môi trường production.

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

Plugin sử dụng OTLPMetricExporter với temporality preference là DELTA. Bảng dưới liệt kê các cách cấu hình exporter phổ biến:

Exporter	Biến môi trường	Mô tả
Console	`TELEMETRY_TRACE_EXPORTER=console`	In ra console — phù hợp khi phát triển
OTLP HTTP	`TELEMETRY_HTTP_URL=http://collector:4318/v1/metrics`	Gửi đến OpenTelemetry Collector qua HTTP
OTLP gRPC	`OTEL_EXPORTER_OTLP_ENDPOINT=http://collector:4317`	Gửi đến Collector qua gRPC

Bước 4: Khởi động và kiểm tra

Khởi động lại server sau khi cấu hình:

bash

yarn start

Kiểm tra log server có dòng xác nhận telemetry đã khởi tạo:

[info] Telemetry initialized: service=digiforce-app

Dữ liệu thu thập

Plugin tự động thu thập các loại dữ liệu sau khi chạy trên instance main:

Loại	Metric name	Mô tả
System	`process_cpu_percent`	Phần trăm CPU process đang dùng
System	`process_memory_mb`	Bộ nhớ process (MB)
System	`process_heap_mb`	Heap memory đã dùng (MB)
HTTP	`http_request_count`	Tổng số HTTP request (có label: app, method, path, status_code)
HTTP	`http_request_cost`	Histogram thời gian xử lý request (ms)
HTTP	`http_request_active`	Số request đang xử lý đồng thời

Tích hợp với observability stack

Jaeger — Distributed tracing

yaml

# docker-compose.yml
services:
  jaeger:
    image: jaegertracing/all-in-one:latest
    ports:
      - "16686:16686"   # Jaeger UI
      - "4318:4318"     # OTLP HTTP

Prometheus + Grafana — Dashboard metrics

Cấu hình Prometheus scrape target trỏ đến OTLP Collector, sau đó dùng Grafana để tạo dashboard hiển thị http_request_count, http_request_cost, và process_cpu_percent.

OpenTelemetry Collector

yaml

# otel-collector-config.yaml
receivers:
  otlp:
    protocols:
      http:
        endpoint: 0.0.0.0:4318

exporters:
  prometheus:
    endpoint: "0.0.0.0:8889"
  jaeger:
    endpoint: "jaeger:14250"

service:
  pipelines:
    metrics:
      receivers: [otlp]
      exporters: [prometheus]
    traces:
      receivers: [otlp]
      exporters: [jaeger]

Lưu ý quan trọng

Telemetry tăng nhẹ overhead — dùng TELEMETRY_HTTP_RECORD_THRESHOLD để lọc bớt request nhanh
Metric reader mặc định export mỗi 60 giây (exportIntervalMillis: 60000)
Plugin chỉ đăng ký system metrics và gateway metrics trên instance có tên main — các worker khác sẽ bỏ qua
Batch processor giảm tải cho exporter bằng cách gom nhiều metric lại gửi một lần