Bỏ qua

Observability - Câu hỏi thường gặp (FAQ)

Câu hỏi 1: Về phần observability được store khi nào?

Trả lời:

Observability data (traces, metrics, logs) được lưu trữ tự động theo quy trình sau:

  1. Khi có HTTP request đến service:
  2. TraceInterceptor tự động tạo span cho mỗi request

  3. Span được gửi đến OTEL Collector ngay sau khi request hoàn thành

  4. OTEL Collector nhận và xử lý:

  5. Collector nhận traces từ tất cả services
  6. Batch dữ liệu (mỗi 1 giây hoặc khi đủ 1024 items)

  7. Ghi vào ClickHouse ngay lập tức

  8. Lưu trữ trong ClickHouse:

  9. Traces → Database signoz_traces
  10. Metrics → Database signoz_metrics
  11. Logs → Database signoz_logs

  12. Dữ liệu được lưu vĩnh viễn (không tự động xóa)

  13. Hiển thị trong Signoz UI:

  14. Signoz Query Service đọc từ ClickHouse
  15. Traces xuất hiện trong UI sau 10-30 giây sau khi request hoàn thành

Timeline cụ thể:

Request → Service (0s)
  ↓
Tạo span (0.1s)
  ↓
Gửi đến Collector (0.2s)
  ↓
Collector batch (1s)
  ↓
Ghi vào ClickHouse (1.5s)
  ↓
Query Service đọc (2s)
  ↓
Hiển thị trong UI (10-30s)

Kết luận:

  • ✅ Tự động store: Không cần cấu hình thêm, tự động lưu mọi request
  • ✅ Real-time: Dữ liệu xuất hiện trong UI sau 10-30 giây
  • ✅ Vĩnh viễn: Dữ liệu không tự động xóa, lưu trong ClickHouse

Câu hỏi 2: Có được tự động instrument hết hay chưa?

Trả lời:

✅ ĐÃ ĐƯỢC TỰ ĐỘNG INSTRUMENT:

1. Tất cả services đã có tracing initialization:

  • ✅ API Gateway (apps/api-gateway/src/main.ts)
  • ✅ Booking Service (apps/booking-service/src/main.ts)
  • ✅ Field Service (apps/field-service/src/main.ts)
  • ✅ User Service (apps/user-service/src/main.ts)
  • ✅ Payment Service (apps/payment-service/src/main.ts)
  • ✅ Notification Service (apps/notification-service/src/main.ts)

Tất cả đều có:

import { initializeTracing } from '@football-booking/observability';
initializeTracing('service-name');

2. Auto-instrumentation bao gồm:

  • ✅ HTTP Requests: Tự động tạo spans cho mọi HTTP request
  • ✅ Express Routes: Tự động instrument Express/NestJS routes
  • ✅ PostgreSQL Queries: Tự động trace database queries
  • ✅ Redis Operations: Tự động trace Redis commands
  • ✅ HTTP Client: Tự động trace outgoing HTTP requests (axios)

3. Modules đã được import:

Tất cả services đã có trong app.module.ts:

imports: [
  TracingModule,    // ✅
  MetricsModule,    // ✅
  LoggerModule,     // ✅
],
providers: [
  {
    provide: APP_INTERCEPTOR,
    useClass: TraceInterceptor,    // ✅ Tự động tạo spans
  },
  {
    provide: APP_INTERCEPTOR,
    useClass: MetricsInterceptor,  // ✅ Tự động collect metrics
  },
]

⚠️ CẦN KIỂM TRA:

  1. Environment Variables:
  2. Services cần có OTEL_EXPORTER_OTLP_ENDPOINT hoặc SIGNOZ_OTEL_COLLECTOR_URL
  3. Nếu chạy trong Docker: http://signoz-otel-collector:4318

  4. Nếu chạy local: http://localhost:4318

  5. Network Connectivity:

  6. Services cần có thể kết nối đến OTEL Collector
  7. Kiểm tra: curl http://localhost:4318/v1/traces

Kết luận:

  • ✅ Đã instrument tự động: Tất cả services đã được setup
  • ✅ Auto-instrumentation hoạt động: HTTP, DB, Redis đều được trace tự động
  • ⚠️ Cần kiểm tra: Environment variables và network connectivity

