Nhật ký nghiệp vụ & trace

Ghi log nghiệp vụ và audit cho service: annotation @SysLog để ghi bản ghi audit vào bảng sys_log, @Trace để lan truyền trace id qua request, kèm aspect ghi log request/response controller và API publish audit thủ công. Dùng khi cần truy vết "ai đã làm gì, vào lúc nào, trên đối tượng nào".

Khi nào sử dụng

• Cần audit thao tác nghiệp vụ (actor, target, thời gian, kết quả) phục vụ tra cứu về sau.
• Cần trace request xuyên service bằng trace id thống nhất trong MDC.
• Cần ghi log tự động toàn bộ request vào controller mà không sửa code từng endpoint.
• Cần lưu lịch sử thao tác của một số luồng đặc biệt bằng publish thủ công.

Cài đặt

Thêm dependency vào pom.xml (không cần khai version vì đã được quản lý qua BOM):

<dependency>
    <groupId>vn.govex.cloud</groupId>
    <artifactId>govex-cloud-log</artifactId>
</dependency>

Version do BOM vn.govex.cloud:dependencies quản lý — xem Cài đặt.

Cấu hình

Property	Mô tả	Mặc định
govex.log.enabled	Bật aspect ghi log (@SysLog, log request/response controller). Khi tắt, annotation không có tác dụng.	false
govex.log.save-log	Lưu bản ghi audit vào database (bảng sys_log) qua sự kiện bất đồng bộ.	false
govex.trace.enabled	Bật TracingFilter và TraceAspect. Điều kiện auto-config dùng matchIfMissing nên tracing bật mặc định; đặt false để tắt.	bật
govex.app-code	Mã ứng dụng gắn vào bản ghi audit.	—

Mức log và dữ liệu ghi nhận chi tiết cấu hình trực tiếp trên annotation @SysLog: logLevel (mặc định DEBUG), showArgs (mặc định false), showResponse (mặc định true), type và content.

Sử dụng

Bước 1 — bật ghi log/audit và tracing:

govex:
  app-code: customer-service
  log:
    enabled: true
    save-log: true
  trace:
    enabled: true

Bước 2 — ghi audit theo EventType chuẩn (nội dung hỗ trợ SpEL). Target của bản ghi do code nghiệp vụ cung cấp qua SysLogContext:

@SysLog(type = EventType.UPDATE_USER, content = "Cập nhật người dùng #id")
public void updateUser(String id, UserUpdateParam param) {
    SysLogContext.setTargetList(List.of(
            Target.builder().type(TargetType.USER).id(id).build()));
    try {
        // ...
    } finally {
        SysLogContext.clear();
    }
}

Bước 3 — publish audit thủ công khi không dùng annotation (ví dụ sự kiện đăng nhập):

sysLogPublisher.publish(EventType.LOGIN_CONSOLE, "Đăng nhập Console",
        Actor.builder().username(username).build(), EventStatus.SUCCESS);

Bước 4 — đánh dấu method cần trace và đọc trace id trong code:

@Trace
public void handleCallback(String payload) {
    String traceId = TraceUtils.get();
    // ...
}

Lưu ý

• Muốn lưu audit vào database (govex.log.save-log=true) cần govex-cloud-data-jpa trên classpath và bảng sys_log đã tồn tại; changelog có sẵn tại db/changelog/log/changelog-master.yaml.
• Listener lưu log chạy bất đồng bộ (@Async), ứng dụng cần bật async thì bản ghi mới được ghi xuống database.
• Trace id nhận từ header X-Request-ID hoặc tham số requestId, nếu không có thì tự sinh; header response trả về requestId.
• Ba property govex.log.level, govex.log.show-args, govex.log.show-response tồn tại trong cấu hình chung nhưng không điều khiển hành vi ghi log; hãy cấu hình bằng thuộc tính annotation @SysLog tương ứng.
• Annotation hoạt động qua AOP proxy: gọi method có annotation từ method khác trong cùng class sẽ không kích hoạt aspect.
• Aspect ghi log cần bean UserAgentParser từ govex-cloud-web; dùng SysLogContext.clear() sau khi xử lý xong để tránh rò rỉ ngữ cảnh giữa các request.