Skip to content
Hosmel Quintana

Querying Audit Logs

Query stored audit logs with Eloquent and work with their columns, actors, targets, and metadata.

Query with Eloquent

Query stored logs with the HosmelQ\AuditLog\Models\AuditLog model:

php
use HosmelQ\AuditLog\Models\AuditLog;

$logs = AuditLog::query()
    ->where('tenant_id', 'org_123')
    ->where('bucket', 'application')
    ->latest('occurred_at')
    ->get();

The model uses the connection and table from the audit-log.storage options. To add scopes or relationships, extend the model.

Columns

Column Type Description
id string Log ID.
event string Event name.
tenant_id string Tenant ID, or an empty string.
actor_id string Actor ID.
actor_type string Actor type.
actor_name string or null Actor display name.
actor_metadata array Actor metadata.
targets array List of targets. Each target has id, type, name, and metadata keys.
metadata array Event metadata.
attribute_changes array or null Changed attributes under before and after keys. See attribute changes.
description string Description, or an empty string.
bucket string Bucket.
source string Source.
correlation_id string or null Correlation ID shared by related logs.
remote_ip string or null Remote IP of the request.
user_agent string or null User agent of the request.
occurred_at CarbonImmutable When the event happened.
inserted_at CarbonImmutable When the log was written.
expires_at CarbonImmutable or null When the log becomes eligible for pruning.

Array columns are stored as JSON and cast to PHP arrays. Date columns are stored with millisecond precision.

Indexes

The table has single-column indexes on event, actor_id, actor_type, correlation_id, occurred_at, inserted_at, and expires_at. A composite index on tenant_id, bucket, occurred_at, and id supports listing a tenant's logs in chronological order. Filter by tenant_id first to use it.

Query JSON columns

Use Laravel's JSON query methods to filter by metadata or targets:

php
use HosmelQ\AuditLog\Models\AuditLog;

$logs = AuditLog::query()
    ->where('tenant_id', 'org_123')
    ->where('metadata->visibility', 'public')
    ->whereJsonContains('targets', [['type' => 'document', 'id' => 'doc_123']])
    ->get();

whereJsonContains() requires a database that supports JSON containment, such as MySQL or PostgreSQL. JSON columns are not indexed, so combine these filters with an indexed column.