@quyenpv/log-agent

Agent đẩy log của 1 server MIDA (app chạy PM2, không Docker) lên Loki trung tâm. Bọc Grafana Alloy chạy trong Docker — cài 1 lệnh, không cần cấu hình Alloy thủ công.

PM2 logs (~/.pm2/logs/*-out.log, JSON từ @quyenpv/logger)
   └─▶ Alloy (do agent này dựng, trong Docker) ──push──▶ Loki trung tâm ──▶ Grafana
       parse JSON, gắn nhãn service/level/env/shard/instance/host, traceId/domain=structured metadata

App không đổi gì: @quyenpv/logger ghi JSON ra stdout, PM2 lưu vào *-out.log. Agent chỉ đọc file đó.

Cài & chạy trên mỗi server

npm i -g @quyenpv/log-agent

LOKI_URL=http://<central-host>:3100/loki/api/v1/push \
HOST_LABEL=api-prod-01 \
quyenpv-log-agent up

Xong. Một lệnh / server. Các lệnh khác:

quyenpv-log-agent status   # trạng thái
quyenpv-log-agent logs     # theo dõi log agent
quyenpv-log-agent render   # xem config + compose sẽ dùng (dry-run, không cần docker)
quyenpv-log-agent down     # gỡ

| Env / flag | Mặc định | Ý nghĩa | |---|---|---| | LOKI_URL / --loki-url | (bắt buộc) | endpoint push của Loki trung tâm | | PM2_LOGS / --pm2-logs | ~/.pm2/logs | thư mục log PM2 của user chạy app | | HOST_LABEL / --host | hostname máy | nhãn host trong Loki (biết log của server nào) | | ALLOY_IMAGE / --image | grafana/alloy:v1.5.1 | image Alloy |

PM2 phải KHÔNG prefix timestamp (ecosystem time: false — mặc định đã vậy) để dòng log giữ nguyên JSON.

Vì sao đóng gói kiểu này? (so sánh các cách)

| Cách | Ưu | Nhược | Kết luận | |---|---|---|---| | npm CLI bọc Alloy-Docker (gói này) | hợp workflow npm; version đi cùng @quyenpv/logger; 1 lệnh/server; isolate; pin version | cần Docker trên server | Chọn — server MIDA đã có Docker (chạy mongo/redis/rabbitmq) | | Copy thư mục compose | đơn giản, minh bạch | đồng bộ/nâng cấp thủ công từng server | dùng được, kém tiện version | | Alloy host binary + systemd | không cần Docker | phải tải & quản lý binary, cập nhật thủ công | chỉ khi server không có Docker | | Push thẳng từ app (pino-loki) | không cần agent | tăng tải app, mất buffer khi Loki sập, mỗi service tự lo | không nên ở prod volume lớn |

→ Tách shipping ra khỏi app: app chỉ ghi stdout (bền, đơn giản), agent lo vận chuyển + buffer + retry. @quyenpv/logger (chuẩn hoá + traceId) và @quyenpv/log-agent (vận chuyển) là 2 lớp bổ trợ.

Server không có Docker? (systemd)

quyenpv-log-agent render in ra config.alloy. Cài Alloy binary, đặt config vào /etc/alloy/, set env LOKI_URL/HOST_LABEL, đổi __path__ thành ~/.pm2/logs/*.log thật (không phải /pm2-logs), rồi chạy bằng systemd. (Docker tiện hơn nên ưu tiên cách trên.)

Loki trung tâm

Triển khai 1 lần ở 1 server: Loki + Grafana (xem quyenpv-logger/observability/).