Add Promtail service to Docker Compose and update Loki configuration

- Introduced a new Promtail service in `docker-compose.observability.yml` for log collection. - Configured Promtail with necessary volumes and command for log processing. - Updated `loki-config.yml` to include `allow_structured_metadata` setting for enhanced metadata handling.
2025-12-27 10:47:35 +07:00
parent 5ff8035013
commit d92cfb3bf3
8 changed files with 268 additions and 3 deletions
--- a/docs/en/guides/observability.md
+++ b/docs/en/guides/observability.md
@@ -0,0 +1,89 @@
+# Observability Stack Guide
+
+This guide explains how to use the observability stack (Grafana, Prometheus, Loki, Promtail) included in the infrastructure.
+
+## Architecture Overview
+
+The stack consists of the following components:
+
+-   **Prometheus**: Collects metrics from services.
+-   **Loki**: Collects logs.
+-   **Promtail**: Scrapes logs from Docker containers and pushes them to Loki.
+-   **Grafana**: Visualization dashboard for metrics (from Prometheus) and logs (from Loki).
+
+## Getting Started
+
+### Prerequisites
+
+-   Docker and Docker Compose installed.
+-   Existing `microservices-network` (created by the main application stack or manually).
+
+### Starting the Stack
+
+You can easily start the stack using the provided script:
+
+```bash
+./scripts/observability/start.sh
+```
+
+Or manually:
+
+```bash
+# Ensure network exists
+docker network create microservices-network || true
+
+cd infra/observability
+docker-compose -f docker-compose.observability.yml up -d
+```
+
+Check if all containers are running:
+
+```bash
+docker ps
+```
+
+You should see `grafana`, `prometheus`, `loki`, and `promtail`.
+
+## Accessing Services
+
+| Service | URL | Credentials (if applicable) | Description |
+| :--- | :--- | :--- | :--- |
+| **Grafana** | [http://localhost:3001](http://localhost:3001) | `admin` / `admin` | Main dashboard for visualization. |
+| **Prometheus** | [http://localhost:9090](http://localhost:9090) | N/A | Raw metrics and target status. |
+| **Loki** | [http://localhost:3100](http://localhost:3100) | N/A | Log aggregation API (no UI). |
+
+## Using Grafana
+
+1.  **Login**: Access [http://localhost:3001](http://localhost:3001) and login with `admin`/`admin`.
+2.  **Explore Data**:
+    -   Go to **Explore** (compass icon) in the sidebar.
+    -   Select **Loki** from the datasource dropdown to search logs.
+    -   Select **Prometheus** from the datasource dropdown to query metrics.
+
+### Viewing Logs (Loki)
+
+In the **Explore** view with **Loki** selected:
+
+1.  Click **Label browser**.
+2.  Select a label, e.g., `container`.
+3.  Choose a specific container (e.g., `auth-service` or `traefik`).
+4.  Click **Show logs**.
+
+You can also write LogQL queries manually, for example:
+
+```logql
+{container="auth-service"}
+```
+
+### Viewing Metrics (Prometheus)
+
+In the **Explore** view with **Prometheus** selected:
+
+1.  Type a metric name in the query field (e.g., `up`, `container_memory_usage_bytes`).
+2.  Click **Run query**.
+
+## Configuration
+
+-   **Prometheus**: Rules and targets are configured in `infra/observability/prometheus/prometheus.yml`.
+-   **Promtail**: Log scraping rules are configured in `infra/observability/promtail/promtail-config.yml`.
+-   **Grafana**: Datasources and dashboards provisioning are in `infra/observability/grafana/`.
--- a/docs/vi/guides/observability.md
+++ b/docs/vi/guides/observability.md
@@ -0,0 +1,89 @@
+# 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
+
+Hệ thống bao gồm các thành phần sau:
+
+-   **Prometheus**: Thu thập metrics từ các services.
+-   **Loki**: Thu thập logs.
+-   **Promtail**: Quét logs từ các Docker container và gửi về Loki.
+-   **Grafana**: Bảng điều khiển (dashboard) để trực quan hóa metrics (từ Prometheus) và logs (từ 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ụ: `auth-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="auth-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/`.
--- a/infra/observability/docker-compose.observability.yml
+++ b/infra/observability/docker-compose.observability.yml
@@ -1,4 +1,4 @@
-version: '3.8'
+

 services:
  prometheus:
@@ -48,6 +48,18 @@ services:
    networks:
      - microservices-network

+  promtail:
+    image: grafana/promtail:latest
+    container_name: promtail
+    volumes:
+      - /var/lib/docker/containers:/var/lib/docker/containers:ro
+      - /var/run/docker.sock:/var/run/docker.sock
+      - ./promtail/promtail-config.yml:/etc/promtail/promtail-config.yml
+    command: -config.file=/etc/promtail/promtail-config.yml
+    networks:
+      - microservices-network
+
+
 volumes:
  prometheus_data:
  grafana_data:
--- a/infra/observability/loki/loki-config.yml
+++ b/infra/observability/loki/loki-config.yml
@@ -32,9 +32,9 @@ ruler:
 limits_config:
  reject_old_samples: true
  reject_old_samples_max_age: 168h
+  allow_structured_metadata: false
+

-chunk_store_config:
-  max_look_back_period: 0s

 table_manager:
  retention_deletes_enabled: false
--- a/infra/observability/promtail/promtail-config.yml
+++ b/infra/observability/promtail/promtail-config.yml
@@ -0,0 +1,19 @@
+server:
+  http_listen_port: 9080
+  grpc_listen_port: 0
+
+positions:
+  filename: /tmp/positions.yaml
+
+clients:
+  - url: http://loki:3100/loki/api/v1/push
+
+scrape_configs:
+  - job_name: docker
+    docker_sd_configs:
+      - host: unix:///var/run/docker.sock
+        refresh_interval: 5s
+    relabel_configs:
+      - source_labels: ['__meta_docker_container_name']
+        regex: '/(.*)'
+        target_label: 'container'
--- a/scripts/observability/logs.sh
+++ b/scripts/observability/logs.sh
@@ -0,0 +1,11 @@
+#!/bin/bash
+# EN: View observability stack logs
+# VI: Xem log của observability stack
+
+set -e
+
+# Source OS helper
+source "$(dirname "$0")/../utils/os-helper.sh"
+
+cd infra/observability
+run_compose logs -f
--- a/scripts/observability/start.sh
+++ b/scripts/observability/start.sh
@@ -0,0 +1,30 @@
+#!/bin/bash
+# EN: Start observability stack
+# VI: Khởi động observability stack
+
+set -e
+
+# Source OS helper
+source "$(dirname "$0")/../utils/os-helper.sh"
+
+echo "🚀 Starting Observability Stack..."
+
+# Check if network exists, create if not
+if ! docker network ls | grep -q "microservices-network"; then
+    echo "Creating network 'microservices-network'..."
+    docker network create microservices-network
+fi
+
+# Resolve project root (assuming script is in scripts/observability)
+PROJECT_ROOT="$(cd "$(dirname "$0")/../.." && pwd)"
+cd "$PROJECT_ROOT/infra/observability"
+
+run_compose up -d
+
+echo ""
+echo "✅ Observability stack started!"
+echo "---------------------------------------------------"
+echo "📊 Grafana:    http://localhost:3001 (admin/admin)"
+echo "📈 Prometheus: http://localhost:9090"
+echo "🪵 Loki:       http://localhost:3100"
+echo "---------------------------------------------------"
--- a/scripts/observability/stop.sh
+++ b/scripts/observability/stop.sh
@@ -0,0 +1,15 @@
+#!/bin/bash
+# EN: Stop observability stack
+# VI: Dừng observability stack
+
+set -e
+
+# Source OS helper
+source "$(dirname "$0")/../utils/os-helper.sh"
+
+echo "🛑 Stopping Observability Stack..."
+
+cd infra/observability
+run_compose down
+
+echo "✅ Observability stack stopped."