Ở bài trước, lỗi gửi mail chỉ được in ra bằng console.error, còn morgan (Bài 6) ghi mỗi request thành một dòng chữ. Tiếp tục với series, bài này mình sẽ giới thiệu với mọi người về logging và cấu hình trong Express.
1. Log có cấu trúc với pino.
Log dạng chữ khó lọc kiểu "mọi lỗi 500 của bài số 3". Log có cấu trúc (structured log) ghi mỗi dòng là một object JSON gồm mức log, thời gian, câu thông báo và các trường riêng, công cụ quản lý log tìm được theo từng trường.
Mình dùng pino (10.4.0), pino-http (11.0.0) thay morgan ghi log request và pino-pretty (13.2.0, chỉ dùng khi phát triển):
npm install pino pino-http
npm install -D pino-pretty
npm uninstall morgan
Mỗi dòng log có một mức log (level), trong JSON là số: fatal (60), error (50), warn (40, VD: 404), info (30, VD: request xong), debug (20), trace (10). Logger đặt mức nào thì chỉ ghi từ mức đó trở lên, silent là tắt hẳn. Đây là ví dụ của cấu hình theo môi trường: khi phát triển cần debug, production chỉ cần info.
2. Kiểm tra biến môi trường khi khởi động.
Thiếu APP_URL thì server vẫn chạy, link trong mail thành undefined/posts/.... Tốt hơn là kiểm tra tất cả khi khởi động, sai thì báo rồi dừng luôn:
// Kiểm tra biến môi trường khi khởi động, sai thì dừng server ngay
const env = process.env;
const REQUIRED = [
'DB_HOST', 'DB_PORT', 'DB_USER', 'DB_NAME', 'SESSION_SECRET', 'JWT_SECRET',
'APP_URL', 'SMTP_HOST', 'SMTP_PORT', 'MAIL_FROM',
];
// Mức log mặc định theo môi trường
const DEFAULT_LOG_LEVELS = { development: 'debug', production: 'info', test: 'silent' };
const errors = [];
for (const name of REQUIRED) {
if (!env[name]) {
errors.push(`${name} chưa có giá trị`);
}
}
for (const name of ['PORT', 'DB_PORT', 'SMTP_PORT']) {
const port = Number(env[name]);
if (env[name] && !(Number.isInteger(port) && port > 0 && port < 65536)) {
errors.push(`${name} phải là số cổng từ 1 đến 65535`);
}
}
for (const name of ['SESSION_SECRET', 'JWT_SECRET']) {
if (env[name] && (env[name].length < 32 || env[name].startsWith('thay-bang'))) {
errors.push(`${name} phải là chuỗi ngẫu nhiên ít nhất 32 ký tự`);
}
}
if (env.APP_URL && !['http:', 'https:'].includes(URL.parse(env.APP_URL)?.protocol)) {
errors.push('APP_URL phải là URL đầy đủ, VD: http://localhost:3000');
}
if (env.NODE_ENV && !Object.hasOwn(DEFAULT_LOG_LEVELS, env.NODE_ENV)) {
errors.push('NODE_ENV chỉ nhận development, production hoặc test');
}
if (env.LOG_LEVEL && !['fatal', 'error', 'warn', 'info', 'debug', 'trace', 'silent'].includes(env.LOG_LEVEL)) {
errors.push('LOG_LEVEL không hợp lệ');
}
if (errors.length > 0) {
throw new Error(`Biến môi trường không hợp lệ:\n- ${errors.join('\n- ')}`);
}
export const nodeEnv = env.NODE_ENV || 'development';
export const logLevel = env.LOG_LEVEL || DEFAULT_LOG_LEVELS[nodeEnv];
Trong đó:
DB_PASSWORD,SMTP_USER,SMTP_PASS,CORS_ORIGINđược để trống nên không nằm trongREQUIRED.NODE_ENVmặc định làdevelopment(như Bài 7), quyết định mức log mặc định;LOG_LEVELcó giá trị thì được ưu tiên.
ESM chạy module theo thứ tự import, nên các bạn thêm vào dòng đầu tiên của app.js:
import './lib/env.js'; // import đầu tiên: kiểm tra biến môi trường trước mọi module khác
Đoạn if (!SECRET || ...) { throw ... } trong middlewares/session.js và lib/jwt.js đã chuyển vào lib/env.js, các bạn xoá đi. Thêm vào cuối .env và .env.example:
# Mức log: fatal, error, warn, info, debug, trace, silent (để trống: theo NODE_ENV)
LOG_LEVEL=
VD: .env có SMTP_HOST=, JWT_SECRET=abc và APP_URL=localhost:3000 (thiếu http://):
npm run start
# Error: Biến môi trường không hợp lệ:
# - SMTP_HOST chưa có giá trị
# - JWT_SECRET phải là chuỗi ngẫu nhiên ít nhất 32 ký tự
# - APP_URL phải là URL đầy đủ, VD: http://localhost:3000
# ... (stack trace, server dừng)
3. Tạo logger dùng chung.
import pino from 'pino';
import { logLevel } from './env.js';
// Logger dùng chung cho cả ứng dụng, mỗi dòng log là một object JSON
const logger = pino({
level: logLevel,
// Không bao giờ ghi token, cookie, mật khẩu vào log
redact: [
'req.headers.authorization',
'req.headers.cookie',
'password',
'*.password',
],
});
export default logger;
redact là đường dẫn tới các trường bí mật, giá trị bị thay bằng [Redacted]. *.password là trường password trong object con cấp 1.
Cú pháp là logger.info(object, message), object có thể bỏ. Mình thay console.log trong server.js bằng logger.info(`MiniBlog đang chạy tại http://localhost:${port}`) (thêm import logger from './lib/logger.js';), và console.error ở bài trước bằng logger.error:
- services/comment-service.js (đoạn thay đổi)
import logger from '../lib/logger.js';
export async function addComment(post, { name, content }) {
await Comment.create({ postId: post.id, name, content });
notifyAuthor(post, { name, content }).catch((err) => {
logger.error({ err, postId: post.id }, 'Không gửi được mail bình luận mới');
});
}
async function notifyAuthor(post, comment) {
const author = post.author_id ? await getUser(post.author_id) : null;
if (author) {
await sendNewCommentMail({ author, post, comment });
logger.debug({ postId: post.id }, 'Đã gửi mail bình luận mới');
}
}
Lỗi đặt ở trường err thì pino ghi cả message và stack trace. Chạy server rồi bình luận một bài có tác giả:
npm run start
# {"level":30,"time":1794731198362,"pid":316,"hostname":"41a118c38061","msg":"MiniBlog đang chạy tại http://localhost:3000"}
# ...
# {"level":20,"time":1794731199214,"pid":316,"hostname":"41a118c38061","postId":3,"msg":"Đã gửi mail bình luận mới"}
4. Log request với pino-http.
Trong app.js, import morgan thay bằng hai dòng import dưới đây, app.use(morgan('dev')) thay bằng phần còn lại:
- app.js (đoạn thay đổi)
import { pinoHttp } from 'pino-http';
import logger from './lib/logger.js';
// Ghi log mọi request bằng pino, đặt trước các router
const requestMessage = (req, res) => `${req.method} ${req.originalUrl} ${res.statusCode}`;
app.use(pinoHttp({
logger,
customSuccessMessage: requestMessage,
customErrorMessage: requestMessage,
// Response chỉ ghi status code, bỏ các header helmet cho log ngắn gọn
serializers: { res: (res) => ({ statusCode: res.statusCode }) },
// 5xx ghi mức error, 4xx mức warn, còn lại mức info
customLogLevel: (req, res, err) => {
if (err || res.statusCode >= 500) {
return 'error';
}
return res.statusCode >= 400 ? 'warn' : 'info';
},
}));
Trong đó:
- Mỗi request ghi một dòng gồm
req(id, method, url, header...),res,responseTime(ms). Headerauthorization,cookiebị ẩn nhờredact. - pino-http không ghi body. Đừng tự ghi
req.bodyvào log (form đăng nhập có mật khẩu),*.passwordchỉ là lớp chặn cuối.
Error handler bỏ console.error(err), gán lỗi vào res.err để pino-http ghi kèm vào dòng log của request:
- middlewares/error-handler.js (đoạn thay đổi)
// Lỗi phía server: pino-http ghi lỗi kèm stack vào dòng log của request
if (status >= 500) {
res.err = err;
}
5. Đọc log khi phát triển với pino-pretty.
Khi phát triển, script dev trong package.json cho log đi qua pino-pretty bằng dấu |, bỏ bớt pid, hostname, req, res:
"dev": "node --watch --env-file=.env server.js | pino-pretty --ignore pid,hostname,req,res"
Chạy npm run dev, mở vài trang, tắt Mailpit (docker stop miniblog-mailpit) rồi bình luận (rút gọn):
# [08:27:49.837] INFO: MiniBlog đang chạy tại http://localhost:3000
# [08:27:50.216] INFO: GET / 200
# responseTime: 35
# [08:27:50.266] WARN: GET /khong-co 404
# responseTime: 4
# [08:27:50.788] ERROR: Không gửi được mail bình luận mới
# postId: 3
# err: {
# "message": "connect ECONNREFUSED 127.0.0.1:1025",
# ...
# }
Script start vẫn ghi JSON. NODE_ENV không ghi vào .env mà đặt khi chạy, biến đặt sẵn như vậy được ưu tiên hơn giá trị trong file --env-file:
# Production: mức info, không còn dòng debug (thêm LOG_LEVEL=warn để chỉ ghi từ warn)
NODE_ENV=production npm run start
Lúc này tắt MySQL (docker stop miniblog-mysql) rồi gọi /api/v1/posts: người dùng chỉ nhận "Đã có lỗi xảy ra, vui lòng thử lại sau", còn log có dòng "level":50 kèm err đầy đủ message và stack.
Cookie session ở production có secure (Bài 15) nên ở local không đăng nhập được. Thử xong các bạn chạy docker start miniblog-mysql miniblog-mailpit, npm run db:seed để xoá dữ liệu thử rồi quay lại npm run dev.
Code đầy đủ của MiniBlog sau bài này nằm ở tag bai-23 trên GitHub; các thay đổi của riêng bài này: so sánh bai-22...bai-23.
6. Lời kết.
Như vậy là chúng ta đã xong logging và cấu hình trong Express: log JSON bằng pino và pino-http, mức log theo môi trường, ẩn dữ liệu bí mật và kiểm tra biến môi trường khi khởi động. Bài sau (dùng NODE_ENV=test để tắt log) mình sẽ giới thiệu với mọi người về testing ứng dụng Express.
Đăng ký nhận tin.
Chúng tôi chỉ gửi tối đa 2 lần trên 1 tháng. Tuyên bố không spam mail!





0 Comments