pos-system/docs/vi/guides/observability.md

Hướng dẫn Observability Stack

Tài liệu này hướng dẫn cách sử dụng stack observability (Grafana, Prometheus, Loki, Promtail) được tích hợp trong dự án.

Tổng quan Kiến trúc

graph TB
    subgraph Services["🚀 Microservices"]
        IAM["IAM Service"]
        User["User Service"]
        Order["Order Service"]
    end
    
    subgraph Collectors["📊 Data Collectors"]
        Prometheus["Prometheus<br/>📈 Metrics Collector"]
        Promtail["Promtail<br/>📝 Log Collector"]
    end
    
    subgraph Storage["💾 Storage"]
        PrometheusDB["Prometheus TSDB<br/>Metrics Storage"]
        Loki["Loki<br/>Log Aggregation"]
    end
    
    subgraph Visualization["📊 Visualization"]
        Grafana["Grafana<br/>Dashboard & Analytics"]
    end
    
    IAM -->|"metrics /metrics"| Prometheus
    User -->|"metrics /metrics"| Prometheus
    Order -->|"metrics /metrics"| Prometheus
    
    IAM -->|"logs (stdout)"| Promtail
    User -->|"logs (stdout)"| Promtail
    Order -->|"logs (stdout)"| Promtail
    
    Prometheus -->|"store"| PrometheusDB
    Promtail -->|"push logs"| Loki
    
    PrometheusDB -->|"query PromQL"| Grafana
    Loki -->|"query LogQL"| Grafana
    
    style Services fill:#1a1a2e,stroke:#16213e,stroke-width:2px,color:#ffffff
    style Collectors fill:#0f3460,stroke:#16213e,stroke-width:2px,color:#ffffff
    style Storage fill:#16213e,stroke:#0f3460,stroke-width:2px,color:#ffffff
    style Visualization fill:#533483,stroke:#16213e,stroke-width:2px,color:#ffffff
    
    style IAM fill:#e94560,stroke:#c81e3b,stroke-width:2px,color:#ffffff
    style User fill:#e94560,stroke:#c81e3b,stroke-width:2px,color:#ffffff
    style Order fill:#e94560,stroke:#c81e3b,stroke-width:2px,color:#ffffff
    
    style Prometheus fill:#f39c12,stroke:#d68910,stroke-width:2px,color:#ffffff
    style Promtail fill:#f39c12,stroke:#d68910,stroke-width:2px,color:#ffffff
    
    style PrometheusDB fill:#3498db,stroke:#2874a6,stroke-width:2px,color:#ffffff
    style Loki fill:#3498db,stroke:#2874a6,stroke-width:2px,color:#ffffff
    
    style Grafana fill:#9b59b6,stroke:#7d3c98,stroke-width:2px,color:#ffffff

Các thành phần chính

• Prometheus: Thu thập metrics từ các services qua endpoint /metrics
• Loki: Thu thập và tổng hợp logs từ các container
• Promtail: Agent quét logs từ Docker containers và đẩy đến Loki
• Grafana: Dashboard trực quan hóa metrics (Prometheus) và logs (Loki)

Bắt đầu

Yêu cầu tiên quyết

• Đã cài đặt Docker và Docker Compose.
• Đã có network microservices-network (thường được tạo bởi stack chính của ứng dụng hoặc tạo thủ công).

Khởi chạy Stack

Bạn có thể khởi chạy dễ dàng bằng script có sẵn:

./scripts/observability/start.sh

Hoặc chạy thủ công:

# Đảm bảo network đã tồn tại
docker network create microservices-network || true

cd infra/observability
docker-compose -f docker-compose.observability.yml up -d

Kiểm tra xem các container đã chạy chưa:

docker ps

Bạn sẽ thấy các container grafana, prometheus, loki, và promtail.

Truy cập Dịch vụ

