MACRO NEPAL
Comprehensive Audit Logging with Spring AOP: A Non-Invasive Approach
awiskar acharya
November 5, 2025
2:17 pm

Audit logging is a critical requirement for enterprise applications, providing a trail of who did what, when, and how. While traditional logging focuses on debugging and monitoring, audit logging serves compliance, security, and business intelligence purposes. Spring AOP (Aspect-Oriented Programming) offers an elegant, non-invasive solution to implement cross-cutting audit logging concerns without cluttering your business logic.

This article explores how to implement robust audit logging using Spring AOP, creating maintainable, declarative audit trails across your application.

Why Spring AOP for Audit Logging?

Traditional Approach Problems:

  • Code Duplication: Audit logging calls scattered throughout business methods
  • Business Logic Pollution: Audit code mixed with core business logic
  • Maintenance Nightmare: Changing audit requirements affects many files
  • Inconsistency: Different developers implement audit logging differently

Spring AOP Advantages:

  • Separation of Concerns: Audit logging is modularized in one place
  • Non-Invasive: Business classes remain unaware of audit logging
  • Declarative: Configure what to audit using annotations or pointcuts
  • Reusable: Same aspect can be applied across multiple methods/classes

Core Concepts: AOP Terminology

  • Aspect: A modularization of a concern (audit logging)
  • Join Point: A point during method execution (method call)
  • Advice: Action taken by an aspect at a particular join point
  • Pointcut: Expression that matches join points
  • Annotation: Metadata to mark methods for auditing

Project Setup

Maven Dependencies:

<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-aop</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-data-jpa</artifactId>
</dependency>
<!-- For JSON logging -->
<dependency>
<groupId>ch.qos.logback</groupId>
<artifactId>logback-classic</artifactId>
</dependency>
<dependency>
<groupId>com.fasterxml.jackson.core</groupId>
<artifactId>jackson-databind</artifactId>
</dependency>
</dependencies>

Enable AOP in Spring Boot:

@SpringBootApplication
@EnableAspectJAutoProxy
public class AuditLoggingApplication {
public static void main(String[] args) {
SpringApplication.run(AuditLoggingApplication.class, args);
}
}

Custom Audit Annotation

First, create a custom annotation to mark methods that require audit logging:

package com.example.audit.annotation;
import java.lang.annotation.*;
@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface AuditLog {
/** Action description for the audit log */
String action();
/** Resource being acted upon */
String resource();
/** Level of detail for logging */
LogLevel level() default LogLevel.INFO;
/** Whether to log method parameters */
boolean logParameters() default true;
/** Whether to log return value */
boolean logResult() default false;
/** Whether to log execution time */
boolean logExecutionTime() default true;
enum LogLevel {
INFO, WARN, ERROR
}
}

Audit Event Entity

Create a JPA entity to store audit events in the database:

package com.example.audit.entity;
import javax.persistence.*;
import java.time.LocalDateTime;
@Entity
@Table(name = "audit_log")
public class AuditEvent {
@Id
@GeneratedValue(strategy = GenerationType.IDENTITY)
private Long id;
@Column(nullable = false)
private String action;
@Column(nullable = false)
private String resource;
private String description;
@Column(nullable = false)
private String username;
@Column(nullable = false)
private String userRole;
@Column(nullable = false)
private String methodName;
private String parameters;
private String returnValue;
private Long executionTime; // in milliseconds
@Column(nullable = false)
private String status; // SUCCESS, FAILURE
private String errorMessage;
@Column(nullable = false)
private String ipAddress;
@Column(nullable = false)
private LocalDateTime timestamp;
// Constructors
public AuditEvent() {
this.timestamp = LocalDateTime.now();
}
public AuditEvent(String action, String resource, String username) {
this();
this.action = action;
this.resource = resource;
this.username = username;
}
// Builder pattern for fluent creation
public static Builder builder(String action, String resource, String username) {
return new Builder(action, resource, username);
}
public static class Builder {
private final AuditEvent event;
public Builder(String action, String resource, String username) {
this.event = new AuditEvent(action, resource, username);
}
public Builder description(String description) {
event.setDescription(description);
return this;
}
public Builder methodName(String methodName) {
event.setMethodName(methodName);
return this;
}
public Builder parameters(String parameters) {
event.setParameters(parameters);
return this;
}
public Builder status(String status) {
event.setStatus(status);
return this;
}
public Builder executionTime(Long executionTime) {
event.setExecutionTime(executionTime);
return this;
}
public Builder ipAddress(String ipAddress) {
event.setIpAddress(ipAddress);
return this;
}
public AuditEvent build() {
return event;
}
}
// Getters and Setters
public Long getId() { return id; }
public void setId(Long id) { this.id = id; }
public String getAction() { return action; }
public void setAction(String action) { this.action = action; }
public String getResource() { return resource; }
public void setResource(String resource) { this.resource = resource; }
public String getDescription() { return description; }
public void setDescription(String description) { this.description = description; }
public String getUsername() { return username; }
public void setUsername(String username) { this.username = username; }
public String getUserRole() { return userRole; }
public void setUserRole(String userRole) { this.userRole = userRole; }
public String getMethodName() { return methodName; }
public void setMethodName(String methodName) { this.methodName = methodName; }
public String getParameters() { return parameters; }
public void setParameters(String parameters) { this.parameters = parameters; }
public String getReturnValue() { return returnValue; }
public void setReturnValue(String returnValue) { this.returnValue = returnValue; }
public Long getExecutionTime() { return executionTime; }
public void setExecutionTime(Long executionTime) { this.executionTime = executionTime; }
public String getStatus() { return status; }
public void setStatus(String status) { this.status = status; }
public String getErrorMessage() { return errorMessage; }
public void setErrorMessage(String errorMessage) { this.errorMessage = errorMessage; }
public String getIpAddress() { return ipAddress; }
public void setIpAddress(String ipAddress) { this.ipAddress = ipAddress; }
public LocalDateTime getTimestamp() { return timestamp; }
public void setTimestamp(LocalDateTime timestamp) { this.timestamp = timestamp; }
}

