Bỏ qua

Hướng dẫn Fix Observability - Không có data trong Signoz

🔍 Vấn đề hiện tại

Bạn không thấy traces và logs trong Signoz UI mặc dù:

  • ✅ Services đã được instrument
  • ✅ Signoz services đang chạy
  • ✅ ClickHouse databases đã tồn tại

🎯 Nguyên nhân

Có 3 vấn đề chính:

  1. ClickHouse connection string sai format → Query Service không thể kết nối đúng
  2. ClickHouse thiếu bảng → Collector không thể ghi data
  3. Services không chạy hoặc không gửi data → Không có data để hiển thị

✅ Giải pháp từng bước

Bước 1: Fix ClickHouse Connection String (ĐÃ FIX)

Connection string trong docker-compose.dev.yml đã được sửa từ:

ClickHouseUrl: tcp://...@clickhouse:9000?database=signoz # ❌ Sai

Thành:

ClickHouseUrl: tcp://...@clickhouse:9000/signoz # ✅ Đúng (path-style)

Bước 2: Khởi động lại Query Service

# Restart Query Service để nó tạo bảng
docker compose -f docker-compose.dev.yml restart signoz-query-service

# Đợi 1-2 phút để Query Service tạo bảng
sleep 60

# Kiểm tra logs
docker logs --tail 20 football-booking-backend-boilerplate-signoz-query-service-1

Lưu ý: Query Service cần thời gian để tạo các bảng trong ClickHouse. Đợi ít nhất 1-2 phút.

Bước 3: Kiểm tra bảng đã được tạo

# Kiểm tra bảng trong signoz_traces
docker exec football-booking-backend-boilerplate-clickhouse-1 \
  clickhouse-client --password clickhouse123 \
  --query "SHOW TABLES FROM signoz_traces"

# Kiểm tra bảng trong signoz_metrics
docker exec football-booking-backend-boilerplate-clickhouse-1 \
  clickhouse-client --password clickhouse123 \
  --query "SHOW TABLES FROM signoz_metrics"

Nếu thấy các bảng như distributed_signoz_index_v3, distributed_samples_v4, etc. → ✅ Bảng đã được tạo.

Bước 4: Khởi động lại OTEL Collector

docker compose -f docker-compose.dev.yml restart signoz-otel-collector

# Đợi 30 giây
sleep 30

# Kiểm tra logs - không nên còn lỗi "Table does not exist"
docker logs --tail 20 football-booking-backend-boilerplate-signoz-otel-collector-1 | grep -i "error\|ready"

Bước 5: QUAN TRỌNG - Start Services

Services KHÔNG chạy trong Docker, chúng chạy bằng NX trên local:

# Option 1: Start tất cả services (recommended)
yarn dev

# Option 2: Start từng service riêng
yarn dev:gateway      # API Gateway (port 3000)
yarn dev:booking      # Booking Service (port 3003)
# ... các service khác

Kiểm tra services đang chạy:

# Kiểm tra ports
lsof -i :3000  # API Gateway
lsof -i :3003  # Booking Service

Bước 6: Kiểm tra Services có gửi data

# Kiểm tra API Gateway logs
# Tìm dòng "OpenTelemetry initialized"
# (Cần chạy service trước)

# Hoặc kiểm tra trong terminal khi start service
# Bạn nên thấy:
# ✅ OpenTelemetry initialized for service: api-gateway
#    OTLP Endpoint: http://localhost:4318

Bước 7: Tạo Traffic để Test

# Test API Gateway
curl http://localhost:3000/health

# Test Booking Service (nếu có endpoint public)
curl http://localhost:3003/health

# Hoặc gửi nhiều requests
for i in {1..10}; do
  curl http://localhost:3000/health
  sleep 1
done

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

  1. Mở http://localhost:3301
  2. Đăng nhập (hoặc tạo account nếu lần đầu)
  3. Vào Traces → Chọn time range "Last 15 minutes"
  4. Đợi 30-60 giây sau khi tạo traffic
  5. Bạn nên thấy traces

🔧 Script tự động fix

Đã có script scripts/fix-observability.sh để tự động fix:

./scripts/fix-observability.sh

Script này sẽ:

  • ✅ Restart Query Service
  • ✅ Restart OTEL Collector
  • ✅ Kiểm tra databases
  • ✅ Báo cáo lỗi

Nhưng script KHÔNG start services - bạn cần tự start bằng yarn dev.

📋 Checklist

Trước khi kiểm tra Signoz, đảm bảo:

  • [ ] Signoz services đang chạy: docker ps | grep signoz
  • [ ] ClickHouse connection string đã được fix (path-style /signoz)
  • [ ] Query Service đã restart và đợi 1-2 phút
  • [ ] ClickHouse có bảng (check bằng SHOW TABLES)
  • [ ] OTEL Collector không còn lỗi "Table does not exist"
  • [ ] Services đang chạy (yarn dev hoặc nx serve)
  • [ ] Services có logs "OpenTelemetry initialized"
  • [ ] Đã tạo traffic (gửi requests)
  • [ ] Đã đợi 30-60 giây sau khi tạo traffic

🐛 Troubleshooting

Vẫn không thấy data?

1. Kiểm tra services có gửi data không:

# Kiểm tra OTEL Collector có nhận được data không
docker logs --tail 50 football-booking-backend-boilerplate-signoz-otel-collector-1 | grep -i "received\|exported\|span"

# Nếu không thấy gì → Services không gửi data

2. Kiểm tra environment variables:

Services cần có OTEL_EXPORTER_OTLP_ENDPOINT hoặc SIGNOZ_OTEL_COLLECTOR_URL:

# Kiểm tra trong .env hoặc .env.development
cat .env.development | grep OTEL

# Nên có:
# OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318

3. Kiểm tra network connectivity:

# Test xem có thể kết nối đến OTEL Collector không
curl -v http://localhost:4318/v1/traces -X POST -H "Content-Type: application/json" -d '{}'

4. Kiểm tra ClickHouse tables:

# Nếu bảng vẫn chưa có, có thể cần đợi lâu hơn hoặc restart lại
docker compose -f docker-compose.dev.yml restart signoz-query-service
sleep 120  # Đợi 2 phút

5. Kiểm tra Query Service logs:

docker logs --tail 50 football-booking-backend-boilerplate-signoz-query-service-1 | grep -i "error\|table\|migration"

Nếu vẫn còn lỗi "Unknown setting 'database'", có thể cần:

  • Kiểm tra lại connection string format
  • Hoặc thử không có database trong connection string

📚 Tài liệu tham khảo

  • docs/OBSERVABILITY-VIETNAMESE.md - FAQ tiếng Việt
  • docs/OBSERVABILITY-TROUBLESHOOTING.md - Troubleshooting chi tiết
  • docs/OBSERVABILITY.md - Setup guide đầy đủ
  • scripts/fix-observability.sh - Script fix tự động

🎯 Tóm tắt

Vấn đề chính: Services không chạy → Không có data để gửi → Không có gì để hiển thị

Giải pháp:

  1. Fix connection string (✅ đã fix)
  2. Restart Query Service và đợi tạo bảng
  3. Start services bằng yarn dev ⚠️ QUAN TRỌNG
  4. Tạo traffic
  5. Kiểm tra Signoz UI