hedii/laravel-gelf-logger
A Laravel package that adds a GELF log driver so your application can send structured logs directly to Graylog. Configure the host, port, and transport, then use Laravel’s logging system to ship messages with levels and context.
Architecture fit. This is a thin adapter, not a platform. It registers a Laravel logging channel that formats records as GELF and ships them to a Graylog-compatible collector over UDP, TCP, or TLS. Architecturally it slots into the existing config/logging.php channel stack, which means it composes rather than replaces: the sane pattern is dual-write (single or daily for local forensics plus a gelf channel for centralized search), not a wholesale migration off file logs. It requires no schema, no queue, no sidecar, and no application code changes if the team already logs through the Log facade. That is the strongest argument in its favor: it converts unstructured log lines into a queryable, structured event stream with a config-file-level footprint. It also aligns with the twelve-factor "logs as event streams" posture, moving the app out of the log-rotation-and-shipping business.
Integration feasibility. High, and cheap to prove. Composer install, package discovery, published config, one channel array, a handful of .env keys. Realistic effort for a competent Laravel engineer is a half-day spike plus a day of staging validation — the work is dominated by the Graylog-side setup (input, stream rules, index set, retention, TLS material), not by the PHP package. The genuine unknowns are environmental, not code-level.
Technical risk. Four material risks, in order:
Key questions to resolve before a go decision: Which transport does the handler use by default, and is there a buffered/async or queued variant? Is there a timeout, and does a collector outage throw into the request path or fail silently? Does it support GELF chunking and compression? Which Monolog and Laravel majors are in the CI matrix? Can static fields (service, environment, release, request ID) be injected centrally? Is the license MIT and are there any transitive dependencies of concern? What does the handler do under Laravel Octane / long-running workers with stale sockets?
Stack fit. Any Laravel or Lumen application on Monolog qualifies. The hard prerequisite is a GELF-capable collector — Graylog, or Logstash/OpenSearch with a GELF input. That means this package is never a standalone decision: it is one half of a paired decision with an observability backend, and the backend is where the cost, ownership, and ongoing operational burden actually live. Non-Laravel PHP services in the estate would use graylog2/gelf-php directly, so a mixed-language estate should standardize on the GELF contract rather than on this package.
Migration path. Non-destructive and reversible by design. Add a dedicated graylog channel alongside the existing ones; flip LOG_STACK to include both; route one low-risk service or the staging environment first; validate field parsing, stream routing, and retention in Graylog; then widen. Rollback is an env-var change and a config cache clear — no deploy required. The separate, longer-lead workstream is structured logging discipline: getting teams to pass context arrays rather than interpolated strings. Without that, GELF buys centralized search but not queryability, and much of the value is left on the table.
Compatibility. Verify against the concrete target matrix: PHP version, Laravel major, Monolog major, and GELF spec 1.1 conformance on the collector side. Two specific traps worth budgeting for: env() calls inside published config files are only evaluated at config-cache time, so environment-specific routing must be designed accordingly; and Octane or queue-worker contexts may hold persistent sockets that need reconnect-on-failure behavior.
Sequencing. (1) Provision the Graylog input, TLS certificates, stream rules, index set, and retention — backend first, package second. (2) Install in a spike branch; read the handler source to confirm transport, buffering, and failure behavior. (3) Dual-write from staging; confirm field mapping and that nothing is silently dropped. (4) Add static fields and correlation IDs. (5) Canary one production service with a defined success threshold (search latency, ingest completeness, p99 request latency unchanged). (6) Expand service by service. (7) Retire redundant host-level log shipping only after the new path has proven itself for a full retention cycle.
Maintenance. Low code surface, but we own the upgrade treadmill. Pin the version, subscribe to releases, and re-validate on every Laravel/Monolog major. The important TPM framing is that this package's maintenance burden is dominated by its environment, not its code: the collector, index lifecycle, and retention policy will consume far more ongoing effort than the PHP adapter ever will. Because the shim is thin and the GELF contract is standard, the switching cost away from it is small — that materially de-risks the adoption decision.
Support. Community-only, MIT, no SLA, no vendor. That is acceptable for a logging path provided there is a named internal owner and a runbook covering channel configuration, TLS rotation, and rollback. Escalation for collector outages routes to the platform/SRE team, not to the maintainer.
Scaling. Log volume is the only real scaling variable, and GELF is verbose relative to plaintext — per-message JSON overhead is meaningful at high request rates. Two constraints to model up front: UDP chunking and packet loss under burst (which produces silent gaps in the record, the worst failure mode for an audit or incident-response use case), and per-request connection overhead if TCP/TLS is used synchronously. Budget an early volume estimate (requests/sec × lines/request × bytes) and design in level filtering, sampling for high-cardinality debug paths, and — if volume is high — a buffered or queued handler so logging never sits in the request's critical path. The collector's ingest throughput, index sizing, and retention cost scale linearly with what we emit, so emission policy is a product and cost decision, not just an engineering one.
Failure modes. Enumerate and test these explicitly: collector unreachable (silent drop vs. thrown exception — know which); UDP datagram loss and MTU fragmentation at volume; oversized messages truncated or rejected by the input; TCP/TLS without a timeout translating a network partition into an application latency incident; TLS misconfiguration or certificate expiry breaking all centralized logging at once; config-cache staleness after an .env change; a logging feedback loop if collector errors are themselves logged back to the collector; and PII or credential leakage into a shared index. Each needs a documented detection signal — the meta-risk here is that logging failures are invisible by nature, so monitor ingest rate as a first-class metric, not just application health.
Ramp-up. Developer ramp-up is genuinely trivial — a config array and an .env block. Platform ramp-up is moderate and is the real cost center: Graylog inputs, streams, pipelines, index sets, retention tiers, TLS lifecycle, dashboards, and alerting. Plan the rollout as an observability workstream with a platform owner, not as a library installation, and gate production expansion on the canary service demonstrating complete ingest and unchanged request latency. Net assessment: technically low-risk, operationally contingent on backend readiness, and strategically low-commitment — a reasonable adoption where Graylog is already the chosen backend, and a poor fit if it would be the reason to stand one up.
How can I help you explore Laravel packages today?