Audit Logging Aspect

The core component that implements the audit logging logic:

package com.example.audit.aspect;
import com.example.audit.annotation.AuditLog;
import com.example.audit.entity.AuditEvent;
import com.example.audit.repository.AuditRepository;
import com.fasterxml.jackson.databind.ObjectMapper;
import org.aspectj.lang.ProceedingJoinPoint;
import org.aspectj.lang.annotation.Around;
import org.aspectj.lang.annotation.Aspect;
import org.aspectj.lang.reflect.MethodSignature;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.security.core.Authentication;
import org.springframework.security.core.context.SecurityContextHolder;
import org.springframework.stereotype.Component;
import org.springframework.web.context.request.RequestContextHolder;
import org.springframework.web.context.request.ServletRequestAttributes;
import javax.servlet.http.HttpServletRequest;
import java.lang.reflect.Method;
import java.time.LocalDateTime;
import java.util.Arrays;
@Aspect
@Component
public class AuditLoggingAspect {
private static final Logger logger = LoggerFactory.getLogger(AuditLoggingAspect.class);
@Autowired
private AuditRepository auditRepository;
@Autowired
private ObjectMapper objectMapper;
@Around("@annotation(auditLog)")
public Object auditMethod(ProceedingJoinPoint joinPoint, AuditLog auditLog) throws Throwable {
long startTime = System.currentTimeMillis();
String status = "SUCCESS";
String errorMessage = null;
Object result = null;
// Extract method information
MethodSignature signature = (MethodSignature) joinPoint.getSignature();
Method method = signature.getMethod();
String methodName = method.getDeclaringClass().getSimpleName() + "." + method.getName();
try {
// Execute the target method
result = joinPoint.proceed();
return result;
} catch (Exception e) {
status = "FAILURE";
errorMessage = e.getMessage();
throw e;
} finally {
long executionTime = System.currentTimeMillis() - startTime;
logAuditEvent(joinPoint, auditLog, methodName, status, errorMessage, executionTime, result);
}
}
private void logAuditEvent(ProceedingJoinPoint joinPoint, AuditLog auditLog, 
String methodName, String status, String errorMessage,
long executionTime, Object result) {
try {
// Get current user from Spring Security
String username = "anonymous";
String userRole = "ROLE_ANONYMOUS";
Authentication authentication = SecurityContextHolder.getContext().getAuthentication();
if (authentication != null && authentication.isAuthenticated() && 
!"anonymousUser".equals(authentication.getPrincipal())) {
username = authentication.getName();
userRole = authentication.getAuthorities().stream()
.findFirst()
.map(Object::toString)
.orElse("ROLE_USER");
}
// Get client IP address
String ipAddress = getClientIpAddress();
// Build audit event
AuditEvent auditEvent = AuditEvent.builder(auditLog.action(), auditLog.resource(), username)
.methodName(methodName)
.userRole(userRole)
.status(status)
.executionTime(executionTime)
.ipAddress(ipAddress)
.description(buildDescription(joinPoint, auditLog, status))
.build();
// Add parameters if enabled
if (auditLog.logParameters()) {
String parameters = serializeParameters(joinPoint.getArgs());
auditEvent.setParameters(parameters);
}
// Add return value if enabled and successful
if (auditLog.logResult() && "SUCCESS".equals(status)) {
String returnValue = serializeReturnValue(result);
auditEvent.setReturnValue(returnValue);
}
// Add error message if failed
if ("FAILURE".equals(status)) {
auditEvent.setErrorMessage(errorMessage);
}
// Save to database
auditRepository.save(auditEvent);
// Also log to application logs
logToApplicationLogs(auditEvent, auditLog.level());
} catch (Exception e) {
logger.error("Failed to create audit log entry", e);
}
}
private String getClientIpAddress() {
try {
HttpServletRequest request = ((ServletRequestAttributes) RequestContextHolder
.currentRequestAttributes()).getRequest();
String xForwardedFor = request.getHeader("X-Forwarded-For");
if (xForwardedFor != null && !xForwardedFor.isEmpty()) {
return xForwardedFor.split(",")[0].trim();
}
return request.getRemoteAddr();
} catch (Exception e) {
return "unknown";
}
}
private String buildDescription(ProceedingJoinPoint joinPoint, AuditLog auditLog, String status) {
return String.format("Action: %s on Resource: %s - Status: %s", 
auditLog.action(), auditLog.resource(), status);
}
private String serializeParameters(Object[] args) {
try {
if (args == null || args.length == 0) {
return "[]";
}
// Avoid serializing large objects or sensitive data
Object[] safeArgs = Arrays.stream(args)
.map(this::sanitizeParameter)
.toArray();
return objectMapper.writeValueAsString(safeArgs);
} catch (Exception e) {
return "Failed to serialize parameters: " + e.getMessage();
}
}
private Object sanitizeParameter(Object param) {
if (param == null) {
return null;
}
// Implement sensitive data masking
String paramString = param.toString().toLowerCase();
if (paramString.contains("password") || paramString.contains("token") || 
paramString.contains("secret")) {
return "***MASKED***";
}
// For large objects, return only type information
if (param.toString().length() > 1000) {
return param.getClass().getSimpleName() + "[size=" + param.toString().length() + "]";
}
return param;
}
private String serializeReturnValue(Object result) {
try {
if (result == null) {
return "null";
}
// Avoid serializing large objects
if (result.toString().length() > 1000) {
return result.getClass().getSimpleName() + "[size=" + result.toString().length() + "]";
}
return objectMapper.writeValueAsString(result);
} catch (Exception e) {
return "Failed to serialize return value: " + e.getMessage();
}
}
private void logToApplicationLogs(AuditEvent auditEvent, AuditLog.LogLevel level) {
String logMessage = String.format(
"AUDIT - Action: %s, Resource: %s, User: %s, Status: %s, Time: %dms",
auditEvent.getAction(), auditEvent.getResource(), auditEvent.getUsername(),
auditEvent.getStatus(), auditEvent.getExecutionTime());
switch (level) {
case WARN:
logger.warn(logMessage);
break;
case ERROR:
logger.error(logMessage);
break;
case INFO:
default:
logger.info(logMessage);
}
}
}

