Laravel Logstash Laravel Package

Technical Evaluation

Architecture fit. The package is a thin, opinionated adapter between Laravel's Monolog-based logging stack and Logstash (typically over TCP/Redis/HTTP). Architecturally it sits at the edge of the application — it consumes Log facade calls and emits structured records to an external sink. That is a low-coupling position: no domain logic, no persistence, no request-path mutation beyond the log write itself. The v2.0.0 auto-registration of a logstash channel via the service provider reduces wiring to a single LOGSTASH_HOST environment variable plus a stack/single channel switch, which fits standard Laravel conventions and keeps environment parity simple.

Integration feasibility. High for teams already on or moving to Laravel 12/13. The hard floor is PHP 8.2+, Laravel 12/13, and Monolog 3 — these are consistent with each other (Laravel 12+ ships Monolog 3), so there is no version-matrix negotiation within the framework. The real feasibility gate is the shift to queued delivery by default: any environment without a running queue worker will silently stop shipping logs unless LOGSTASH_QUEUE=false is set. That is a one-line config fix but a meaningful behavioural default change.

Technical risk.

• Breaking by construction. v2.0.0 drops everything below Laravel 12 / Monolog 2. Any application on Laravel 10/11 or Monolog 2 cannot adopt it and must stay on the v1 branch. This is a hard fork in the upgrade path, not a soft deprecation.
• Silent failure is a designed feature and an operational hazard. "A failing or unreachable Logstash never throws" protects application availability but removes the loudest signal that observability is broken. Without a secondary channel or metric, log loss becomes invisible.
• Queued-by-default changes delivery semantics. Records are no longer written at the moment of the event; ordering, latency, and loss-on-queue-failure characteristics all change. Logs are frequently the diagnostic tool used during an incident — if the queue is the thing that is broken, the logs about it are in that same queue.
• Auto-registered channel. If it writes into config/logging.php at boot rather than merging defensively, it can mask or conflict with an existing logstash channel definition. Needs verification.
• Quality signals are positive but unscored. Pest suite, PHPStan and a 12/13 CI matrix indicate active maintenance; the PHPStan level and test coverage depth are not stated.

Key questions.

1. Does channel auto-registration merge with or overwrite an existing logstash channel config?
2. Where do send failures surface — Log::warning on a fallback channel, a Laravel event, or nowhere?
3. Does the queued job retry, and with what backoff/tries? Is there a failed() handler, or are failed jobs dropped?
4. What is the support window for the v1 branch — security fixes only, or parity?
5. Is Monolog 2 support truly gone, or is there a compatibility shim for mixed-version fleets?
6. What PHPStan level and coverage threshold gate the CI matrix?

Integration Approach

Stack fit. Native fit for a Laravel 12/13 service with a standard queue backend (Redis, SQS, database) and an existing ELK/OpenSearch pipeline. The LOGSTASH_HOST + logstash channel pattern is idiomatic; teams already using stack channels can append logstash alongside single/daily with no application code changes. The new level, queue connection, queue name, and timeout options map cleanly onto per-environment configuration (for example, a dedicated logging queue connection so log shipping does not compete with business jobs).

Migration path. This is a major-version migration, not a patch. Two viable routes:

• In-place upgrade for services already on Laravel 12: bump the constraint to ^2.0, set LOGSTASH_QUEUE=false in every environment initially to preserve current synchronous behaviour, then flip to queued delivery once workers are confirmed healthy. This decouples the version bump from the delivery-model change and keeps rollback trivial.
• Branch-and-pin for services still on Laravel 10/11 or Monolog 2: pin to the v1 branch, and treat the Laravel 12 upgrade as a prerequisite work item rather than bundling it with the logging change.

Compatibility. Confirm Monolog 3 alignment across the whole fleet first — a partial Monolog 3 estate will produce a confusing mix of v1 and v2 consumers. Check for any custom Monolog handlers or formatters in the codebase that assume Monolog 2 APIs, since those will be the actual upgrade blockers rather than this package.

Sequencing.

1. Verify Monolog 3 and Laravel 12/13 across target services.
2. Upgrade in a non-production or canary service with LOGSTASH_QUEUE=false.
3. Validate record shape in Kibana/OpenSearch (field names, timestamps, level mapping) against the v1 baseline.
4. Enable queueing in staging, confirm worker throughput and lag.
5. Roll out per service, canary first, with a rollback pin to v1 documented.

Operational Impact

Maintenance. Low surface area: one config entry, one env var, no database migrations. The active CI matrix and static analysis are a good signal, but the v1 maintenance commitment is open-ended and should be confirmed in writing before teams depend on it as a safety net. Budget a recurring review each Laravel major cycle, since this package's major versions appear to track framework majors.

Support. Failure diagnosis splits into three layers — application-side (channel misconfigured), queue-side (worker down, job failing, backlog), and sink-side (Logstash unreachable). Because the package deliberately swallows sink-side errors, the on-call runbook must cover "logs stopped appearing" as a distinct alert class, sourced from queue metrics and a synthetic canary log rather than from the package itself. Without that, mean time to detect observability outages goes up, not down.

Scaling. Queued delivery is the right call at volume — it removes network latency from the request path and absorbs Logstash restarts via buffering. Watch queue depth as the primary scaling metric; log volume spikes during incidents correlate exactly with when the queue is most needed. Size timeout conservatively so a slow sink degrades into dropped records rather than stalled workers. High-cardinality payloads (stack traces, request bodies) are the usual driver of queue growth.

Failure modes.

• Queue worker absent/stopped with LOGSTASH_QUEUE=true → total silent log loss.
• Logstash unreachable → records dropped without exception; only detectable via sink-side gap or fallback signal.
• Misconfigured LOGSTASH_HOST → same silent-drop profile, easy to ship to production unnoticed.
• Auto-registered channel conflicting with a hand-written config → unpredictable routing.
• Queue backlog → log delivery lag, which corrupts incident timelines reconstructed from logs.
• Failed job exhaustion → records lost after retries, unless a failed() handler forwards them elsewhere.

Ramp-up. A developer can integrate this in under an hour. The operational ramp-up is the real cost: on-call needs to learn that "no Logstash errors" is not evidence that logging works, and platform/observability needs a canary and queue-lag alert in place before the queued default is enabled in production. Estimate roughly one engineer-day of platform work per organisation (alerting, runbook, canary) and near-zero per service thereafter. Teams without an existing queue infrastructure investment should start with LOGSTASH_QUEUE=false and treat queueing as a deliberate follow-up, not part of the initial adoption.