Batching and Correlating Logs

Record several logs in one call and link related logs with a correlation ID.

A correlation ID links logs that belong to the same operation. Logs get one in three ways: by setting it with correlationId(), by being recorded in the same batch, or by being recorded inside a correlation scope.

Record a batch

Pass an array or other iterable of AuditLogData objects to the manager's record() method:

php
use function HosmelQ\AuditLog\audit_log;

audit_log()->record([
    audit_log('document.published')->tenant('org_123')->toAuditLogData(),
    audit_log('notification.sent')->tenant('org_123')->toAuditLogData(),
]);

All logs in one record() call are written in a single database transaction. If any insert fails, none of the logs are stored. Large batches are split into insert statements according to audit-log.storage.insert_chunk_size.

When a batch contains two or more logs, every log without a correlation ID receives the same generated ID. Logs that already have a correlation ID keep it. A batch with a single log does not receive a correlation ID. An empty or whitespace-only ID set with correlationId() counts as no correlation ID.

Correlate separate calls

Use correlate() when logs recorded by separate calls should share one correlation ID:

php
use function HosmelQ\AuditLog\audit_log;

audit_log()->correlate(function (): void {
    audit_log('document.published')
        ->target(type: 'document', id: 'doc_123')
        ->record();

    audit_log('notification.sent')
        ->target(type: 'document', id: 'doc_123')
        ->record();
});

Every log recorded inside the callback without its own correlation ID receives the scope's ID, including single logs and batches. The scope generates a new ID unless you pass one as the second argument:

php
use function HosmelQ\AuditLog\audit_log;

audit_log()->correlate(function (): void {
    audit_log('document.published')->record();
    audit_log('notification.sent')->record();
}, request()->header('X-Request-Id'));

correlate() returns the callback's return value. The AuditLog facade provides the same method.

Nested scopes

Scopes can be nested. Logs use the innermost scope's ID, and the outer ID applies again after the inner callback finishes. A scope is also closed when its callback throws.

Passing an empty or whitespace-only ID does not open a new scope. The callback still runs, and logs use the outer scope's ID if there is one.

Correlation scopes belong to the current request or job.