Câu hỏi 3: Tại sao không thấy traces và logs trong Signoz?

Nguyên nhân chính:

Dựa trên logs và kiểm tra, có 3 vấn đề:

1. ⚠️ ClickHouse thiếu bảng (VẤN ĐỀ CHÍNH)

Triệu chứng:

error: "code: 60, message: Table signoz_traces.distributed_signoz_index_v3 does not exist"
error: "code: 60, message: Table signoz_metrics.distributed_samples_v4 does not exist"

Nguyên nhân:

  • Databases (signoz_traces, signoz_metrics, signoz_logs) đã tồn tại
  • Nhưng các bảng bên trong chưa được tạo
  • Signoz Query Service cần tạo các bảng này khi khởi động lần đầu

Giải pháp:

# Khởi động lại Query Service để tạo bảng
docker compose -f docker-compose.dev.yml restart signoz-query-service

# Hoặc dùng script tự động
./scripts/fix-observability.sh

2. ⚠️ OTEL Collector không thể ghi dữ liệu

Triệu chứng:

  • Collector nhận được traces từ services
  • Nhưng không thể ghi vào ClickHouse vì thiếu bảng
  • Collector status: unhealthy

Giải pháp:

  • Sau khi Query Service tạo bảng, khởi động lại Collector:
docker compose -f docker-compose.dev.yml restart signoz-otel-collector

3. ⚠️ Services có thể chưa gửi dữ liệu

Kiểm tra:

# Kiểm tra services có khởi tạo tracing
docker logs api-gateway-1 | grep -i "opentelemetry"
# Nên thấy: "✅ OpenTelemetry initialized for service: api-gateway"

# Kiểm tra environment variables
cat .env.development | grep OTEL
# Nên có: OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318

Giải pháp nhanh:

Bước 1: Chạy script fix tự động

./scripts/fix-observability.sh

Script này sẽ:

  1. Khởi động lại Query Service để tạo bảng
  2. Khởi động lại OTEL Collector
  3. Kiểm tra và báo cáo lỗi

Bước 2: Tạo traffic để test

# Gửi requests đến services
curl http://localhost:3000/health
curl http://localhost:3003/health

Bước 3: Kiểm tra trong Signoz UI

  1. Mở http://localhost:3301
  2. Vào Traces → Chọn "Last 15 minutes"
  3. Bạn nên thấy traces sau 30-60 giây

Checklist để debug:

  • [ ] Signoz services đang chạy: docker ps | grep signoz
  • [ ] OTEL Collector healthy: docker ps | grep otel-collector (không có "unhealthy")
  • [ ] Query Service healthy: docker ps | grep query-service (có "healthy")
  • [ ] Không có lỗi "Table does not exist" trong Collector logs
  • [ ] Services có initializeTracing() trong logs
  • [ ] Environment variables được set
  • [ ] Đã tạo traffic (gửi requests)
  • [ ] Đã đợi 30-60 giây sau khi tạo traffic

Commands để verify:

# 1. Kiểm tra status
docker ps --filter "name=signoz"

# 2. Kiểm tra Collector logs
docker logs --tail 20 signoz-otel-collector-1 | grep -i "error\|ready"

# 3. Kiểm tra services có gửi data
docker logs api-gateway-1 | grep -i "opentelemetry"

# 4. Test connectivity
curl -v http://localhost:4318/v1/traces -X POST

Tóm tắt

✅ Đã hoàn thành:

  1. Tất cả services đã được instrument tự động
  2. Observability data được store tự động khi có requests
  3. Cấu hình đã đúng: Modules, interceptors, initialization

⚠️ Vấn đề hiện tại:

  1. ClickHouse thiếu bảng → Cần khởi động lại Query Service
  2. OTEL Collector không thể ghi → Sẽ fix sau khi có bảng

🚀 Giải pháp:

  1. Chạy ./scripts/fix-observability.sh để fix tự động
  2. Tạo traffic để test
  3. Kiểm tra trong Signoz UI sau 1-2 phút

📚 Tài liệu tham khảo:

  • docs/OBSERVABILITY-TROUBLESHOOTING.md - Hướng dẫn chi tiết
  • docs/OBSERVABILITY.md - Setup guide đầy đủ
  • scripts/fix-observability.sh - Script fix tự động