README

Integrates PHP Monolog with Seq using HTTP ingestion, enabling structured event logging to a centralized Seq server for enhanced log management.

Installation

composer require pablo1gustavo/monolog-seq

Usage

This package automatically formats log records as CLEF (Compact Log Event Format) and sends them to Seq via HTTP. The fields @t, @m/@mt, @l, and @x are set automatically from the log record.

For more details, refer to the official Seq documentation.

Vanilla PHP

You can find a runnable example in example.php.

use Monolog\Logger;
use Pablo1Gustavo\MonologSeq\Handler\SeqHandler;

$logger = new Logger('app');
$logger->pushHandler(new SeqHandler(
    url: 'http://localhost:5341/ingest/clef',
    apiKey: 'your-api-key',
));

$logger->info("hello my name is {name}", ['name' => 'pablo']);
$logger->warning('warn message', ['abc' => '123', 'def' => [1, 2, 3]]);
$logger->error('something failed', ['exception' => new Exception('error')]);
$logger->debug('debug message', ['date' => new DateTime('2002-01-13')]);
$logger->info('User logged in', ['@i' => 0xABCD1234, 'userId' => 42]);

Laravel

Laravel allows configuring custom Monolog handlers within config/logging.php. See Laravel Logging - Creating Monolog Handler Channels for details.

'seq' => [
    'driver'    => 'monolog',
    'level'     => env('LOG_LEVEL', 'debug'),
    'handler'   => \Pablo1Gustavo\MonologSeq\Handler\SeqHandler::class,
    'formatter' => \Pablo1Gustavo\MonologSeq\Formatter\SeqJsonFormatter::class,
    'with' => [
        'url'    => env('SEQ_URL'),
        'apiKey' => env('SEQ_API_KEY'),
    ],
],

The formatter key is required. Without it, Laravel applies its default formatter, which produces plain text instead of CLEF.

Symfony

See How to Define a Custom Logging Handler for details.

Register both the handler and the formatter as services in config/services.yaml:

services:
    Pablo1Gustavo\MonologSeq\Formatter\SeqJsonFormatter: ~

    Pablo1Gustavo\MonologSeq\Handler\SeqHandler:
        arguments:
            $url: '%env(SEQ_URL)%'
            $apiKey: '%env(SEQ_API_KEY)%'

Then reference them in config/packages/monolog.yaml:

monolog:
    handlers:
        seq:
            type:      service
            id:        Pablo1Gustavo\MonologSeq\Handler\SeqHandler
            formatter: Pablo1Gustavo\MonologSeq\Formatter\SeqJsonFormatter

The formatter option is required. Without it, Symfony's MonologBundle applies LineFormatter by default, which produces plain text instead of CLEF.

Retry

SeqHandler automatically retries failed deliveries using an exponential-free (immediate) retry strategy. By default it retries up to 3 times on:

• Connection errors — DNS failure, connection refused, timeout, SSL errors
• HTTP 503 Service Unavailable — the only HTTP status that explicitly signals transient unavailability

All other failures (4xx, 500, 502, 504…) are not retried.

When all retries are exhausted, a SeqDeliveryException is thrown with the original cause attached as $previous.

new SeqHandler(
    url: 'http://localhost:5341/ingest/clef',
    apiKey: 'your-api-key',
    maxRetries: 5, // default: 3 — set to 0 to disable retries
);

Batch Ingestion

By default, each log record is sent as a separate HTTP request. For better performance, wrap SeqHandler with Monolog's BufferHandler to accumulate records and flush them in a single request at the end of the process:

use Monolog\Handler\BufferHandler;
use Pablo1Gustavo\MonologSeq\Handler\SeqHandler;

$logger->pushHandler(
    new BufferHandler(
        new SeqHandler(
            url: 'http://localhost:5341/ingest/clef',
            apiKey: 'your-api-key',
        )
    )
);

The BufferHandler automatically flushes at the end of the request via register_shutdown_function().

CLEF Fields via Context

Any CLEF property passed in the log context is promoted to a top-level field in the event. This includes tracing, event identity, and custom overrides:

// Event ID — used by Seq to group and deduplicate events
$logger->info('User logged in', [
    '@i' => 0xABCD1234,
    'userId' => 42,
]);
// Distributed tracing (OpenTelemetry)
$logger->info('Incoming request', [
    '@tr' => $traceId,
    '@sp' => $spanId,
]);
// Override formatter defaults
$logger->info('Custom timestamp', [
    '@t' => '2020-01-01T00:00:00Z',
]);

Supported CLEF fields: @i (event ID), @tr (trace ID), @sp (span ID), @ps (parent span ID), @st (span start), @sk (span kind), @sc (instrumentation scope), @ra (resource attributes).