Ecs Logging Laravel Package

Product Decisions This Supports

• Standardize logging before it sprawls. This package is a formatter, not a platform — it turns Monolog records into ECS-compliant JSON via ElasticCommonSchemaFormatter, which plugs into any Monolog handler. The decision it supports is "do we pick one log schema now, or let each team invent one?" ECS is an open schema under Apache-2.0, so the answer can be yes without buying Elastic.
• Roadmap input for observability work. Structured logs are a prerequisite for log-based alerting, trace-to-log correlation, and per-tenant/per-service dashboards. If "improve MTTR" or "correlate logs with traces" is on the roadmap, this package is a cheap first step, not a quarter-long project.
• Build vs. buy. Building ECS serialization in-house means owning schema version bumps, @timestamp formatting (timezone bug fixed in 1.0.2), label key sanitization, and dot-key expansion behavior. That's a small but permanent maintenance tax for zero differentiation. Buying here is composer require plus wiring.
• Concrete Laravel use cases:
  • Incident response — searchable fields (log.level, log.logger, service.name, service.version) instead of regex-scraping free text.
  • PII and compliance — Elastic\Types\User ships a setHash method for obfuscating user.id/user.name, plus first-class error, service, user, and tracing context objects. This directly supports data-minimization obligations rather than leaving redaction to ad-hoc preg_replace.
  • Trace correlation — Elastic\Types\Tracing injects trace.id/transaction.id, so a log line links to an APM trace. This is the highest-leverage feature for any team already running Elastic APM.
  • Multi-tenant SaaS — ECS labels gives a sanctioned place for tenant.id/environment, which matters if you ever split indices or enforce access control at the log-store layer.
• What it does not decide. It doesn't change your log transport. You still need Filebeat (or Fluent Bit/Vector) with ndjson parsing plus expand_keys/overwrite_keys, or Docker/Kubernetes hints annotations, to land this JSON correctly. Budget that work in the same decision.

When to Consider This Package

Consider it when most of these are true:

• The stack is Laravel on Monolog 3.x — and verify this against your pinned version, because the docs disagree with themselves (see below).
• You are on, or committed to, Elasticsearch/Kibana/Elastic APM, or a log backend that ingests ECS natively. This is where the value is nearly free.
• You want trace correlation and already emit or plan to emit trace IDs.
• You need schema conformance for compliance or cross-team consistency and don't want to author that spec internally.
• Your logging is currently unstructured text, and a migration is scheduled anyway — the marginal cost of doing it right is low.

Look elsewhere, or defer, when:

• You are not on the Elastic stack. ECS is a reasonable schema regardless, but the pitch weakens considerably on Datadog, Loki, or CloudWatch, where native conventions (or OpenTelemetry's log data model) are better supported. OTel is the strategic bet if you expect to change backends.
• You need a Laravel-native, batteries-included integration. There isn't one. You'll write a custom channel in config/logging.php and set the formatter on the handler yourself. That's roughly a day of work including tests — acceptable, but it's yours to own.
• Monolog 2 is still in play. README says only Monolog 3.* is supported; docs/reference/setup.md carries a note that ECS logging for PHP is "currently only available for Monolog v2.*" and imports Elastic\Monolog\v2\Formatter\ElasticCommonSchemaFormatter, while docs/Monolog_v3.md imports Elastic\Monolog\Formatter\ElasticCommonSchemaFormatter. Two namespaces, two claims. Make engineering confirm the shipped namespace against the installed tag before you commit to a plan.
• Adoption risk matters to you. 21 GitHub stars, 0 dependents, effectively a single-vendor project. The Apache-2.0 license means you can fork, and Elastic is a durable sponsor — but there is no community to lean on for answers. That's a supportability cost, not a blocker.
• You want a drop-in win with no transport work. If nobody owns the Filebeat/log-shipper config, this package alone changes nothing.

Two smaller checks worth doing: the examples emit "ecs.version":"1.2.0", so confirm which ECS spec version the tag you install targets and whether your index templates expect it; and confirm the formatter behaves acceptably under Laravel's exception handler, since uncaught exceptions are the logs you'll care most about during an incident.

How to Pitch It (Stakeholders)

To executives (one paragraph): We can make every Laravel service emit logs in a single industry-standard format for the cost of a Composer dependency and about a day of wiring. That buys faster incident diagnosis, consistent audit trails, and the ability to correlate a log line to a specific user and request trace — the foundation for the reliability and observability work already on the roadmap. No license cost, no vendor lock-in, open schema. The main caveat is that it's a small Elastic-maintained library with minimal external adoption, so we should treat it as a thin adapter we could replace in a day rather than infrastructure we depend on.

To engineering (the ask): Add elastic/ecs-logging, set ElasticCommonSchemaFormatter on the Monolog handler for the channels we want structured, and use the provided Error, Service, User, and Tracing context objects instead of hand-rolled arrays. Rough scope: one custom log channel in config/logging.php, a base service provider to attach service name/version, an exception-handling hook, and tests asserting the JSON shape. Before sizing, resolve the docs conflict — the README claims Monolog 3-only while the setup guide claims v2-only and uses a v2 namespace. Ship behind a single channel first, validate the parsed output in Kibana, then migrate the rest.

Positioning line: Not a logging platform — a one-day adapter that makes our existing logs queryable, correlatable, and compliant, with an exit ramp we control.