Weave Code
Ecs Logging Laravel Package
elastic/ecs-logging
ECS Logging for PHP transforms application logs into structured logs that comply with Elastic Common Schema. Supports Monolog 3, works with Filebeat, Elasticsearch, and Kibana, and helps correlate logs with APM traces for better observability.
At a glance
Frequently asked questions about Ecs Logging
- What is elastic/ecs-logging used for in Laravel?
- It is a Monolog formatter that renders application logs as JSON that follows the Elastic Common Schema (ECS). In a Laravel app you can use it to make the existing Monolog stack emit structured fields such as log.level, service.name, and trace.id for Filebeat, Elasticsearch, and Kibana. It does not replace Laravel's logging system or ship logs by itself.
- Does elastic/ecs-logging work with Laravel and Monolog 3?
- The package is not a Laravel package but a Monolog formatter, and Laravel uses Monolog internally, so it can be wired into a Laravel logging channel. The README states Monolog 3.x is the supported version and points to the Monolog v3 example. Laravel versions that constrain Monolog to 3.x are the natural fit, but verify your app's monolog/monolog constraint and the formatter namespace in the installed source before committing.
- How do I install elastic/ecs-logging?
- Run composer require elastic/ecs-logging. There is no Laravel service provider or auto-discovery to register, so installation is only half the work. You still need to define a Laravel logging channel and point its Monolog handler at the ECS formatter.
- How do I configure an ECS logging channel in Laravel?
- Add a channel in config/logging.php using the monolog driver, attach a StreamHandler, RotatingFileHandler, or php://stderr handler, and set the formatter to Elastic\Monolog\Formatter\ElasticCommonSchemaFormatter. Because Laravel builds the channel from config, any formatter constructor arguments such as service name and version may need an explicit container binding or formatter_with configuration. Enrich entries with Log::withContext or per-call context arrays for request, user, and trace fields.
- Which formatter class should I use with Monolog 3?
- The README shows Elastic\Monolog\Formatter\ElasticCommonSchemaFormatter for Monolog 3, while some setup documentation references an Elastic\Monolog\v2\Formatter\ElasticCommonSchemaFormatter namespace for Monolog 2. This contradiction is a real integration risk, so inspect the installed package source and composer constraints rather than relying on the docs alone. For a Monolog 3 Laravel app, use the non-v2 formatter namespace shown in the Monolog v3 example.
- Does elastic/ecs-logging send logs to Elasticsearch?
- No. It is formatter-only: there is no transport, daemon, Elasticsearch client, or Filebeat agent bundled. You must ship the resulting NDJSON with Filebeat, Vector, Fluent Bit, the OpenTelemetry Collector, or a similar agent. Filebeat's filestream input with NDJSON parsing and Elasticsearch index templates are part of the operational work you own.
- How do I correlate Laravel logs with APM traces?
- Populate trace.id and transaction.id, plus service.name and service.version, in the Monolog context using Laravel's Log::withContext or per-call context arrays; the ECS formatter passes additional keys through. In practice you would populate those values from Elastic APM agent data or middleware. That lets Kibana correlate log lines with APM traces, but the correlation only works if the IDs are present and the ECS fields match your mappings.
- Is it safe to log user emails or tokens with ECS logging?
- ECS logs are structured, indexed, and often retained, so emails, tokens, request bodies, and other secrets become searchable data. The package's User object includes setEmail and an opt-in setHash, and arbitrary context passthrough makes it easy to leak PII accidentally. Treat log context as a compliance surface: redact sensitive fields, avoid dumping whole requests, and review what middleware adds.
- How should I test ECS logs before production?
- Unit-test the formatter output by decoding the JSON and asserting required ECS fields such as ecs.version, log.level, message, service.name, and trace.id. Then test the full pipeline in staging with your actual shipper and Elasticsearch index template, because a formatter pinned to an older ECS version can emit fields that do not match current mappings. Also check that redaction middleware runs before the formatter renders context.
- Is elastic/ecs-logging actively maintained, and what are the alternatives?
- The package is Apache-2.0 and published by Elastic, but the assessment found very low adoption, no dependents, and contradictory Monolog 2 versus 3 documentation, so treat it as a small dependency you must validate yourself. Alternatives include Laravel's built-in JSON logging with Monolog's JsonFormatter, a custom ECS formatter, or an OpenTelemetry-based logging pipeline if you are not standardizing on Elastic. Pin the version, confirm the ECS version it emits, and plan for schema upgrades.
Weaver
How can I help you explore Laravel packages today?