Laravel Logstash Laravel Package

Getting Started

Install the package with Composer and it registers a logstash log channel for you — there is no service provider to publish or register manually:

composer require <vendor>/<package>:^2.0

Requirements are strict: PHP 8.2+, Laravel 12 or 13, and Monolog 3. If you're on an older Laravel or Monolog 2, stay on the v1 branch (composer require <vendor>/<package>:^1.0), which continues to receive the 1.x line.

The smallest working setup is:

1. Set the host in .env:

   LOGSTASH_HOST=logstash.internal:5000
   

2. Point a channel at it in config/logging.php — the package auto-registers the logstash channel, so you can reference it by name:

   'stack' => [
       'driver' => 'stack',
       'channels' => ['single', 'logstash'],
   ],
   

3. Log as usual. Records are dispatched through a queued job by default.

The first use case to reach for is shipping application logs to Logstash → Elasticsearch/Kibana for centralized search, without changing any Log::info() calls in your code.

Implementation Patterns

Add it to a stack, don't replace your local log. The most common pattern is keeping single/daily for local files and appending logstash to the stack, so you retain a local fallback if the pipeline is down.

Queued by default. Records go through a queued job, which keeps logging off the request path. This means:

• In production, run your queue workers — otherwise records queue up and never ship.
• For CLI scripts or short-lived jobs where the queue may not drain, set LOGSTASH_QUEUE=false to send synchronously.

Tune the channel per environment. The new v2 options (level, queue connection/name, timeout) let you configure the channel like any other Laravel log channel:

'logstash' => [
    'driver'    => 'logstash',
    'host'      => env('LOGSTASH_HOST'),
    'level'     => env('LOG_LEVEL', 'info'),
    'queue'     => env('LOGSTASH_QUEUE', true),
    'connection'=> env('LOGSTASH_QUEUE_CONNECTION'), // dedicated connection
    'queue_name'=> env('LOGSTASH_QUEUE_NAME', 'logs'),
    'timeout'   => 2,
],

Use a dedicated queue connection. If your Logstash job shares a connection with business jobs, a slow/backed-up queue delays shipping logs (and vice versa). Point the connection/queue_name options at a small, isolated queue so logging throughput is independent of application work.

Set the level threshold deliberately. Because the level option exists, you can send only warning+ to Logstash while keeping debug in local files — a clean way to control volume and cost in Elasticsearch.

Integration with existing logging: since it behaves like any Monolog-backed channel, contextual data, channels, and Log::withContext() all flow through unchanged — no wrapper or custom formatter required.

Gotchas and Tips

• Failures are silent by design. The package guarantees an unreachable Logstash never throws, which is great for uptime but bad for observability of the logger itself. Add monitoring on queue depth and, if possible, a dead-letter or a periodic heartbeat log that you verify appears in Kibana. "No errors" does not mean "logs are arriving."
• Queued by default is a behavior change to plan around. In v1-era setups developers often assumed synchronous sends. Verify your workers run in every environment (including scheduled/CLI contexts) or set LOGSTASH_QUEUE=false.
• Queue backlog is your first debugging signal when records stop appearing. Check the configured connection/queue name before assuming the host is wrong.
• Timeout tuning matters for sync mode. With LOGSTASH_QUEUE=false, a hung Logstash endpoint can stall the request until the timeout fires. Keep timeout modest (1–3s).
• Upgrading from 1.x is a hard break. Monolog 3 and Laravel 12/13 are required — there's no gradual path. Audit your Monolog handlers/formatters for Monolog 3 compatibility before bumping, and pin to ^1.0 on the v1 branch if you can't move yet.
• LOGSTASH_HOST is the only required env var, but host:port formatting varies by driver; confirm whether your setup expects a bare host:port or a URL and test one record end-to-end after configuring.
• Extension points: because it's a standard Laravel log channel, you can override the channel definition entirely in config/logging.php and still get the driver — use this to bolt on custom level/queue/timeout combos rather than fighting the auto-registration.