Giới thiệu

Logging là một phần thiết yếu trong bất kỳ ứng dụng hiện đại nào. Log tốt không chỉ giúp các nhà phát triển dễ dàng gỡ lỗi mà còn hỗ trợ nhóm vận hành theo dõi và phân tích khi có sự cố xảy ra. Tuy nhiên, nhiều ứng dụng hiện nay thường viết log một cách ngẫu nhiên: không nhất quán, khó phân tích, hoặc chứa quá nhiều thông tin không cần thiết.

Bài viết này sẽ cung cấp cho bạn những cách thức để tạo ra log ứng dụng thực tế, ngắn gọn và nhất quán.

Mục Lục

• 1. Phân Biệt Cấp Độ Log Đúng Cách
• 2. Sử Dụng Định Dạng Có Cấu Trúc
• 3. Các Trường Thông Tin Cần Thiết
• 4. Thêm Ngữ Cảnh Với Các Trường Tùy Chọn
• 5. Tránh Logging Dữ Liệu Nhạy Cảm
• 6. Quản Lý Log Hiệu Quả
• 7. Thực Hành Tốt Nhất
• 8. Các Cạm Bẫy Thường Gặp
• 9. Mẹo Tối Ưu Hiệu Suất
• 10. Giải Quyết Sự Cố
• 11. Kết Luận

1. Phân Biệt Cấp Độ Log Đúng Cách

Một trong những lỗi phổ biến là không phân loại đúng cấp độ log. Không phải mọi trường hợp thất bại đều là lỗi ứng dụng.

• DEBUG → thông tin chi tiết cho nhà phát triển.
• INFO → sự kiện bình thường, bao gồm cả việc xác thực thất bại hoặc người dùng nhập sai dữ liệu.
• WARN → vấn đề tiềm ẩn, ví dụ như yêu cầu phản hồi chậm hoặc phụ thuộc vào dịch vụ gặp vấn đề.
• ERROR → lỗi thực sự của ứng dụng, chẳng hạn như ngoại lệ, dịch vụ phụ thuộc bị ngắt, hoặc truy vấn cơ sở dữ liệu thất bại.

👉 Ví dụ: Nếu người dùng nhập sai định dạng email → log như là INFO, không phải ERROR.

2. Sử Dụng Định Dạng Có Cấu Trúc

Định dạng log tự do như sau:

[INFO] Đăng nhập thất bại cho người dùng

Khó khăn trong việc xử lý tự động. Hãy sử dụng định dạng JSON hoặc key-value nhất quán.

{
  "timestamp": "2025-09-16T16:45:01.123Z",
  "level": "INFO",
  "request_id": "req-12345",
  "endpoint": "/auth/register",
  "message": "Xác thực thất bại",
  "extra": {
    "field": "email",
    "value": "user@@domain"
  }
}

3. Các Trường Thông Tin Cần Thiết

Để log có thể dễ dàng tìm kiếm và phân tích, hãy sử dụng các trường tiêu chuẩn sau:

• timestamp → thời gian log được tạo (định dạng ISO 8601, UTC).
• level → DEBUG | INFO | WARN | ERROR.
• request_id → ID duy nhất để theo dõi một yêu cầu từ đầu đến cuối.
• endpoint → API/path đã được truy cập.
• message → tóm tắt ngắn gọn về sự kiện.

4. Thêm Ngữ Cảnh Với Các Trường Tùy Chọn

Không phải mọi yêu cầu đều cần thêm chi tiết, nhưng log có thể hữu ích hơn khi có ngữ cảnh:

• extra → thông tin bổ sung liên quan đến sự kiện. Có thể là một đối tượng linh hoạt, ví dụ như order_id, amount, hoặc latency.

Ví dụ:

{
  "timestamp": "2025-09-16T16:50:20.789Z",
  "level": "WARN",
  "request_id": "req-56789",
  "endpoint": "/payment/process",
  "message": "Yêu cầu chậm",
  "extra": {
    "latency_ms": 2200,
    "threshold_ms": 2000
  }
}

5. Tránh Logging Dữ Liệu Nhạy Cảm

Một nguyên tắc quan trọng nhưng cổ điển: không bao giờ log mật khẩu, token hoặc dữ liệu cá nhân nhạy cảm. Nếu cần, hãy sử dụng masking hoặc hashing.

6. Quản Lý Log Hiệu Quả

Log có thể tăng nhanh chóng. Hãy áp dụng:

• Log rotation → ví dụ qua logrotate.
• Retention policy → lưu trữ log theo nhu cầu kinh doanh/quy định.
• Aggregator → sử dụng ELK, Loki hoặc dịch vụ logging đám mây để tìm kiếm lâu dài.

7. Thực Hành Tốt Nhất

• Sử dụng cấp độ log chính xác → chỉ sử dụng ERROR cho các vấn đề thực sự của ứng dụng, không cho đầu vào của người dùng.
• Log trong định dạng có cấu trúc (JSON).
• Các trường tối thiểu: timestamp, level, request_id, endpoint, message.
• Sử dụng extra chỉ khi cần thiết.
• Mã lỗi chỉ nên có trong phản hồi API, không cần lặp lại trong log.

8. Các Cạm Bẫy Thường Gặp

• Log quá nhiều thông tin: Chỉ nên log những gì thật sự cần thiết để tránh làm rối loạn dữ liệu.
• Không xác định cấp độ log: Đảm bảo mọi log được phân loại chính xác để dễ dàng theo dõi và xử lý.

9. Mẹo Tối Ưu Hiệu Suất

• Sử dụng bộ nhớ đệm cho các log thường xuyên được truy cập.
• Giảm thiểu kích thước log bằng cách chỉ ghi lại thông tin cần thiết.

10. Giải Quyết Sự Cố

Nếu log không hoạt động như mong muốn:

• Kiểm tra cấu hình logging.
• Đảm bảo rằng các thư viện logging đang được sử dụng là phiên bản mới nhất.

11. Kết Luận

Logging không chỉ đơn thuần là việc sử dụng console.log(), mà là một phần thiết yếu của kiến trúc ứng dụng khỏe mạnh. Những nguyên tắc cơ bản:

• Sử dụng cấp độ log đúng → chỉ dùng cho lỗi ứng dụng, không cho lỗi nhập liệu của người dùng.
• Log trong định dạng có cấu trúc (JSON).
• Các trường tối thiểu cần có: timestamp, level, request_id, endpoint, message.
• Sử dụng extra chỉ khi thực sự cần thiết.
• Mã lỗi chỉ cần có trong phản hồi API, không cần lặp lại trong log.

Với cách tiếp cận này, log ứng dụng của bạn sẽ:

• Ngắn gọn, không thừa thãi.
• Nhất quán, dễ tìm kiếm.
• Hữu ích cho việc gỡ lỗi và theo dõi.