Audit Logging

immudb supports immutable, structured audit logging of all server operations. Every gRPC operation is recorded as a JSON audit event stored in immudb’s tamper-proof KV store.

Enabling audit logging#

Start immudb with the --audit-log flag:

1./immudb --audit-log

Or set the environment variable:

1IMMUDB_AUDIT_LOG=true ./immudb

Event types#

Events are classified into five types:

Filtering events#

Control which events are logged with --audit-log-events:

1# Log everything (default)
2./immudb --audit-log --audit-log-events=all
3
4# Only write, admin, and auth events
5./immudb --audit-log --audit-log-events=write
6
7# Only admin and auth events
8./immudb --audit-log --audit-log-events=admin

Event format#

Each event is stored as a JSON object:

 1{
 2  "ts": 1712345678000000000,
 3  "user": "immudb",
 4  "ip": "10.0.0.5",
 5  "db": "defaultdb",
 6  "method": "/immudb.schema.ImmuService/Set",
 7  "type": "WRITE",
 8  "ok": true,
 9  "dur_ms": 2,
10  "sid": "session-id-here"
11}

Events are stored with the audit: key prefix and can be queried using the standard Scan API. They are cryptographically verifiable like all immudb data.

Compliance features#

• Events are immutable and tamper-evident, suitable for SOC 2, HIPAA, and GDPR compliance
• The logger blocks for up to 5 seconds when the internal buffer is full, rather than silently dropping events
• Write failures are retried 3 times with exponential backoff
• Dropped events (after timeout) are logged at ERROR level for monitoring