Laravel Logstash Laravel Package

Product Decisions This Supports

• Observability roadmap / centralized logging strategy: This package is a narrow, low-cost enabler for shipping application logs into an ELK/Logstash pipeline. It directly supports decisions like "do we standardize on Logstash as our log sink?" and "can we get structured app logs into Kibana without building a custom driver?"
• Build vs. buy (build vs. adopt): A custom Monolog handler plus queue plumbing plus failure-isolation logic is straightforward but non-trivial to harden. This package packages the "don't let logging break the app" behavior (swallowed failures), queued delivery, and config surface into a maintained dependency. The PM decision is adopt-and-configure over build-and-maintain — reasonable when log shipping is infrastructure, not a product differentiator.
• Platform upgrade planning: v2.0.0 explicitly targets Laravel 12/13, PHP 8.2+, and Monolog 3. This is a forcing function for the framework upgrade roadmap — if we're on Laravel 10/11 or Monolog 2, this release is not available to us, and the 1.x line is now maintenance-only on the v1 branch. Sequence the logging dependency alongside the Laravel upgrade, not after it.
• Reliability / risk posture decisions: The "a failing or unreachable Logstash never throws" guarantee is a product-level reliability decision: logging is best-effort and must never be a customer-facing outage vector. This lets us green-light aggressive log shipping without a blast-radius review.
• Cost and throughput decisions: Queued-by-default delivery (LOGSTASH_QUEUE=false to send inline) means log volume is absorbed asynchronously and can be scaled with worker capacity rather than request latency. This informs capacity planning and whether to route through the existing queue infrastructure or a dedicated connection (new queue connection/name options).
• Use cases unlocked: audit/event logging for compliance-adjacent features, per-tenant log routing via separate channels, environment-specific shipping (local direct, production queued), and fast onboarding of new services into the existing Logstash estate.
• Vendor/operational dependency: Adoption deepens commitment to a Logstash-based stack. If the org is standardizing on a hosted observability vendor (Datadog, New Relic, Grafana Cloud), this is a stopgap, not a destination.

When to Consider This Package

Consider it when:

• You run Laravel 12 or 13 on PHP 8.2+ with Monolog 3, and you already operate (or are standing up) a Logstash/ELK ingestion endpoint.
• You want a zero-custom-code log channel: a LOGSTASH_HOST env var and a channel entry is the entire integration surface.
• You need log shipping that is provably non-blocking to requests — the fail-silent contract plus queued-by-default delivery is the headline value.
• You already run a queue worker fleet and can absorb log volume there; the new queue connection/name options let you isolate logging traffic from business jobs.
• You want a maintained dependency with a test suite, static analysis, and a CI matrix across supported framework versions — a reasonable proxy for "someone is watching this."
• Your team is small and logging is infrastructure, not a product feature worth owning.

Look elsewhere when:

• You're on Laravel ≤11, PHP <8.2, or Monolog 2 — v2 is unavailable; the 1.x line is frozen on v1 and will not track new framework releases. Budget for migration, not indefinite pinning.
• Your destination isn't Logstash. If you're sending to Datadog, New Relic, Grafana Loki, or an OTLP collector, use a native Monolog handler or an OpenTelemetry path instead; don't insert Logstash as an accidental middleware.
• You cannot tolerate silent log loss. Fail-silent delivery is the right default for app logs, but it is the wrong choice for audit trails, billing events, or security-relevant records that require delivery guarantees. Those need a durable outbox pattern with acknowledgement and replay, not a fire-and-forget log channel.
• You need rich per-record metadata contracts, sampling, PII redaction, or log-level routing rules beyond a level/queue/timeout setting — the config surface here is intentionally small.
• You have no queue workers and no appetite to run them; you'd be falling back to synchronous sends on the request path.

Adoption risks to flag before committing:

• Silent failure means silent observability gaps — if Logstash is down for hours, nothing pages you. Pair this with a dead-letter/metric on queue failures or a synthetic log-volume alert.
• Queued delivery shifts the failure mode from latency to queue backlog; capacity planning for the log queue is now on your SLO map.
• The package is a thin integration layer — assess maintainer responsiveness and release cadence, since v1 being parked on a branch signals a major-version-only support model going forward.

How to Pitch It (Stakeholders)

For executives (one paragraph): This release is a small, low-cost upgrade to how our applications ship logs into our central logging platform. It brings support for our current Laravel and PHP versions, sends logs in the background so they never slow down customer requests, and is deliberately built so that a logging outage can never take the product down. The trade-off is equally clear: if the logging system is down, logs are dropped quietly rather than queued forever. That is the correct default for operational logs — but it means audit-grade and financial records must stay on a separate, guaranteed-delivery path. Recommendation: adopt for application logs, sequence the upgrade with our framework upgrade, and treat it as infrastructure we configure rather than software we build.

For engineering leadership: The integration cost is near zero — a channel and a LOGSTASH_HOST value — and v2 adds meaningful operational controls (log level, dedicated queue connection and queue name, send timeout) that let us isolate logging traffic from business jobs and tune backpressure independently. It ships with a Pest suite, PHPStan, and a Laravel 12/13 CI matrix, which is the evidence we need that it keeps pace with framework releases.

For engineering teams (the two things to action):

1. Upgrade ordering matters. v2 requires PHP 8.2+, Laravel 12/13, and Monolog 3. It must land with, not after, the framework upgrade. The 1.x line remains on the v1 branch, so anyone staying behind is on a frozen dependency — treat that as a dated exception, not a resting state.
2. Make the silence observable. The fail-silent guarantee protects the app but hides pipeline outages from us. Before rollout, add a queue-failure alarm and a log-volume anomaly check so "Logstash is unreachable" surfaces in minutes rather than being discovered during an incident review.