Skip to content

LogEvent

Jump to bottom
Viames Marino edited this page May 5, 2026 · 1 revision

Pair framework: LogEvent

Pair\Models\LogEvent is the ActiveRecord model for warning/error records stored in the log_events table.

The table keeps the request snapshot used by Pair applications and stores structured observability metadata: release, environment, correlation, trace, exception, fingerprint, and sanitized JSON payloads.

Applications should normally write log event records through Logger or Log, not by instantiating LogEvent directly.

Stored data

Main field groups:

  • Severity: level, eventName.
  • Request and user: userId, path, requestMethod, requestData, referer, clientIp, userAgent.
  • Release and runtime: appVersion, environment.
  • Correlation and trace: correlationId, traceId.
  • Grouping: fingerprint.
  • Exception: exceptionClass, exceptionFile, exceptionLine, exceptionTrace.
  • Payloads: description, contextData, serverData.
  • Time: createdAt.

Cookies and authorization headers are not persisted in the default log event table.

Payload format

New rows store request, context, and server payloads as JSON. User-facing messages queued by the application are preserved inside contextData.userMessages when present, instead of a dedicated column.

For backward compatibility, afterPopulate() still reads legacy PHP-serialized payload values when they are stored inside migrated JSON containers. beforePrepareData() normalizes arrays before saving and encodes them as JSON with unescaped slashes and Unicode.

Sensitive payload keys are redacted before persistence by LogEventSanitizer.

Severity

getLevelDescription() returns the human-readable Pair severity for the numeric level.

The table stores only level. String labels and OpenTelemetry-style severity numbers are derived in code or by exporters when needed.

Main methods

  • _init(): defines table, fields, validation, and default ordering.
  • afterPopulate(): decodes JSON or legacy serialized payloads after hydration.
  • beforePrepareData(): sanitizes and JSON-encodes array payloads before storage.
  • getLevelDescription(): string: returns a display label for the numeric severity level.

Recommended usage

Use the logger and pass structured context:

use Pair\Core\Logger;

try {
    exportMonthlyReport();
} catch (Throwable $exception) {
    Logger::getInstance()->error('Report export failed for tenant {tenantId}', [
        'eventName' => 'report.export.failed',
        'tenantId' => 42,
        'exception' => $exception,
    ]);
}

This creates a LogEvent row with a sanitized request snapshot, structured context, exception metadata, trace identifier, and a stable fingerprint.

Set APP_VERSION in the runtime environment to populate the first-class appVersion column.

Migration

20260505_log_events.sql extends the legacy error_logs table with useful structured observability columns, preserves legacy request/user-message payloads in JSON containers, drops the old dedicated payload columns, and renames the table to log_events.

Historical appVersion values remain NULL when old records do not reliably contain release information.

See also: Logger, Log, ErrorLog, DatabaseLogWriter, LogEventSanitizer, LogEventFingerprint, Observability, LogBar.

Clone this wiki locally