Repository and Service Layer

Audit Repository:

package com.example.audit.repository;
import com.example.audit.entity.AuditEvent;
import org.springframework.data.jpa.repository.JpaRepository;
import org.springframework.data.jpa.repository.Query;
import org.springframework.stereotype.Repository;
import java.time.LocalDateTime;
import java.util.List;
@Repository
public interface AuditRepository extends JpaRepository<AuditEvent, Long> {
List<AuditEvent> findByUsernameOrderByTimestampDesc(String username);
List<AuditEvent> findByActionAndTimestampBetween(String action, LocalDateTime start, LocalDateTime end);
@Query("SELECT ae FROM AuditEvent ae WHERE ae.timestamp >= :since ORDER BY ae.timestamp DESC")
List<AuditEvent> findRecentAuditEvents(LocalDateTime since);
long countByStatus(String status);
}

Audit Service:

package com.example.audit.service;
import com.example.audit.entity.AuditEvent;
import com.example.audit.repository.AuditRepository;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Service;
import java.time.LocalDateTime;
import java.util.List;
@Service
public class AuditService {
@Autowired
private AuditRepository auditRepository;
public List<AuditEvent> getUserAuditTrail(String username) {
return auditRepository.findByUsernameOrderByTimestampDesc(username);
}
public List<AuditEvent> getAuditEventsSince(LocalDateTime since) {
return auditRepository.findRecentAuditEvents(since);
}
public long getFailedAuditCount() {
return auditRepository.countByStatus("FAILURE");
}
}

Using the Audit Annotation

Service Layer Example:

