Logging

• Introduction
• Log Level
• Request Correlation
• Structured (JSON) Logging
• Console Output
• Logging Naming Conventions
• Log Rotation

Introduction

The framework uses Monolog by default for logging. To enable logging, use the LogWriter behavior trait in your class. The trait provides a $logger property — a Monolog logger accepting a message and a context array:

use Sukarix\Behaviours\LogWriter;

class MyService
{
    use LogWriter;

    public function process(string $id): void
    {
        $this->logger->info('Processing started', ['id' => $id]);
    }
}

Note

Initializing LogWriter

If the class does not extend the Tailored singleton class, ensure to call the initLogWriter method in the constructor.

Log Level

The minimum level is set with log.level (defaults to info):

[globals]
log.level = debug

Request Correlation

Every request is stamped with a request id: Boot forwards an incoming X-Request-Id header when the caller already sent one (useful behind a reverse proxy or an upstream service), or mints one otherwise, and echoes it back on the response. The id is available in the hive as application.request_id and is attached to every log line automatically via Sukarix\Observability\RequestIdProcessor:

[203.0.113.7] [2026-09-14 10:15:03.120] [POST] app.INFO: Processing started {"id":"42"} {"request_id":"a1b2c3d4e5f6a7b8"} []

Forward the same header when your application calls another service so a single request can be traced across all of them.

Structured (JSON) Logging

By default LogWriter writes the line-formatted log described above. Set log.json (or the LOG_JSON environment variable) to emit JSON lines to stdout instead — the shape a log collector (Loki, CloudWatch, an ELK stack) expects:

[globals]
log.json = true

{"message":"Processing started","context":{"id":"42"},"level":200,"level_name":"INFO","channel":"MyService","datetime":"2026-09-14T10:15:03.120000+00:00","extra":{"request_id":"a1b2c3d4e5f6a7b8"}}

All channels share one underlying Monolog logger (Sukarix\Observability\LoggerFactory), so every class using LogWriter writes to the same handler with a consistent format.

Console Output

CLI applications can mirror the log to standard output by enabling log.console. This has no effect when log.json is on — JSON mode already writes to stdout, so there is nothing left for the console handler to add.

[globals]
log.console = true

When the optional bramus/monolog-colored-line-formatter package is installed, console output is coloured per level; otherwise a plain stream is used. The file handler stays active either way, so enabling this adds console output rather than replacing the log file.

Logging Naming Conventions

Logs follow these naming patterns:

• Application Logs: app-yyyy-mm-dd.log
• Application Error Logs: app-error-yyyy-mm-dd.log
• CLI Logs: cli-yyyy-mm-dd.log
• CLI Error Logs: cli-error-yyyy-mm-dd.log
• Exception Logs: exception.log

Log Rotation

Logs are kept for 14 days by default, configurable via the log.keep setting (an integer in days). The Sukarix\Actions\Logs\Clean action is responsible for rotating and cleaning logs.