Cài đặt và sử dụng — Logger

Tổng quan

Plugin Logger cung cấp giao diện quản trị (Admin UI) để xem danh sách, tìm kiếm, và tải về file log từ server — không cần SSH trực tiếp vào máy chủ. Plugin đọc file .log từ filesystem và đóng gói thành logs.tar.gz để download.

Bước 1: Kích hoạt Plugin

Plugin Logger thường được bật sẵn khi cài đặt Digiforce. Kiểm tra trong Settings → Plugin Manager và đảm bảo plugin-logger đang ở trạng thái Enabled.

Nếu chưa bật, kích hoạt và khởi động lại server.

Bước 2: Truy cập giao diện Logger

Sau khi plugin được kích hoạt, vào Settings → Logger trong giao diện quản trị. Giao diện hiển thị:

Cây thư mục (Tree view): Danh sách tất cả file .log trên server, có hỗ trợ thư mục lồng nhau
Ô tìm kiếm: Lọc file theo tên
Checkbox: Chọn file cần tải về
Nút Download: Tải file đã chọn dưới dạng logs.tar.gz

Các loại file log

File log	Mô tả
`request_*.log`	Log request và response của API
`system_*.log`	Log hệ thống: ứng dụng, database, plugin
`system_error_*.log`	Log lỗi hệ thống (tách riêng từ system log)
`sql_*.log`	Log câu lệnh SQL (khi `DB_LOGGING` được bật)

Bước 3: Tải về file log

Mở Settings → Logger
Duyệt cây thư mục và tick chọn file cần tải
Nhấn Download (.tar.gz)
Trình duyệt sẽ tải về file logs.tar.gz

Giải nén trên máy local:

bash

tar -xzf logs.tar.gz

Cấu hình biến môi trường

Plugin Logger đọc cấu hình từ hệ thống logger core (@digiforce-nc/logger). Các biến môi trường quan trọng:

Biến môi trường	Giá trị mặc định	Mô tả
`LOGGER_LEVEL`	`info`	Mức log: `error`, `warn`, `info`, `debug`
`LOGGER_TRANSPORT`	`console,file`	Nơi ghi log (console, file, hoặc cả hai)
`LOGGER_BASE_PATH`	`./storage/logs`	Thư mục lưu file log

Mức log (Log Level)

Mức	Khi nào dùng	Lượng log
`error`	Chỉ ghi lỗi nghiêm trọng	Ít nhất
`warn`	Ghi cảnh báo và lỗi	Ít
`info`	Thông tin hoạt động bình thường (khuyến nghị cho production)	Vừa phải
`debug`	Thông tin chi tiết cho gỡ lỗi	Rất nhiều

Cảnh báo

Mức debug tạo rất nhiều log và ảnh hưởng hiệu năng. Chỉ sử dụng khi cần gỡ lỗi, sau đó chuyển lại info hoặc warn.

API Endpoints

Plugin đăng ký ba API endpoints:

Endpoint	Method	Mô tả	Body
`logger:list`	GET	Liệt kê danh sách file log (dạng tree)	—
`logger:download`	POST	Download file đã chọn → `logs.tar.gz`	`{ files: ["request.log", "sql.log"] }`
`logger:collect`	POST	Thu thập diagnostic từ frontend, trả về log gần nhất	`{ error: {...}, ... }`

Bảo mật API

Tất cả endpoints được bảo vệ bởi ACL snippet pm.logger
Chỉ người dùng có quyền admin mới truy cập được
Kiểm tra path traversal: không cho phép truy cập file ngoài thư mục log
Chỉ cho phép file có extension .log

Tính năng Diagnostic Collect

Khi gặp lỗi trên frontend, hệ thống có thể tự động:

Gửi thông tin lỗi frontend lên server qua logger:collect
Server ghi thông tin diagnostic (lỗi, biến môi trường) vào log
Server tìm các file log mới nhất (request, sql, system, system_error)
Đóng gói và trả về cho admin dưới dạng logs.tar.gz

Lưu ý khi vận hành

Log file tự động rotate theo cấu hình của @digiforce-nc/logger (kích thước và thời gian)
Không có database: Plugin đọc trực tiếp từ filesystem, không tạo bảng nào
Dung lượng ổ đĩa: Theo dõi dung lượng thư mục log, đặc biệt khi bật DB_LOGGING (SQL log rất lớn)
Production: Khuyến nghị dùng mức info hoặc warn, kết hợp với hệ thống log tập trung (ELK, Datadog, Loki)