package com.example.service;
import com.example.audit.annotation.AuditLog;
import org.springframework.stereotype.Service;
@Service
public class UserService {
@AuditLog(
action = "CREATE_USER",
resource = "USER",
logParameters = true,
logResult = false,
logExecutionTime = true
)
public User createUser(User user) {
// Business logic for creating user
return userRepository.save(user);
}
@AuditLog(
action = "UPDATE_USER",
resource = "USER", 
level = AuditLog.LogLevel.WARN,
logParameters = true
)
public User updateUser(Long userId, User user) {
// Business logic for updating user
User existingUser = getUserById(userId);
// update logic...
return userRepository.save(existingUser);
}
@AuditLog(
action = "DELETE_USER", 
resource = "USER",
level = AuditLog.LogLevel.ERROR
)
public void deleteUser(Long userId) {
// Business logic for deleting user
userRepository.deleteById(userId);
}
@AuditLog(
action = "SEARCH_USERS",
resource = "USER",
logParameters = false,
logExecutionTime = true
)
public List<User> searchUsers(String criteria) {
// Search logic
return userRepository.findByCriteria(criteria);
}
}

Controller Layer Example:

package com.example.controller;
import com.example.audit.annotation.AuditLog;
import org.springframework.web.bind.annotation.*;
@RestController
@RequestMapping("/api/users")
public class UserController {
@Autowired
private UserService userService;
@PostMapping
@AuditLog(action = "CREATE_USER_API", resource = "USER_API")
public User createUser(@RequestBody User user) {
return userService.createUser(user);
}
@PutMapping("/{id}")
@AuditLog(action = "UPDATE_USER_API", resource = "USER_API") 
public User updateUser(@PathVariable Long id, @RequestBody User user) {
return userService.updateUser(id, user);
}
@DeleteMapping("/{id}")
@AuditLog(action = "DELETE_USER_API", resource = "USER_API")
public void deleteUser(@PathVariable Long id) {
userService.deleteUser(id);
}
}

Configuration and Best Practices

Application Properties:

# application.yml
spring:
jpa:
hibernate:
ddl-auto: update
show-sql: false
datasource:
url: jdbc:mysql://localhost:3306/audit_db
username: user
password: pass
logging:
level:
com.example.audit.aspect: DEBUG
pattern:
console: "%d{yyyy-MM-dd HH:mm:ss} - %logger{36} - %msg%n"
app:
audit:
enabled: true
mask-sensitive-data: true
max-parameter-size: 1000

Best Practices:

  1. Security: Always mask sensitive data (passwords, tokens)
  2. Performance: Be cautious with large object serialization
  3. Selective Auditing: Only audit business-critical operations
  4. Error Handling: Ensure audit failures don't break business logic
  5. Retention: Implement audit log retention policies
  6. Monitoring: Monitor audit system health and performance

Testing the Audit Logging

Unit Test Example:

package com.example.audit.aspect;
import com.example.audit.annotation.AuditLog;
import com.example.audit.repository.AuditRepository;
import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.boot.test.mock.mockito.SpyBean;
import static org.mockito.ArgumentMatchers.any;
import static org.mockito.Mockito.times;
import static org.mockito.Mockito.verify;
@SpringBootTest
class AuditLoggingAspectTest {
@Autowired
private TestService testService;
@SpyBean
private AuditRepository auditRepository;
@Test
void whenAnnotatedMethodCalled_thenAuditLogCreated() {
// When
testService.auditedMethod("test param");
// Then
verify(auditRepository, times(1)).save(any());
}
@Test
void whenNonAnnotatedMethodCalled_thenNoAuditLog() {
// When
testService.nonAuditedMethod();
// Then
verify(auditRepository, times(0)).save(any());
}
@Component
static class TestService {
@AuditLog(action = "TEST_ACTION", resource = "TEST_RESOURCE")
public String auditedMethod(String param) {
return "result";
}
public String nonAuditedMethod() {
return "result";
}
}
}

Conclusion

Spring AOP provides a powerful, non-invasive approach to implement comprehensive audit logging:

  • Clean Separation: Audit logic is completely separated from business logic
  • Declarative Control: Use annotations to specify audit requirements
  • Comprehensive Data: Capture user, timing, parameters, and results
  • Security Aware: Integrates with Spring Security for user context
  • Flexible Storage: Store in database, logs, or both
  • Easy Maintenance: Centralized audit logic in one aspect

This approach ensures your application meets compliance requirements while maintaining clean, maintainable code. The audit trail becomes a valuable asset for security monitoring, debugging, and business intelligence.

Category : JAVA

Leave a Reply

Your email address will not be published. Required fields are marked *


Macro Nepal Helper