Download the PHP package aporat/laravel-cloudwatch-logger without Composer

Laravel CloudWatch Logger

A Laravel logging driver for AWS CloudWatch Logs.

Features

• A custom Monolog channel that writes to CloudWatch Logs.
• Configurable AWS client, log group, stream, retention, batching and throttling.
• String, class, instance and callable formatters.
• Optional caching of group/stream existence, so a busy app isn't paying two extra AWS calls per process.
• Optional failure suppression, so an unreachable CloudWatch can't turn a handled error into a 500.
• Configuration is validated up front: a bad value fails with a message naming the key, not with an opaque AWS error on the first log line.

Requirements

• PHP: ^8.4
• Laravel: ^12.0 || ^13.0
• phpnexus/cwh: ^3.2 — the handler options this package exposes (create_stream, rps_limit, a PSR-6 cache pool and a null retention) only exist from 3.2 onwards.

Installation

The service provider is auto-discovered. It registers a cloudwatch logging channel from the package defaults, so this already works:

To customise it, publish the config:

The published config/cloudwatch-logger.php is a complete channel definition. If you define a cloudwatch channel yourself in config/logging.php, yours wins and the package leaves it alone.

Defining channels

A channel is a normal Laravel custom driver entry:

Leave both credential values empty to use the AWS default credential chain (IAM task/instance role, environment variables, ~/.aws/credentials). The empty block is removed before the client is built, so the SDK doesn't reject it.

Options

Every one of these also accepts the string form env() produces, so CLOUDWATCH_LOG_BATCH_SIZE=25 and 'batch_size' => 25 behave identically.

Choosing a batch size

batch_size buffers events in memory and sends them in one PutLogEvents call. The right value depends on how long the process lives:

• Queue workers, Horizon, long-running CLI — keep it low (often 1). A logger is cached for the life of the process, so a half-full buffer sits in memory until the next log line arrives, which may be minutes later.
• HTTP requests — a larger batch is fine; the handler flushes when the request ends.

CloudWatch throttles PutLogEvents per stream. When it does, the handler sleeps for a second and retries, which blocks the process. If a stream is busy enough to hit that, set rps_limit so the handler paces itself instead.

Avoiding the per-process describe calls

By default the handler issues a DescribeLogGroups and a DescribeLogStreams call on the first write of every process, for every channel, to find out whether it needs to create them. Set cache to remember the answer:

Entries are namespaced per log group, so two channels writing to a same-named stream in different groups don't collide. Cache failures degrade to a miss — the handler just asks CloudWatch again.

If the group and stream are provisioned outside the application (Terraform, CloudFormation), set create_group and create_stream to false instead and skip the lookups entirely.

Failure handling

A log write that can't reach CloudWatch throws. In a request path that logs its own errors, that turns a handled failure into a 500. Set 'suppress_failures' => true to wrap the handler in Monolog's WhatFailureGroupHandler, which drops the record instead.

For a local fallback rather than a silent drop, use a Laravel stack channel:

Formatters

formatter accepts four shapes:

A string that looks like a class name but doesn't resolve to a FormatterInterface is rejected, rather than being silently used as a format template.

Configuration errors

Invalid configuration throws Aporat\CloudWatchLogger\Exceptions\IncompleteCloudWatchConfig while the channel is being built.

Note that Laravel's LogManager catches anything a channel factory throws and substitutes its emergency file logger (storage/logs/laravel.log). So a misconfigured channel does not raise at the call site — it stops reaching CloudWatch, and the reason is written to the emergency log. Worth checking there if a channel goes quiet after a config change.

Testing

Contributing

See SECURITY.md.

License

MIT. See LICENSE.