Weave Code
Laravel Log Cloudwatch Laravel Package
sinemacula/laravel-log-cloudwatch
A Laravel logging driver that sends application logs directly to AWS CloudWatch. Integrate CloudWatch Logs with Laravel’s logging stack to centralize, monitor, and retain logs in AWS with simple configuration.
A CloudWatch Monolog log driver for Laravel that ships application log records to AWS CloudWatch.
Frequently asked questions about Laravel Log Cloudwatch
- How do I install sinemacula/laravel-log-cloudwatch in a Laravel application?
- Install it with Composer using composer require sinemacula/laravel-log-cloudwatch. The package is a Laravel logging driver, so its service provider is registered through package auto-discovery and no manual wiring is normally required. After installing, add a CloudWatch channel to config/logging.php and point LOG_CHANNEL or a stack channel at it. Pin the version you validate so a minor release cannot change behaviour under you.
- Which Laravel and PHP versions does this package support?
- The v1.1.0 release added Laravel 13 support, which signals active maintenance and a forward path without forking. Check the composer.json require constraints of the version you install to confirm the exact Laravel and PHP matrix, since that is authoritative over any README table. Confirm your PHP 8.x runtime matches before adopting, and re-verify the constraint on each upgrade.
- How do I configure the CloudWatch log channel in config/logging.php?
- Add a channel entry to the channels array with the package's driver name and the AWS region, log group and log stream you want to write to. Then either set LOG_CHANNEL to that channel or add it to a stack alongside your existing driver. Most teams keep the configuration environment-driven so per-environment log groups are chosen by config rather than code. Integration is configuration-first and typically takes hours, not days, for a single service.
- What IAM permissions does laravel-log-cloudwatch need to write logs?
- At minimum the task or instance role needs logs:CreateLogGroup, logs:CreateLogStream, logs:DescribeLogStreams and logs:PutLogEvents. Decide deliberately whether your application is allowed to create log groups and streams at all, or whether infrastructure should pre-create them and the app should only put events. Without create permissions, a missing log group surfaces as a ResourceNotFoundException on the first deploy, so pre-provision the group if you lock down IAM.
- Does the driver send logs synchronously, and what happens if CloudWatch is throttled or unreachable?
- Delivery happens on Laravel's logging path through a Monolog handler backed by the AWS SDK, so PutLogEvents calls add network latency to the request or worker lifecycle. Before adopting, validate the handler's buffering and batching behaviour and whether write failures are swallowed, thrown or retried, because a blocking retry can amplify an incident when CloudWatch throttles. The safest pattern is a stack channel that keeps a stderr driver as a fallback so a CloudWatch outage cannot stop the application from logging.
- How are AWS credentials resolved on ECS, EKS or EC2?
- The handler uses the official AWS SDK, so it follows the standard credential chain: ECS task roles, EC2 instance profiles and IRSA on EKS all work without configuration. Prefer those short-lived role credentials over long-lived access keys in environment variables. The SDK refreshes expiring credentials, which matters for long-running queue workers that stay alive for hours.
- Can I keep stderr logging as a fallback alongside CloudWatch?
- Yes. Configure a stack channel in config/logging.php that lists both your CloudWatch channel and the standard stderr or single driver, and set LOG_CHANNEL to the stack. This keeps container-local logs available for immediate debugging and preserves a working sink if CloudWatch is unreachable. It also makes it easy to remove the CloudWatch channel later without touching application code, since the package stays behind Laravel's channel abstraction.
- Does it work reliably with queue workers and scheduled tasks?
- Short-lived processes are the case to test hardest, because a batched handler that only flushes on shutdown can lose records when a worker exits or is killed. Verify flush-on-shutdown behaviour for queue consumers and scheduled commands, and confirm what happens to buffered records on a fatal error. If guarantees are unclear, pair the driver with a stderr channel in a stack so nothing is lost.
- How are log group and stream names configured, and are there message size limits?
- You supply the log group and stream through channel configuration, so you can template them per service, per environment or per container instance depending on what your config layer supports. Check how the package resolves the stream name on each write, since a stream per container instance avoids interleaved writes but multiplies stream count. CloudWatch enforces a 256 KB per-event and per-batch limit, so very large exception payloads with stack traces can be truncated; keep exception context concise.
- When should I avoid this package and use an alternative instead?
- Skip it on AWS Lambda, where stdout and stderr are already routed to CloudWatch automatically and this driver only adds cost and latency. It is also a questionable fit if your system of record is Datadog, New Relic or OpenSearch, or if you already run a Fluent Bit or FireLens sidecar that handles log shipping. It is a transport driver, not an observability platform, so it adds no tracing correlation, sampling or structured context. Given the small, single-maintainer supply chain, run a dependency review and pin the version before production use.
Weaver
How can I help you explore Laravel packages today?