Giao diện
@digiforce-nc/plugin-telemetry
Plugin OpenTelemetry — thu thập traces, metrics và logs theo chuẩn OpenTelemetry, gửi đến backend quan sát (Jaeger, Zipkin, OTLP collector).
Plugin này làm gì?
Khi ứng dụng gặp vấn đề hiệu suất hoặc lỗi, cần dữ liệu quan sát (observability) để phân tích. Plugin tích hợp OpenTelemetry SDK vào server, tự động instrument HTTP request, database query, và cho phép plugin khác thêm custom spans/metrics.
Cơ chế hoạt động
Tính năng chính
| # | Tính năng | Mô tả |
|---|---|---|
| 1 | Distributed tracing | Theo dõi request xuyên suốt các service |
| 2 | Auto-instrumentation | Tự động trace HTTP, database, Redis |
| 3 | Custom spans | Plugin khác thêm span riêng |
| 4 | Metrics | Thu thập metrics (request count, latency, error rate) |
| 5 | OTLP export | Gửi dữ liệu qua OTLP protocol (gRPC/HTTP) |
| 6 | Sampling | Cấu hình tỉ lệ sampling để giảm overhead |
Cấu hình
| Tham số | Mặc định | Mô tả |
|---|---|---|
enabled | false | Bật/tắt telemetry |
serviceName | digiforce | Tên service trong traces |
exporterType | otlp | Loại exporter (otlp, jaeger, zipkin) |
endpoint | http://localhost:4318 | OTLP collector endpoint |
samplingRate | 1.0 | Tỉ lệ sampling (0.0 - 1.0) |
enabledInstrumentations | ['http', 'db'] | Danh sách auto-instrumentation |
Kiến trúc nội bộ
Dependencies
| Package | Vai trò |
|---|---|
@digiforce-nc/server | Server framework |
@opentelemetry/sdk-node | OpenTelemetry Node.js SDK |
@opentelemetry/exporter-trace-otlp-http | OTLP trace exporter |
@opentelemetry/exporter-metrics-otlp-http | OTLP metrics exporter |
@opentelemetry/auto-instrumentations-node | Auto-instrumentation |
Lưu ý triển khai
- Telemetry tăng nhẹ overhead (~1-3% CPU) — dùng sampling trong production
- Cần OTLP collector (Jaeger, Grafana Tempo, hoặc OpenTelemetry Collector)
- Trace context tự động propagate qua HTTP headers