@digiforce-nc/logger

Package	@digiforce-nc/logger
Import	import { createLogger, createSystemLogger, requestLogger } from '@digiforce-nc/logger'

Tổng quan

@digiforce-nc/logger là thư viện logging tập trung của hệ thống Digiforce, xây dựng trên nền Winston. Package cung cấp:

• Logger factory - tạo logger instance với cấu hình linh hoạt.
• System logger - logger có sẵn context ứng dụng (app name, module).
• Request logger - Koa middleware ghi log request/response.
• Transport - hỗ trợ console, file, daily rotate file.
• Cấu hình qua biến môi trường - dễ dàng tuỳ chỉnh theo environment.

Standalone

@digiforce-nc/logger không phụ thuộc vào bất kỳ package core nào khác. Có thể sử dụng độc lập trong bất kỳ project Node.js nào.

---

Kiến trúc

---

API

createLogger(options)

Tạo Winston logger instance với cấu hình tuỳ chỉnh.

Option	Type	Mặc định	Mô tả
level	string	'info'	Log level tối thiểu.
transports	Transport[]	[console]	Danh sách transport.
format	Format	logfmt	Format output.
dirname	string	-	Thư mục chứa log file.
filename	string	-	Tên file log.

import { createLogger } from '@digiforce-nc/logger';

const logger = createLogger({
  level: 'debug',
  transports: ['console', 'file'],
  dirname: '/var/log/myapp',
  filename: 'app.log',
});

logger.info('Application started');
logger.error('Something went wrong', { code: 'ERR_001', detail: '...' });

createConsoleLogger()

Tạo logger chỉ output ra console - tiện cho development:

import { createConsoleLogger } from '@digiforce-nc/logger';

const logger = createConsoleLogger();
logger.info('Dev mode active');
logger.debug('Variable value:', { x: 42 });

createSystemLogger(options)

Tạo system logger với context ứng dụng (app name, module name). Đây là loại logger chính sử dụng trong các core module.

Option	Type	Mô tả
app	string	Tên ứng dụng - dùng trong log message và tên file.
module	string	Tên module - phân biệt nguồn log.
level	string	Log level. Mặc định đọc từ LOGGER_LEVEL.
transports	string | string[]	Transport. Mặc định đọc từ LOGGER_TRANSPORT.
format	string	Format. Mặc định đọc từ LOGGER_FORMAT.

import { createSystemLogger } from '@digiforce-nc/logger';

const logger = createSystemLogger({
  app: 'digiforce',
  module: 'auth',
});

logger.info('User signed in', { userId: 123, method: 'email' });
// Output: 2024-03-15 10:30:00 [digiforce:auth] info: User signed in userId=123 method=email

requestLogger(name, options)

Trả về Koa middleware ghi log cho mỗi HTTP request/response.

Option	Type	Mô tả
name	string	Tên logger (dùng cho file name).
skip	(ctx) => boolean	Hàm bỏ qua log cho một số request.
requestWhitelist	string[]	Các field request cần log.
responseWhitelist	string[]	Các field response cần log.

import { requestLogger } from '@digiforce-nc/logger';

app.use(requestLogger('api', {
  skip: (ctx) => ctx.path === '/api/health',
  requestWhitelist: ['method', 'url', 'headers.user-agent'],
  responseWhitelist: ['status', 'body.error'],
}));

Mỗi request sẽ được ghi log khi hoàn thành:

2024-03-15 10:30:01 [api] info: POST /api/users:create 201 45ms
2024-03-15 10:30:02 [api] warn: GET /api/posts:list 403 12ms
2024-03-15 10:30:05 [api] error: PUT /api/orders/99 500 230ms error="Internal Server Error"

Utility functions

Function	Mô tả
getLoggerLevel()	Đọc log level từ LOGGER_LEVEL env. Mặc định 'info'.
getLoggerFilePath(app)	Trả về đường dẫn thư mục log. Mặc định storage/logs/<app>. Đọc từ LOGGER_BASE_PATH.
getLoggerTransport()	Đọc transport config từ LOGGER_TRANSPORT env. Mặc định 'console'.
getLoggerFormat()	Đọc format config từ LOGGER_FORMAT env. Mặc định 'logfmt'.

---

SystemLogger

SystemLogger mở rộng Winston logger với context ứng dụng. Mỗi Application instance có một app.logger là SystemLogger.

Mỗi plugin nên tạo logger riêng với module name:

class MyPlugin extends Plugin {
  async load() {
    const logger = createSystemLogger({
      app: this.app.name,
      module: 'my-plugin',
    });

    logger.info('Plugin loaded');
    logger.debug('Config:', this.options);
  }
}

---

Transport types

Console

Output ra stdout/stderr với màu sắc (development).

const logger = createLogger({
  transports: ['console'],
});

File

Ghi log vào file cố định, tự động rotate khi đạt maxsize.

