Observability Troubleshooting Guide

Vấn đề: Không thấy traces và logs trong Signoz

Tóm tắt vấn đề

Khi vào Signoz UI (http://localhost:3301), bạn thấy:

Traces: "Retrieving your traces!" nhưng không có dữ liệu
Logs: "No data" với lỗi "Something went wrong"
Filters: Tất cả đều hiển thị "No data found" (Service Name, Environment, Status)

Nguyên nhân

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

ClickHouse thiếu bảng: Các database (signoz_metrics, signoz_traces, signoz_logs) đã tồn tại nhưng các bảng bên trong chưa được tạo
OTEL Collector không thể ghi dữ liệu: Collector nhận được traces từ services nhưng không thể lưu vào ClickHouse vì thiếu bảng
Services có thể chưa gửi dữ liệu: Cần kiểm tra xem services có đang gửi traces đến collector không

Giải pháp

Bước 1: Kiểm tra trạng thái services

# Kiểm tra Signoz services
docker ps --filter "name=signoz"

# Kiểm tra OTEL Collector logs (tìm lỗi về missing tables)
docker logs --tail 50 football-booking-backend-boilerplate-signoz-otel-collector-1

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

Bước 2: Khởi động lại Signoz Query Service để tạo bảng

Signoz Query Service sẽ tự động tạo các bảng cần thiết khi khởi động lần đầu. Nếu bảng chưa được tạo, hãy khởi động lại:

# Dừng và xóa Query Service (giữ lại volume để không mất dữ liệu)
docker compose -f docker-compose.dev.yml stop signoz-query-service
docker compose -f docker-compose.dev.yml rm -f signoz-query-service

# Khởi động lại Query Service (sẽ tự động tạo bảng)
docker compose -f docker-compose.dev.yml up -d signoz-query-service

# Đợi 30-60 giây để Query Service khởi tạo bảng
sleep 30

# Kiểm tra logs để xem có lỗi không
docker logs --tail 20 football-booking-backend-boilerplate-signoz-query-service-1

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

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

# 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

Bước 4: Kiểm tra services có gửi dữ liệu

4.1. Kiểm tra environment variables

Services cần có biến môi trường để kết nối đến OTEL Collector:

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

Cần có:

OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
# hoặc
SIGNOZ_OTEL_COLLECTOR_URL=http://localhost:4318

Lưu ý: Nếu services chạy trong Docker, cần dùng http://signoz-otel-collector:4318 thay vì localhost.

4.2. Kiểm tra services có khởi tạo tracing

Kiểm tra logs của services khi khởi động:

# API Gateway
docker logs football-booking-backend-boilerplate-api-gateway-1 | grep -i "opentelemetry\|tracing"

# Booking Service
docker logs football-booking-backend-boilerplate-booking-service-1 | grep -i "opentelemetry\|tracing"

Bạn nên thấy:

✅ OpenTelemetry initialized for service: api-gateway
   OTLP Endpoint: http://localhost:4318

4.3. Tạo traffic để test

Gửi một số requests đến services để tạo traces:

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

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

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

Mở http://localhost:3301
Vào Traces → Chọn time range "Last 15 minutes"
Bạn nên thấy traces nếu mọi thứ hoạt động đúng

Khi nào observability data được store?

Quy trình lưu trữ dữ liệu:

Service tạo trace/span:
Khi có HTTP request, TraceInterceptor tự động tạo span
Service gửi span đến OTEL Collector qua OTLP (HTTP port 4318)
OTEL Collector nhận dữ liệu:
Collector nhận traces/metrics/logs từ services
Xử lý và batch dữ liệu (mỗi 1 giây hoặc khi đủ 1024 items)
OTEL Collector ghi vào ClickHouse:
Traces → signoz_traces database
Metrics → signoz_metrics database
Logs → signoz_logs database
Signoz Query Service đọc từ ClickHouse:
Query Service query ClickHouse để hiển thị trong UI
Dữ liệu được lưu trữ vĩnh viễn trong ClickHouse

Timeline:

Real-time: Traces xuất hiện trong UI sau 10-30 giây sau khi request hoàn thành
Batch processing: Collector batch dữ liệu mỗi 1 giây (configurable)
Storage: Dữ liệu được lưu vĩnh viễn trong ClickHouse

Có được tự động instrument hết hay chưa?

✅ Đã được instrument:

API Gateway (apps/api-gateway/src/main.ts):
✅ initializeTracing('api-gateway') được gọi
✅ TracingModule, MetricsModule, LoggerModule được import
✅ TraceInterceptor và MetricsInterceptor được đăng ký globally
Booking Service (apps/booking-service/src/main.ts):
✅ initializeTracing('booking-service') được gọi
✅ Observability modules được import
✅ Interceptors được đăng ký
Field Service (apps/field-service/src/main.ts):
✅ initializeTracing('field-service') được gọi
User Service (apps/user-service/src/main.ts):
✅ initializeTracing('user-service') được gọi
Payment Service (apps/payment-service/src/main.ts):
✅ initializeTracing('payment-service') được gọi
Notification Service (apps/notification-service/src/main.ts):
✅ initializeTracing('notification-service') được gọi

🔍 Auto-instrumentation bao gồm:

HTTP requests: Tự động tạo spans cho mọi HTTP request
Express routes: Tự động instrument Express routes
PostgreSQL queries: Tự động trace database queries
Redis operations: Tự động trace Redis commands
Custom spans: Có thể tạo custom spans bằng TraceService

⚠️ Cần kiểm tra:

Environment variables: Mỗi service cần có OTEL_EXPORTER_OTLP_ENDPOINT hoặc SIGNOZ_OTEL_COLLECTOR_URL
Network connectivity: Services cần có thể kết nối đến signoz-otel-collector:4318 (nếu chạy trong Docker)
ClickHouse tables: Các bảng cần được tạo bởi Query Service

Script tự động fix

Tạo file scripts/fix-observability.sh:

#!/bin/bash
set -e

echo "🔧 Fixing Observability Setup..."

# 1. Restart Query Service to create tables
echo "1. Restarting Signoz Query Service..."
docker compose -f docker-compose.dev.yml stop signoz-query-service
docker compose -f docker-compose.dev.yml rm -f signoz-query-service
docker compose -f docker-compose.dev.yml up -d signoz-query-service

echo "⏳ Waiting for Query Service to initialize tables (30s)..."
sleep 30

# 2. Restart OTEL Collector
echo "2. Restarting OTEL Collector..."
docker compose -f docker-compose.dev.yml restart signoz-otel-collector

# 3. Check status
echo "3. Checking service status..."
docker ps --filter "name=signoz" --format "table {{.Names}}\t{{.Status}}"

# 4. Check for errors
echo "4. Checking for errors..."
echo "--- OTEL Collector logs (last 10 lines) ---"
docker logs --tail 10 football-booking-backend-boilerplate-signoz-otel-collector-1 2>&1 | grep -i "error\|ready" || echo "No errors found"

echo ""
echo "✅ Fix complete!"
echo ""
echo "📝 Next steps:"
echo "1. Wait 1-2 minutes for services to stabilize"
echo "2. Generate some traffic to your services"
echo "3. Check Signoz UI at http://localhost:3301"
echo "4. Go to Traces → Select 'Last 15 minutes'"

Kiểm tra nhanh

Checklist:

[ ] Signoz services đang chạy (docker ps | grep signoz)
[ ] OTEL Collector healthy (không có lỗi "Table does not exist")
[ ] Query Service healthy
[ ] Services có initializeTracing() trong main.ts
[ ] Environment variables được set (OTEL_EXPORTER_OTLP_ENDPOINT)
[ ] Đã tạo traffic (gửi requests đến services)
[ ] Đã đợi 30-60 giây sau khi tạo traffic

Commands để verify:

# 1. Check services status
docker ps --filter "name=signoz"

# 2. Check OTEL Collector logs (should not have "Table does not exist")
docker logs --tail 20 football-booking-backend-boilerplate-signoz-otel-collector-1 | grep -i "error\|ready"

# 3. Check if services are sending data
docker logs football-booking-backend-boilerplate-api-gateway-1 | grep -i "opentelemetry"

# 4. Test connectivity
curl -v http://localhost:4318/v1/traces -X POST -H "Content-Type: application/json" -d '{}'

Tài liệu tham khảo

Signoz Documentation
OpenTelemetry Node.js
docs/OBSERVABILITY.md - Hướng dẫn setup đầy đủ
docs/CLICKHOUSE-DATABASES-FIX.md - Fix về databases
docs/OTEL-COLLECTOR-FIX.md - Fix về collector config