Giao diện

Câu hỏi thường gặp (FAQ) — Telemetry ​

Cài đặt ​

Bật telemetry có ảnh hưởng hiệu năng không? ​

Có, nhưng không đáng kể. Plugin tăng thêm khoảng 1-5% overhead tùy thuộc lượng request và cấu hình. Để giảm thiểu:

  • Dùng batch processor thay vì simple (mặc định đã là batch)
  • Đặt TELEMETRY_HTTP_RECORD_THRESHOLD cao hơn để bỏ qua request nhanh
  • Giảm tần suất export bằng cách tăng TELEMETRY_METRIC_INTERVAL
  • Dùng sampling rate thấp hơn 1.0 cho traces

Cần cài đặt gì ngoài plugin? ​

Tùy thuộc backend bạn muốn dùng:

Mục đíchCông cụ cần cài
Xem distributed tracesJaeger, Grafana Tempo, hoặc Zipkin
Dashboard metricsPrometheus + Grafana
Log aggregationELK Stack (Elasticsearch, Logstash, Kibana)
Trung gian tổng hợpOpenTelemetry Collector (khuyên dùng)

Khuyến nghị

Dùng OpenTelemetry Collector làm trung gian. Nó nhận dữ liệu từ ứng dụng rồi fan-out đến nhiều backend khác nhau, giúp bạn không cần thay đổi cấu hình ứng dụng khi đổi backend.

Plugin có hoạt động trên tất cả các instance không? ​

Không hoàn toàn. System metrics (process_cpu_percent, process_memory_mb, process_heap_mb) và gateway request metrics chỉ được đăng ký trên instance có tên main. Các worker instance khác sẽ bỏ qua để tránh trùng lặp dữ liệu.

Cấu hình ​

Làm sao chỉ thu thập traces cho API chậm? ​

Có hai cách:

  1. Phía ứng dụng: Đặt TELEMETRY_HTTP_RECORD_THRESHOLD=500 để chỉ ghi histogram cho request mất hơn 500ms
  2. Phía collector: Dùng tail-based sampling trên OpenTelemetry Collector để chỉ giữ traces có duration cao hoặc có lỗi
yaml
# otel-collector-config.yaml — ví dụ tail-based sampling
processors:
  tail_sampling:
    policies:
      - name: slow-requests
        type: latency
        latency:
          threshold_ms: 500
      - name: errors
        type: status_code
        status_code:
          status_codes: [ERROR]

Có thể xuất ra nhiều backend cùng lúc không? ​

Có. Cấu hình OpenTelemetry Collector để fan-out dữ liệu đến nhiều backend:

yaml
exporters:
  jaeger:
    endpoint: "jaeger:14250"
  prometheus:
    endpoint: "0.0.0.0:8889"
  loki:
    endpoint: "http://loki:3100/loki/api/v1/push"

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

DELTA temporality nghĩa là gì? ​

Plugin sử dụng AggregationTemporalityPreference.DELTA — nghĩa là mỗi lần export chỉ gửi phần thay đổi kể từ lần trước, không phải giá trị tích lũy. Hầu hết các backend hiện đại (Prometheus, Datadog) đều hỗ trợ DELTA.

Xử lý sự cố ​

Không thấy metrics trong Prometheus? ​

Kiểm tra theo thứ tự:

  1. Xác nhận TELEMETRY_ENABLED=true trong .env
  2. Kiểm tra TELEMETRY_HTTP_URL trỏ đúng đến OTLP Collector
  3. Đảm bảo OTLP Collector đang chạy và có pipeline trỏ đến Prometheus exporter
  4. Kiểm tra Prometheus scrape config có target đúng
  5. Đợi ít nhất 60 giây (khoảng thời gian export mặc định) sau khi khởi động

Metrics http_request_cost không có dữ liệu? ​

Có thể do TELEMETRY_HTTP_RECORD_THRESHOLD đặt quá cao. Kiểm tra:

bash
# Xem giá trị hiện tại
echo $TELEMETRY_HTTP_RECORD_THRESHOLD

Nếu giá trị là 5000 (5 giây) mà không có request nào chậm hơn 5s, histogram sẽ trống. Hạ ngưỡng xuống hoặc đặt 0 để ghi tất cả.

Log server báo lỗi kết nối collector? ​

Error: connect ECONNREFUSED 127.0.0.1:4318

Nguyên nhân: OTLP Collector chưa chạy hoặc endpoint sai. Giải pháp:

  • Kiểm tra collector đang chạy: docker ps | grep otel
  • Xác nhận port 4318 (HTTP) hoặc 4317 (gRPC) đang mở
  • Nếu dùng Docker, đảm bảo network giữa ứng dụng và collector kết nối được

Làm sao correlate logs với traces? ​

Plugin tự động inject traceId vào structured logs khi telemetry bật. Để tìm log liên quan đến một trace:

  1. Mở Jaeger, tìm trace cần xem → copy traceId
  2. Trong log backend (ELK, Loki), tìm theo field traceId
  3. Bạn sẽ thấy tất cả log entries được ghi trong cùng request đó