Audit block

The audit block configures the audit logging settings for the Cerbos instance. Audit logs capture access records and decisions made by the engine along with the associated context data.

Audit logging has some overhead in terms of resource usage (disk IO, CPU and memory). This overhead is usually negligible unless Cerbos is running in a resource-constrained environment. If resources are scarce or if you are expecting heavy traffic, disabling audit logging might have a positive impact on performance.

audit:
  enabled: true # Set to false to completely disable audit logging.
  accessLogsEnabled: true # Log API access attempts
  decisionLogsEnabled: true # Log policy decisions
  backend: local # Audit backend to use.
  local: # Configuration for the local audit backend
    storagePath: /path/to/dir # Path to store the data
    retentionPeriod: 168h # Records older than this will be automatically deleted

Local backend

The local backend uses an embedded key-value store to save audit records. Records are preserved for seven days by default and can be queried using the Admin API, the cerbosctl audit command or the cerbosctl decisions text interface (TUI).

The only required setting for the local backend is the storagePath field which specifies the path on disk where the logs should be stored.

audit:
  enabled: true
  accessLogsEnabled: true
  decisionLogsEnabled: true
  backend: local
  local:
    storagePath: /path/to/dir
    retentionPeriod: 168h
    advanced:
      bufferSize: 16 # Size of the memory buffer. Increasing this will use more memory and the chances of losing data during a crash.
      maxBatchSize: 16 # Write batch size. If your records are small, increasing this will reduce disk IO.
      flushInterval: 30s # Time to keep records in memory before committing.
      gcInterval: 15m # How often the garbage collector runs to remove old entries from the log.

File backend

The file backend writes audit records as newline-delimited JSON to a file or stdout/stderr. With this backend you can use your existing log aggregation system (DataDog agent, Elastic agent, Fluentd, Graylog — to name a few) to collect, process and archive the audit data from all Cerbos instances.

This backend cannot be queried using the Admin API, cerbosctl audit or cerbosctl decisions.

audit:
  enabled: true
  accessLogsEnabled: true
  decisionLogsEnabled: true
  backend: file
  file:
    path: /path/to/audit.log

The path field can be set to special names stdout or stderr to log to stdout or stderr. Note that this would result in audit logs being mixed up with normal Cerbos operational logs. It is recommended to use an actual file for audit log output if your container orchestrator has support for collecting logs from files in addition to stdout/stderr.

Audit log entries can be selected by setting a filter on log.logger == "cerbos.audit". Access log entries have log.kind == "access" and decision log entries have log.kind == "decision".