Configuration

Configure default attributes, request metadata, redaction, retention, and storage.

The published config/audit-log.php file contains five groups of options. Most options can be set through environment variables; see the table at the end of this page.

Default attributes

Option	Default	Description
`defaults.bucket`	`application`	Bucket used when a log does not set one.
`defaults.source`	`platform`	Source used when a log does not set one.

The builder applies these defaults when it prepares a log. Values passed to bucket() and source() take precedence. AuditLogData objects you create yourself must set both values.

Request metadata

Option	Default	Description
`request.capture_remote_ip`	`true`	Fill a missing remote IP from the current request.
`request.capture_user_agent`	`true`	Fill a missing user agent from the current request.
`request.capture_in_console`	`false`	Allow capture while the application runs in the console.

Console capture is disabled because Laravel binds a synthetic request when running Artisan commands. Queue workers also run in the console, so logs recorded from queued jobs have no request metadata unless you set it yourself. Enable capture_in_console only when the console request holds the values you want to store.

See request metadata for how captured and explicit values are combined.

Redaction

Option	Default	Description
`redaction.exclude`	`[]`	Metadata keys removed from logs.
`redaction.mask`	`[]`	Metadata keys whose values are replaced.
`redaction.replacement`	`[REDACTED]`	Value stored for masked keys.

Both lists must contain only strings; any other value throws an InvalidArgumentException when a log is recorded. See redacting sensitive data for how the rules are applied.

Retention

Option	Default	Description
`retention.days`	`null`	Number of days to keep new logs, or `null` to keep them indefinitely.

When a log is written, its expires_at value is set to occurred_at plus the configured number of days. A null value leaves expires_at empty, and 0 makes logs expire as soon as they occur. Changing the option does not update rows that already exist. A negative value throws an InvalidArgumentException when a log is written.

The package model uses Laravel's MassPrunable trait. Schedule the model:prune command to delete expired rows:

use HosmelQ\AuditLog\Models\AuditLog;
use Illuminate\Support\Facades\Schedule;

Schedule::command('model:prune', [
    '--model' => [AuditLog::class],
])->daily();

The command deletes rows whose expires_at value is not null and is in the past. Rows without an expiration date are never pruned. If you register a custom model, you may pass that class instead.

Storage

Option	Default	Description
`storage.connection`	`null`	Database connection for audit logs. `null` uses the default connection.
`storage.table`	`audit_logs`	Table that stores audit logs.
`storage.insert_chunk_size`	`500`	Maximum number of rows per insert statement.

The migrations, the model, and the writer all read the connection and table from this group, so set them before running the migrations.

Each record() call writes its logs inside one database transaction. Larger batches are split into insert statements of insert_chunk_size rows, and every chunk is rolled back if one fails. The chunk size must be at least 1; a smaller value throws an InvalidArgumentException when a log is written.

Environment variables

Option	Environment variable
`defaults.bucket`	`AUDIT_LOG_DEFAULTS_BUCKET`
`defaults.source`	`AUDIT_LOG_DEFAULTS_SOURCE`
`request.capture_in_console`	`AUDIT_LOG_REQUEST_CAPTURE_IN_CONSOLE`
`request.capture_remote_ip`	`AUDIT_LOG_REQUEST_CAPTURE_REMOTE_IP`
`request.capture_user_agent`	`AUDIT_LOG_REQUEST_CAPTURE_USER_AGENT`
`retention.days`	`AUDIT_LOG_RETENTION_DAYS`
`storage.connection`	`AUDIT_LOG_STORAGE_CONNECTION`
`storage.insert_chunk_size`	`AUDIT_LOG_STORAGE_INSERT_CHUNK_SIZE`
`storage.table`	`AUDIT_LOG_STORAGE_TABLE`

The redaction options have no environment variables. Edit the lists in config/audit-log.php.