audit-logging

Audit Logging Conventions

Context

• Apply when implementing significant business operations within service classes (src/main/java/**/service/**/*.java) that require an audit trail.
• This application uses a dedicated AuditLogger utility to ensure consistent, structured logging of important events for security and compliance.
• Audit logs are separate from regular application/debug logs.
• For comprehensive security best practices, see [security.mdc](mdc:rules/common/security.mdc).

Standard Log Structure

Using the AuditLogger utility ensures logs are generated in the following standard JSON format. Developers do not construct this JSON manually.

{
  "correlationId": "550e8400-e29b-41d4-a716-446655440000",
  "time": "2023-04-04T12:34:56.123456Z",
  "application": {
    "name": "bookstore-service",
    "extraInfo": {
      "environment": "dev"
    }
  },
  "activity": {
    "action": "BOOK_UPDATED", // Example action
    "extraInfo": { // Action-specific details
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "oldTitle": "The Old Title",
      "newTitle": "The New Title"
      // ... other relevant fields ...
    }
  },
  "actor": {
    "name": "system" // Or user identifier
  },
  "client": {
    "id": "bookstore-app",
    "source": "INTERNAL"
  },
  "result": {
    "code": "SUCCESS",
    "message": "Operation completed successfully"
  }
}

Requirements

• Use AuditLogger: ALL audit log entries MUST be generated using the static methods provided by the AuditLogger utility class.
• Log Significant Business Events: Only log high-level, meaningful business operations (e.g., resource creation, update, deletion, key access), not low-level implementation details.
• Log After Success: Audit log entries for successful operations MUST be created after the core business logic (e.g., database commit) has completed successfully within the same transaction context.
• Do Not Log Sensitive Data: Avoid including sensitive personal information (e.g., passwords, detailed financial data, PII unless strictly necessary and compliant with regulations) in audit log messages or extraInfo fields. Redact or omit if necessary.
• Use Correct Methods: Use the appropriate AuditLogger method for the event type.
• Log All Authentication Attempts: ALL authentication attempts MUST be logged regardless of outcome (login, logout, failed authentication, session timeout).
• Log All User-Initiated Activities: ALL user-initiated activities MUST be logged (CRUD operations, searches, file uploads, exports).