Java SDK — AuditRails Audit Logging and Integration

The AuditRails Java SDK is a zero-dependency library that uses only HttpURLConnection from the standard library. It targets Java 11+ and is designed for production use: a background thread drains the event buffer, exponential-backoff retries handle transient failures, and AutoCloseable ensures safe shutdown in Spring Boot applications and try-with-resources blocks alike.

Installation

Add the dependency to your build file. The artifact is published to Maven Central.

<dependency>
    <groupId>io.auditrails</groupId>
    <artifactId>auditrails-java</artifactId>
    <version>1.0.0</version>
</dependency>

implementation 'io.auditrails:auditrails-java:1.0.0'

implementation("io.auditrails:auditrails-java:1.0.0")

Initialization

Use the fluent builder to create an AuditRails instance. The API key is the only required argument.

import io.auditrails.AuditRails;

AuditRails audit = AuditRails.builder("at_live_...")
    .baseUrl("https://api.auditrails.io")
    .batchSize(100)
    .flushIntervalMs(1000)
    .maxRetries(3)
    .timeoutMs(10_000)
    .build();

AuditRails implements AutoCloseable, so you can use it in a try-with-resources block for short-lived contexts (such as scripts or tests). In long-running applications, prefer Spring Boot’s destroyMethod or a JVM shutdown hook — see Graceful Shutdown.

Configuration options

Builder method	Default	Description
`baseUrl(String)`	`https://api.auditrails.io`	Override the API endpoint.
`batchSize(int)`	`100`	Maximum events per HTTP request.
`flushIntervalMs(long)`	`1000` (ms)	How often the buffer is flushed, in milliseconds.
`maxRetries(int)`	`3`	Retry attempts on `5xx` responses.
`timeoutMs(int)`	`10000` (ms)	Per-request timeout in milliseconds.

Logging events

Buffered logging (recommended)

audit.log() adds an AuditEvent to the in-memory buffer and returns immediately. The buffer is flushed in the background on the flushIntervalMs schedule. This method never throws.

import io.auditrails.AuditEvent;

audit.log(AuditEvent.builder("user.login")
    .actorId("user_123")
    .resource("session/sess_abc")
    .metadata(Map.of("ip", "203.0.113.1", "method", "oauth2"))
    .build());

Direct (immediate) logging

audit.logDirect() sends the event immediately and returns a LogResponse. It throws AuditRailsException on failure.

import io.auditrails.LogResponse;

LogResponse response = audit.logDirect(
    AuditEvent.builder("document.deleted")
        .actorId("user_456")
        .resource("document/doc-789")
        .build()
);

System.out.println(response.logId());     // "01HXYZ..."
System.out.println(response.requestId()); // AuditRails request ID for support

Direct batch logging

Send multiple events in a single HTTP request, bypassing the buffer. Returns a BatchResponse with all assigned log IDs.

import io.auditrails.BatchResponse;

BatchResponse batch = audit.logBatchDirect(List.of(
    AuditEvent.builder("document.created").actorId("user_123").resource("document/doc-001").build(),
    AuditEvent.builder("document.shared").actorId("user_123").resource("document/doc-001").build()
));
System.out.println(batch.logIds()); // ["01HXYZ...", "01HABC..."]

Manual flush

audit.flush(); // Blocks until the buffer is drained

Framework integration

Spring Boot

Declare AuditRails as a Spring-managed singleton bean. Setting destroyMethod = "close" ensures Spring calls audit.close() during application shutdown, flushing all buffered events before the JVM exits.

import io.auditrails.AuditRails;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class AuditConfig {

    @Bean(destroyMethod = "close")
    public AuditRails auditRails(@Value("${auditrails.api-key}") String apiKey) {
        return AuditRails.builder(apiKey).build();
    }
}

# application.yml

auditrails:
  api-key: ${AUDITRAILS_API_KEY}

Spring MVC interceptor

Use a HandlerInterceptor to automatically audit every API request. afterCompletion fires after the response has been committed, so you always capture the final HTTP status.

import io.auditrails.AuditEvent;
import io.auditrails.AuditRails;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;
import org.springframework.stereotype.Component;
import org.springframework.web.servlet.HandlerInterceptor;

@Component
public class AuditInterceptor implements HandlerInterceptor {

    private final AuditRails audit;

    public AuditInterceptor(AuditRails audit) {
        this.audit = audit;
    }

    @Override
    public void afterCompletion(
        HttpServletRequest request,
        HttpServletResponse response,
        Object handler,
        Exception ex
    ) {
        audit.log(AuditEvent.builder("api.request")
            .actorId(request.getHeader("X-User-ID"))
            .resource(request.getMethod() + " " + request.getRequestURI())
            .metadata(Map.of("status", response.getStatus()))
            .build());
    }
}

@Configuration
public class WebConfig implements WebMvcConfigurer {

    private final AuditInterceptor auditInterceptor;

    public WebConfig(AuditInterceptor auditInterceptor) {
        this.auditInterceptor = auditInterceptor;
    }

    @Override
    public void addInterceptors(InterceptorRegistry registry) {
        registry.addInterceptor(auditInterceptor);
    }
}

Error handling

log() never throws. For logDirect() and logBatchDirect(), catch AuditRailsException to inspect the failure.

import io.auditrails.AuditRailsException;

try {
    audit.logDirect(AuditEvent.builder("user.login").actorId("user_123").build());
} catch (AuditRailsException e) {
    System.out.println(e.getStatusCode()); // HTTP status, e.g. 401
    System.out.println(e.getCode());       // Machine-readable code, e.g. "INVALID_API_KEY"
    System.out.println(e.getRequestId());  // AuditRails request ID for support
    System.out.println(e.getDocUrl());     // Link to relevant documentation
    System.out.println(e.isRetryable());   // true/false
}

Graceful shutdown

AuditRails implements java.lang.AutoCloseable. Calling close() flushes all buffered events and stops the background flush thread. Spring Boot (recommended): Use @Bean(destroyMethod = "close") as shown above. Spring will call close() automatically when the application context is shut down. Try-with-resources: For short-lived use cases (scripts, tests, CLI tools):

try (AuditRails audit = AuditRails.builder(apiKey).build()) {
    audit.log(AuditEvent.builder("script.run").actorId("system").build());
} // close() is called automatically here

Manual shutdown hook: If you are not using Spring, register a JVM shutdown hook:

AuditRails audit = AuditRails.builder(apiKey).build();
Runtime.getRuntime().addShutdownHook(new Thread(audit::close));

Calling close() more than once is safe — subsequent calls are no-ops. Do not call log() after close() has been called; events submitted after shutdown are silently discarded.

​Installation

​Initialization

​Configuration options

​Logging events

​Buffered logging (recommended)

​Direct (immediate) logging

​Direct batch logging

​Manual flush

​Framework integration

​Spring Boot

​Spring MVC interceptor

​Error handling

​Graceful shutdown

Installation

Initialization

Configuration options

Logging events

Buffered logging (recommended)

Direct (immediate) logging

Direct batch logging

Manual flush

Framework integration

Spring Boot

Spring MVC interceptor

Error handling

Graceful shutdown