auditrails-java

Official Java SDK for auditrails.io — tamper-proof audit logging as a service.

Install

Maven:

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

Gradle:

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

Requires Java 11+. Zero external dependencies (uses java.net.HttpURLConnection).

Quick Start

import io.auditrails.AuditRails;
import io.auditrails.AuditEvent;

try (AuditRails audit = AuditRails.builder("at_live_...").build()) {
    // Fire-and-forget (buffered, flushed in background thread)
    audit.log(AuditEvent.builder(ComplianceAction.AUTH_LOGIN.getValue())  // typed action
            .actorId("user_123")
            .resource("session/sess_456")
            .addMetadata("ip", "1.2.3.4")
            .build());
}
// Events flush automatically on close

That's it. Your first audit event in under 2 minutes.

Compliance Action Constants

The SDK includes ComplianceAction enum with typed constants for all 42 compliance actions:

import io.auditrails.ComplianceAction;

audit.log(AuditEvent.builder(ComplianceAction.AUTH_LOGIN.getValue()).actorId("user_1").build());
audit.log(AuditEvent.builder(ComplianceAction.CONSENT_GIVEN.getValue()).actorId("user_1").build());
audit.log(AuditEvent.builder(ComplianceAction.PHI_ACCESSED.getValue()).actorId("user_1").resource("patient/123").build());

Raw strings are still accepted for backward compatibility.

API

AuditRails.builder(apiKey).build()

Option	Type	Default	Description
baseUrl	String	https://api.auditrails.io	Ingestion API URL
batchSize	int	100	Max events per batch (max 100)
flushIntervalMs	long	1000	Auto-flush interval in ms
maxRetries	int	3	Retry attempts for 5xx errors
timeoutMs	int	10000	Request timeout in ms

audit.log(event)

Buffer an event for batch sending. Never throws — errors are logged via java.util.logging.

audit.log(AuditEvent.builder("document.created")  // required
        .actorId("user_123")                        // who did it
        .resource("document/doc-456")               // what was affected
        .addMetadata("key", "value")                // extra context
        .build());

audit.logDirect(event): LogResponse

Send a single event immediately. Throws AuditRailsException on API errors.

LogResponse resp = audit.logDirect(AuditEvent.builder("user.deleted").build());
System.out.println(resp.getLogId());     // "01HX..."
System.out.println(resp.getRequestId()); // "req_01HX..."

audit.logBatchDirect(events): BatchResponse

Send a batch of events immediately. Throws on error.

audit.flush()

Flush all buffered events immediately.

audit.close()

Flush remaining events and shut down. Implements AutoCloseable for try-with-resources.

Error Handling

The SDK never crashes your application:

• log() never throws — errors go to java.util.logging
• logDirect() and logBatchDirect() throw AuditRailsException on API errors
• 5xx errors are retried with exponential backoff
• 4xx errors fail immediately (no retry)

try {
    audit.logDirect(AuditEvent.builder("test").build());
} catch (AuditRailsException e) {
    System.out.println(e.getCode());       // "validation/missing_action"
    System.out.println(e.getStatusCode()); // 422
    System.out.println(e.getRequestId());  // "req_..."
    System.out.println(e.getDocUrl());     // link to docs
}

License

MIT