Cấu hình chi tiết — Telemetry

Biến môi trường

Core

Biến	Mặc định	Mô tả
TELEMETRY_ENABLED	false	Bật/tắt toàn bộ hệ thống telemetry
TELEMETRY_SERVICE_NAME	digiforce	Tên service hiển thị trong traces và metrics
TELEMETRY_SERVICE_VERSION	(tự động)	Phiên bản service — nếu không đặt sẽ lấy từ package.json

Traces

Biến	Mặc định	Mô tả
TELEMETRY_TRACE_PROCESSOR	batch	Loại processor: batch (gom rồi gửi) hoặc simple (gửi ngay)
TELEMETRY_TRACE_EXPORTER	console	Loại exporter: console (in ra log), otlp (gửi đến collector)
TELEMETRY_TRACE_SAMPLE_RATE	1.0	Tỉ lệ sampling — 1.0 là thu thập tất cả, 0.1 là 10%

Metrics

Biến	Mặc định	Mô tả
TELEMETRY_HTTP_URL	—	URL endpoint của OTLP Collector để gửi metrics (bắt buộc nếu dùng OTLP)
TELEMETRY_HTTP_RECORD_THRESHOLD	0	Ngưỡng tối thiểu (ms) để ghi nhận histogram duration — giúp lọc request nhanh
TELEMETRY_METRIC_READER	periodic	Loại metric reader: periodic hoặc prometheus
TELEMETRY_METRIC_INTERVAL	60000	Khoảng thời gian export metrics (ms) — mặc định 1 phút

OTLP Exporter

Biến	Mặc định	Mô tả
OTEL_EXPORTER_OTLP_ENDPOINT	http://localhost:4318	Endpoint tổng của OTLP Collector
OTEL_EXPORTER_OTLP_PROTOCOL	http/protobuf	Protocol: http/protobuf hoặc grpc
OTEL_EXPORTER_OTLP_HEADERS	(trống)	Headers bổ sung, định dạng key=value,key2=value2

Chi tiết cách plugin đăng ký metrics

Khi server load plugin, các bước sau xảy ra:

System metrics (đăng ký trong setSystemMetrics)

Plugin dùng pidusage để thu thập thông tin process:

// Observable gauges — đọc giá trị theo chu kỳ
const cpuGauge = meter.createObservableGauge('process_cpu_percent', {
  description: 'Process CPU usage percentage',
});
const memoryGauge = meter.createObservableGauge('process_memory_mb', {
  description: 'Process memory usage in MB',
});
const heapGauge = meter.createObservableGauge('process_heap_mb', {
  description: 'Process heap used in MB',
});

Gateway request metrics (đăng ký trong registerGatewayRequestMetrics)

Middleware trên Gateway tự động đo:

Metric	Loại	Labels	Mô tả
http_request_count	Counter	app, method, path, status_code	Đếm tổng số request
http_request_cost	Histogram	app, method, path, status_code	Phân phối thời gian xử lý (ms)
http_request_active	UpDownCounter	app, method, path	Số request đang xử lý đồng thời

Custom instrumentation

Plugin khác có thể thêm metric riêng thông qua Meter API:

class MyPlugin extends Plugin {
  async load() {
    const telemetry = this.app.pm.get('telemetry') as PluginTelemetryServer;
    const meter = this.app.telemetry.metric.getMeter();

    // Counter — đếm sự kiện
    const emailsSent = meter.createCounter('emails_sent_total', {
      description: 'Tổng số email đã gửi',
    });
    emailsSent.add(1, { template: 'welcome' });

    // Histogram — đo phân phối giá trị
    const processingTime = meter.createHistogram('job_processing_ms', {
      description: 'Thời gian xử lý background job',
      unit: 'ms',
    });
    processingTime.record(142, { job_type: 'export' });
  }
}

Chiến lược Sampling

Chiến lược	Mô tả	Khi nào dùng
Always On (1.0)	Thu thập tất cả traces	Môi trường dev, staging
Ratio (0.1)	Chỉ 10% request được ghi nhận	Production có tải cao
Parent-based	Quyết định dựa trên parent trace	Hệ thống microservices phân tán

Cảnh báo

Đặt sampling rate quá thấp (< 0.01) có thể khiến bạn bỏ lỡ các lỗi hiếm gặp. Khuyến nghị dùng tail-based sampling trên OTLP Collector để giữ lại traces có lỗi.

Prometheus metrics endpoint

Khi dùng Prometheus reader, metrics được expose tại:

GET /api/metrics

Cấu hình Prometheus scrape:

scrape_configs:
  - job_name: 'digiforce'
    scrape_interval: 60s
    metrics_path: '/api/metrics'
    static_configs:
      - targets: ['localhost:13000']

Temporality preference

Plugin cấu hình AggregationTemporalityPreference.DELTA cho OTLP exporter. Điều này có nghĩa:

• DELTA: Mỗi lần export chỉ gửi giá trị thay đổi kể từ lần export trước
• Phù hợp với backend như Prometheus, Datadog, New Relic
• Nếu backend yêu cầu CUMULATIVE, cần điều chỉnh cấu hình trong collector