9ba4a478ee
- Updated Mermaid diagrams in the deployment and development guides for better visual representation and consistency. - Improved formatting and clarity in the Kubernetes local deployment and IAM migration guides, including detailed workflows and troubleshooting sections. - Enhanced the Vietnamese documentation to align with the English version, ensuring consistency across guides. - Added quick tips and common issues sections to facilitate user navigation and understanding.
195 lines
7.0 KiB
Markdown
195 lines
7.0 KiB
Markdown
# 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**
|
|
|