const logger = createLogger({
  transports: ['file'],
  dirname: 'storage/logs',
  filename: 'app.log',
});

Daily Rotate File

Tự động tạo file log mới mỗi ngày, xoá file cũ sau maxFiles ngày.

const logger = createLogger({
  transports: ['dailyRotateFile'],
  dirname: 'storage/logs',
  filename: 'app-%DATE%.log',
});

Option	Mặc định	Mô tả
datePattern	'YYYY-MM-DD'	Pattern ngày trong tên file
maxSize	'20m'	Kích thước tối đa mỗi file
maxFiles	'14d'	Giữ log trong 14 ngày

Production recommendation

Trong production, nên dùng dailyRotateFile kết hợp console:

LOGGER_TRANSPORT=console,dailyRotateFile

---

Log levels

Theo thứ tự ưu tiên giảm dần:

Level	Số	Dùng khi
error	0	Lỗi nghiêm trọng, ứng dụng không thể xử lý
warn	1	Cảnh báo - vẫn chạy được nhưng cần chú ý
info	2	Thông tin quan trọng - startup, shutdown, request summary
debug	3	Thông tin chi tiết - chỉ bật khi debug

Khi set level: 'warn', chỉ log error và warn được ghi.

Performance

Level debug có thể tạo rất nhiều output. Chỉ bật trong development hoặc khi debug issue cụ thể. Trong production, dùng info hoặc warn.

---

Biến môi trường

Biến	Mô tả	Giá trị hợp lệ	Mặc định
LOGGER_LEVEL	Log level tối thiểu	error, warn, info, debug	info
LOGGER_TRANSPORT	Transport types (phân cách bằng ,)	console, file, dailyRotateFile	console
LOGGER_FORMAT	Output format	logfmt, json, delimiter, console	logfmt
LOGGER_BASE_PATH	Thư mục gốc chứa log file	Đường dẫn tuyệt đối hoặc tương đối	storage/logs

Format types

Format	Mô tả	Ví dụ output
logfmt	Key-value pairs, dễ parse bằng tool	level=info msg="User created" userId=123 ts=2024-03-15T10:30:00Z
json	JSON structured, tốt cho log aggregator	{"level":"info","message":"User created","userId":123}
delimiter	Pipe-delimited	2024-03-15 10:30:00 | info | User created | userId=123
console	Human-friendly với màu sắc	[10:30:00] INFO: User created { userId: 123 }

Chọn format

• Development: console - dễ đọc với highlight màu.
• Production: json hoặc logfmt - dễ parse bằng ELK/Grafana/Datadog.

---

Ví dụ tổng hợp

Tạo logger cho application

import {
  createSystemLogger,
  createLogger,
  requestLogger,
  getLoggerLevel,
  getLoggerTransport,
  getLoggerFilePath,
} from '@digiforce-nc/logger';

// 1. System logger cho app core
const appLogger = createSystemLogger({
  app: 'digiforce',
  module: 'core',
});

appLogger.info('Application initializing...');

// 2. Custom logger cho module cụ thể
const emailLogger = createLogger({
  level: 'debug',
  transports: ['file', 'console'],
  dirname: getLoggerFilePath('digiforce'),
  filename: 'email.log',
});

emailLogger.info('Sending email', { to: 'user@example.com', template: 'welcome' });
emailLogger.error('Email send failed', { error: err.message, stack: err.stack });

// 3. Request logging middleware
app.use(requestLogger('http', {
  skip: (ctx) => ctx.path.startsWith('/health'),
}));

Cấu hình theo environment

# Development
LOGGER_LEVEL=debug
LOGGER_TRANSPORT=console
LOGGER_FORMAT=console

# Staging
LOGGER_LEVEL=info
LOGGER_TRANSPORT=console,dailyRotateFile
LOGGER_FORMAT=logfmt
LOGGER_BASE_PATH=/var/log/digiforce

# Production
LOGGER_LEVEL=warn
LOGGER_TRANSPORT=dailyRotateFile
LOGGER_FORMAT=json
LOGGER_BASE_PATH=/var/log/digiforce

Custom transport

import { createLogger } from '@digiforce-nc/logger';
import winston from 'winston';

const logger = createLogger({
  level: 'info',
  transports: [
    new winston.transports.Console(),
    new winston.transports.Http({
      host: 'log-collector.internal',
      port: 8080,
      path: '/logs',
    }),
  ],
});

---

Phụ thuộc

@digiforce-nc/logger là package standalone - không phụ thuộc vào bất kỳ package core nào khác.

Dependencies ngoài:

Package	Vai trò
winston	Logger engine
winston-daily-rotate-file	Daily rotate file transport

---

Đọc thêm

• Server Application - cách app.logger được khởi tạo và cấu hình.
• FAQ - troubleshooting logging issues.
• Mã nguồn