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