Dịch vụ	URL	Tài khoản (nếu có)	Mô tả
Grafana	http://localhost:3001	admin / admin	Dashboard chính để theo dõi.
Prometheus	http://localhost:9090	N/A	Xem metrics thô và trạng thái target.
Loki	http://localhost:3100	N/A	API tổng hợp log (không có giao diện web).

Sử dụng Grafana

1. Đăng nhập: Truy cập http://localhost:3001 và đăng nhập với admin/admin.
2. Khám phá dữ liệu (Explore):
   • Chọn biểu tượng Explore (hình la bàn) ở thanh bên trái.
   • Chọn Loki từ menu datasource để tìm kiếm logs.
   • Chọn Prometheus từ menu datasource để truy vấn metrics.

Xem Logs (Loki)

Trong giao diện Explore với Loki đã chọn:

1. Nhấn nút Label browser.
2. Chọn một label, ví dụ: container.
3. Chọn tên container cụ thể (ví dụ: iam-service hoặc traefik).
4. Nhấn Show logs.

Bạn cũng có thể viết truy vấn LogQL thủ công, ví dụ:

{container="iam-service"}

Xem Metrics (Prometheus)

Trong giao diện Explore với Prometheus đã chọn:

1. Nhập tên metric vào ô truy vấn (ví dụ: up, container_memory_usage_bytes).
2. Nhấn Run query.

Cấu hình

• Prometheus: Các rules và targets được cấu hình tại infra/observability/prometheus/prometheus.yml.
• Promtail: Rules để quét log được cấu hình tại infra/observability/promtail/promtail-config.yml.
• Grafana: Cấu hình datasources và dashboards provisioning nằm trong infra/observability/grafana/.

💡 Quick Tips

Troubleshooting chung

Vấn đề	Triệu chứng	Giải pháp
⚠️ Không thấy logs	Grafana Explore không hiển thị logs	Kiểm tra Promtail đang chạy: docker ps | grep promtail
📊 Metrics bị thiếu	Services không xuất hiện trong Prometheus targets	Kiểm tra /metrics endpoint của service
🔴 Container không khởi động	docker ps không show container	Xem logs: docker-compose logs <service-name>
🌐 Network issue	Services không kết nối được	Tạo network: docker network create microservices-network

LogQL Quick Reference

{container="iam-service"}                           # Logs từ IAM service
{container="iam-service"} |= "error"                # Chỉ logs có chứa "error"
{container="iam-service"} | json                    # Parse JSON logs
{container="iam-service"} | json | level="error"    # Filter by log level

PromQL Quick Reference

up                                                  # Status của tất cả targets (1 = up, 0 = down)
rate(http_requests_total[5m])                       # Request rate trong 5 phút
container_memory_usage_bytes{container="iam-service"}  # Memory usage của IAM service

Best Practices

• ✅ Naming Convention: Đặt tên metrics theo pattern <namespace>_<subsystem>_<name>_<unit>
• ✅ Labels: Sử dụng labels để phân loại dữ liệu (environment, service, instance)
• ✅ Retention: Cấu hình retention phù hợp cho Prometheus và Loki
• ✅ Alerting: Thiết lập alerts cho các metrics quan trọng
• ⚠️ Cardinality: Tránh sử dụng quá nhiều unique labels (gây tăng cardinality)

Color Palette Reference

Diagram sử dụng bảng màu tối để dễ nhìn:

Loại Component	Fill Color	Stroke Color	Mục đích
🚀 Services	#e94560	#c81e3b	Microservices (đỏ)
📊 Collectors	#f39c12	#d68910	Thu thập dữ liệu (cam)
💾 Storage	#3498db	#2874a6	Lưu trữ (xanh dương)
📊 Visualization	#9b59b6	#7d3c98	Trực quan hóa (tím)
📦 Subgraphs	#1a1a2e - #533483	#16213e - #0f3460	Nhóm logic

Tất cả text sử dụng color:#ffffff (trắng) để dễ đọc trên nền tối