Skip to content

    Audit Logging

    Find here information about the AuditLog service in CAP Java.


    AuditLog Service


    As of CAP Java 1.18.0, an AuditLog service is provided for CAP Java applications. The AuditLog service can be used to emit AuditLog related events to registered handlers.

    The following events can be emitted with the AuditLogService to the registered handlers:

    AuditLog events typically are bound to business transactions. In order to handle the events transactionally and also to decouple the request from outbound calls to a consumer, for example a central audit log service, the AuditLog service leverages the outbox service internally which allows deferred sending of events.

    Use AuditLogService

    Get AuditLogService Instance

    The AuditLogService can be injected into a custom handler class, if the CAP Java project uses Spring Boot:

    private AuditLogService auditLogService;

    Alternatively the AuditLog service can be retrieved from the ServiceCatalog:

    ServiceCatalog catalog = context.getServiceCatalog();
    auditLogService = (AuditLogService) catalog.getService(AuditLogService.DEFAULT_NAME);

    See section Using Services for more details about retrieving services.

    Emit Personal Data Access Event

    To emit a personal data access event use method logDataAccess of the AuditLogService.

    List<Access> accesses = new ArrayList<>();
    Access access = Access.create();
    // fill access object with data

    Emit Personal Data Modification Event

    To emit a personal data modification event use method logDataModification of the AuditLogService.

    List<DataModification> dataModifications = new ArrayList<>();
    DataModification modification = DataModification.create();
    // fill data modification object with data

    Emit Configuration Change Event

    To emit a configuration change event use method logConfigChange of the AuditLogService.

    List<ConfigChange> configChanges = new ArrayList<>();
    ConfigChange configChange = ConfigChange.create();
    // fill config change object with data
    auditLogService.logConfigChange(Action.UPDATE, configChanges);

    Emit Security Event

    Use method logSecurityEvent of the AuditLogService to emit an security event.

    String action = "login";
    String data = "user-name";
    auditLogService.logSecurityEvent(action, data);

    Deferred AuditLog Events

    Instead of processing the audit log events synchronously in the audit log handler, the AuditLogService can store the event in the outbox. This is done in the same transaction of the business request. Hence, a cancelled business transaction will not send any audit log events that are bound to it. To gain fine-grained control, for example to isolate a specific event from the current transaction, you may refine the transaction scope. See ChangeSetContext API for more information.

    As the stored events are processed asynchronously, the business request is also decoupled from the audit log handler which typically sends the events synchronously to a central audit log service. This improves resilience and performance.

    By default, the outbox comes in an in-memory flavour which has the drawback that it can’t guarantee that the all events are processed after the transaction has been successfully closed.

    AuditLog Handlers

    Default Handler

    By default, the CAP Java SDK provides an AuditLog handler that writes the AuditLog messages to the application log. This default handler is registered on all AuditLog events, but the log entries are not written to the application log, as the corresponding log level is DEBUG. To enable audit logging to the application log, the log level of the default handler needs to be set to DEBUG level:

      level: DEBUG

    Custom AuditLog Handler

    CAP Java applications can also provide their own AuditLog handlers to implement custom processing of AuditLog events. The custom handler class has to implement the interface EventHandler and needs to be annotated with @ServiceName(value = "*", type = AuditLogService.class). If the CAP Java project uses Spring Boot, the class can be annotated with @Component to register the handler at the CDS runtime.

    For each of the four supported AuditLog events, a handler method can be registered. Depending on the event type, the method signature has to support the corresponding argument type:

    Event Type Argument Type
    Personal Data Access
    Personal Data Modification
    Configuration Change
    Security Event

    With one of the annotations @Before, @On, and @After the handler method needs to be annotated to indicate in which phase of the event processing this method gets called.

    The following example defines an AuditLog event handler class with methods for all event types:

    import org.springframework.stereotype.*;
    @ServiceName(value = "*", type = AuditLogService.class)
    class CustomAuditLogHandler implements EventHandler {
    	public void handleDataAccessEvent(DataAccessLogContext context) {
    		// custom handler code
    	public void handleDataModificationEvent(DataModificationLogContext context) {
    		// custom handler code
    	public void handleConfigChangeEvent(ConfigChangeLogContext context) {
    		// custom handler code
    	public void handleSecurityEvent(SecurityLogContext context) {
    		// custom handler code

    Learn more about implementing an event handler in Event Handler Classes.