Weave Code
Monolog Bridge Laravel Package
bref/monolog-bridge
A Monolog formatter for AWS Lambda that makes CloudWatch logs both readable and filterable. It outputs structured JSON with message, level, exception, context, and extra fields, enabling Logs Insights queries by level or exception class.
Monolog formatter optimized for AWS Lambda and CloudWatch
Frequently asked questions about Monolog Bridge
- What is bref/monolog-bridge used for?
- It ships the Bref\Monolog\CloudWatchFormatter class, a Monolog formatter that writes each log record as a readable message line followed by a compact JSON object to stderr. The JSON contains message, level, exception, context, and extra fields, which CloudWatch parses so you can filter logs by level or exception class in Logs Insights. It deliberately omits timestamps and channel names because CloudWatch records ingestion time and the Lambda function boundary already separates channels. It is aimed at PHP applications running on AWS Lambda through Bref.
- Do I need to install bref/monolog-bridge if I use Bref's Laravel or Symfony bridge?
- No. The package is already pulled in transitively by Bref's Laravel bridge and Symfony bridge, so running composer require is unnecessary in those setups. You only need to point your logging configuration at Bref\Monolog\CloudWatchFormatter. Install it directly only when you run Bref on Lambda with a hand-rolled Monolog setup.
- How do I enable the CloudWatch formatter in a Laravel app on Lambda?
- Set LOG_STDERR_FORMATTER: Bref\Monolog\CloudWatchFormatter under provider.environment in serverless.yml, then deploy. Laravel's stderr log channel reads that variable, so no PHP code changes are required. This is effectively a one-line configuration change when you are already on the Bref Laravel bridge.
- How do I configure bref/monolog-bridge in Symfony Monolog?
- In config/packages/prod/monolog.yaml, define a stream handler with type: stream, level: info, and formatter: 'Bref\Monolog\CloudWatchFormatter'. The handler must write to stderr, which Bref's Symfony bridge already arranges on Lambda. After that a normal deploy is enough, with no changes to application code.
- Which PHP and Monolog versions does bref/monolog-bridge support?
- The 2.0 line requires PHP 8.2 or newer and adds the Lambda request ID as a prefix on the log line. It is consumed with Monolog 2 or 3 through Bref's bridges, so check your Bref version's constraints if you pin Monolog yourself. The older 1.0 line supports earlier PHP runtimes but lacks the request-ID correlation prefix.
- How do I query logs formatted by bref/monolog-bridge in CloudWatch Logs Insights?
- Because the trailing JSON is parsed by CloudWatch, you can write queries such as fields @timestamp, @message | filter level = 'ERROR' | filter exception.class = 'RuntimeException' | sort @timestamp desc | limit 1000. This structured filtering is the main payoff of the formatter and only matters if your team actually uses Logs Insights operationally. If you just need readable lines, the human-readable message portion alone may be enough.
- Does bref/monolog-bridge work outside AWS Lambda?
- It installs and runs mechanically with any Monolog StreamHandler pointed at php://stderr, so nothing breaks on ECS, EC2, Kubernetes, or another cloud. However, the CloudWatch-specific design choices, such as dropping timestamps and channel names and appending JSON for CloudWatch to parse, lose most of their value there. In those environments a standard JSON or Logstash formatter is usually the better choice.
- What changed in bref/monolog-bridge 2.0 and is it a breaking change?
- Version 2.0 raises the minimum PHP version to 8.2 and prefixes each log line with the Lambda request ID, which makes correlating a request's logs much easier. The new prefix changes the line format, so any tooling or saved queries that parse the previous layout will need adjusting. If you are pinned to an older PHP runtime, stay on the 1.0 line until you upgrade.
- Is bref/monolog-bridge safe for production, and does structured logging increase CloudWatch costs?
- The code itself is small, MIT-licensed, and stateless, adding no services, IAM changes, or I/O beyond the log write. The main risk is ecosystem-level: it is maintained by a single Bref maintainer and is consumed through Bref's bridges rather than direct installs. Structured payloads including exception traces, context, and extra data can increase the bytes shipped to CloudWatch, so review ingestion and retention costs. Also sanitize context and extra fields, since PII there becomes durable and searchable once structured.
- What are the alternatives to bref/monolog-bridge for structured logging?
- Monolog's built-in JsonFormatter or LogstashFormatter, or a small custom formatter, cover most structured logging needs on non-Lambda infrastructure. bref/monolog-bridge is worth preferring when you are on Bref-managed Lambda and intend to filter logs in CloudWatch Logs Insights by level or exception class. If you only need readable stderr output or you standardize on Bref Cloud log viewing, evaluate whether the JSON-after-message layout still fits your workflow before adopting it.
Weaver
How can I help you explore Laravel packages today?