ADR-0004: OpenTelemetry + SigNoz cho observability (self-hosted, thay vì SaaS APM)
- Status: Accepted
- Date: ~2026-06-27 (backfilled 2026-07-25)
- Supersedes: —
- Superseded by: —
Bối cảnh
Với nhiều service giao tiếp lẫn nhau (ADR-0001), một request có thể đi qua api-gateway → nhiều service nội bộ → DB/Kafka. Cần distributed tracing + metrics + logs tập trung để debug được, thay vì chỉ xem log rời rạc từng container. Ràng buộc: hạ tầng tự vận hành trên K3s, không phụ thuộc SaaS trả phí theo traffic.
Quyết định
Dùng OpenTelemetry SDK (chuẩn vendor-neutral) instrument ở từng service
(initializeTracing('service-name') gọi trong main.ts trước mọi import
khác), export traces/metrics/logs qua OTLP (gRPC/HTTP) tới SigNoz tự host:
Services (OTel SDK) → OTLP → SigNoz OTEL Collector (4317/4318)
→ ClickHouse (lưu trữ)
→ SigNoz Query Service + Frontend (dashboards, alerts, trace explorer)
- Logic chung đóng gói trong
libs/observability(TraceService tạo custom span cho business operation) - SigNoz UI expose qua Nginx reverse proxy hạ tầng, tách khỏi api-gateway (xem ADR-0007)
Lựa chọn khác đã cân nhắc
- SaaS APM (Datadog, New Relic...): tích hợp nhanh hơn, nhưng chi phí theo traffic/host và phụ thuộc vendor — loại vì mục tiêu tự chủ hạ tầng trên K3s và kiểm soát chi phí ở giai đoạn dự án cá nhân/học tập.
- ELK/Grafana stack riêng lẻ (Loki + Tempo + Prometheus): linh hoạt nhưng cần ghép 3 hệ thống + UI riêng; SigNoz gộp traces/metrics/logs + UI trong 1 stack, giảm số thành phần cần vận hành — chọn SigNoz để giảm effort vận hành.
- Chỉ dùng console/file log không tracing: không đủ để debug lỗi xuyên service trong kiến trúc microservices — loại.
Hệ quả
- Được: trace xuyên service, metrics, logs tập trung 1 nơi; chuẩn OTel giúp
không bị khoá vào SigNoz (có thể đổi backend export sau nếu cần) — xem
các lần đổi hướng troubleshooting trong
docs/OBSERVABILITY-*.md. - Đánh đổi: thêm ClickHouse + SigNoz collector/frontend cần vận hành trên
K3s (tốn tài nguyên); độ phức tạp setup ban đầu cao hơn hẳn so với chỉ
console log, thể hiện qua số lượng lớn doc troubleshooting đã phát sinh
(
OBSERVABILITY-FIX-GUIDE.md,CLICKHOUSE-DATABASES-FIX.md,SIGNOZ-405-FIX.md...).