# 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

```mermaid
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:

```bash
./scripts/observability/start.sh
```

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

```bash
# Đả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:

```bash
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](http://localhost:3001) | `admin` / `admin` | Dashboard chính để theo dõi. |
| **Prometheus** | [http://localhost:9090](http://localhost:9090) | N/A | Xem metrics thô và trạng thái target. |
| **Loki** | [http://localhost:3100](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](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ụ:

```logql
{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

```logql
{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

```promql
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**