Download the PHP package schaefersoft/laravel-seq without Composer

Laravel Seq

Structured logging from Laravel to Seq. Placeholders like {order_id} become properties you can search, filter and chart on, and exceptions arrive with their full stack trace.

Events are buffered and shipped in batches after the response has been sent, so logging never slows down or breaks your application.

Features

• A seq log driver and a ready-to-use seq channel, registered automatically
• PSR-3 placeholders become Seq message templates, context becomes event properties
• Exceptions, including previous exceptions, land in Seq's exception view
• Log::withContext(), Log::shareContext() and Laravel's Context are shipped as properties
• Batched delivery after the response, between queue jobs and when a process ends, even after fatal errors
• Short timeouts, and delivery failures never reach your application
• A circuit breaker pauses shipping while Seq is unreachable, so requests and workers are not held up
• Oversized events are trimmed instead of failing the whole batch
• php artisan seq:test to verify the connection and Seq::fake() for your own tests

Requirements

• PHP 8.2+
• Laravel 12 or 13
• Seq 2023.4+

Installation

The service provider is discovered automatically.

Quick start

Point the package to your Seq server. Without SEQ_URL, nothing is shipped:

Add the seq channel to your log stack:

Check that everything works:

Configuration

Publish the configuration file to change the defaults:

Properties

Every event carries the properties from config/seq.php. By default these are Application and Environment, which lets you tell applications apart on a shared Seq server:

Properties with a null value are skipped. Context values with the same name take precedence.

Channels

The registered seq channel reads everything from config/seq.php. Define channels with the seq driver in config/logging.php to override any of those options per channel, for example to ship audit events to a second Seq server:

Besides the options of config/seq.php, channels accept bubble, name, processors and Laravel's tap. Processors only apply to the events shipped to Seq, even when the channel is part of a stack. properties defined on a channel replace the default properties.

Usage

Keep the message constant and pass the values as context:

Seq receives the event as CLEF:

Seq renders the message as Order 1042 placed by [email protected], lets you filter with order_id = 1042 and groups all events of the same template. Interpolating values yourself ("Order {$id} placed") loses all of that.

Exceptions

Exceptions passed in the exception context key are shipped to Seq's exception field, including previous exceptions and stack traces. Laravel's exception handler does this for every reported exception, so they show up in Seq as soon as the seq channel is part of your default stack.

Context

Context from Log::withContext(), Log::shareContext() and Laravel's Context facade is shipped as properties:

Values

Braces that are not placeholders are escaped, so Blade {{ $name }} failed is rendered exactly as written. Property names starting with @ are escaped as CLEF requires.

Levels

Delivery

Events are buffered in memory and shipped in batches:

A batch is also shipped as soon as SEQ_BATCH_SIZE events are buffered, or when an event is logged while the oldest buffered event is older than SEQ_FLUSH_INTERVAL seconds. This keeps long-running commands close to real time. In your own long-running loops, ship the buffer explicitly:

Failures

Requests use short timeouts. Delivery errors are swallowed and the affected events are dropped, so logging never throws and never blocks longer than the timeouts. After a connection failure, the remaining batches of that flush are dropped instead of waiting for more timeouts. Keep a local channel in your stack, like LOG_STACK=daily,seq, to not lose any events, and run php artisan seq:test to find out what is wrong.

When Seq cannot be reached or does not answer in time, a circuit breaker pauses shipping for SEQ_CIRCUIT_BREAKER seconds and drops the events of that time. Otherwise every request would wait for the timeouts, and under load the PHP-FPM pool would fill up. Error responses from Seq do not trip the circuit breaker. Its state is kept per Seq server:

Without APCu, PHP-FPM forgets the state after every request. Install APCu or set SEQ_CIRCUIT_BREAKER_STORE to a cache store that responds quickly, since it is queried before every delivery.

Large events

Seq rejects events larger than 256 KB and requests larger than 10 MB, and a single rejected event makes it reject the whole request. To prevent that, requests are split into chunks of at most 1 MB, and oversized events are trimmed:

1. The largest properties are removed and listed in DroppedProperties.
2. If that is not enough, the message and exception messages are truncated.
3. As a last resort, the event is replaced by a placeholder with a sample of the original.

If you raised the event size limit of your Seq server, raise SEQ_MAX_EVENT_SIZE as well.

Checking the connection

seq:test sends a test event with the settings of a channel and explains what went wrong if Seq rejects it:

php artisan about shows the Seq configuration as well.

Testing

Seq requests do not go through the Http facade, so Http::fake() neither catches nor counts them. Disable shipping in your phpunit.xml:

Or fake Seq and assert what would have been shipped:

Running Seq locally

Seq is then available at http://localhost:5341. Set SEQ_URL=http://localhost:5341 to ship to it.

Development

The integration tests run against a real Seq server, for example the container from Running Seq locally:

Changelog

See CHANGELOG.md.

License

The MIT License (MIT). See LICENSE.