diephp / laravel-cloudwatch-logs
Laravel Adapter for AWS CloudWatch
Requires
- php: ^7.4 || ^8.0
- illuminate/support: ~5.5.0|~5.6.0|~5.7.0|~5.8.0|~6.0|^7.0|^8.0|^9.0|^10.0|^11.0|^v12.0
- maxbanton/cwh: ^2.0
This package is auto-updated.
Last update: 2025-03-05 21:29:30 UTC
README
Breaking Change for Version dev-master
This documentation explains how to use the PHP package with Laravel to send logs to AWS CloudWatch using a security policy that doesn't require full access to CloudWatch.
Installation
You can install it via Composer:
composer require diephp/laravel-cloudwatch-logs
Or manually add this to your composer.json
:
{ "require": { "diephp/laravel-cloudwatch-logs": "^1.0.0" } }
Usage in Laravel
You can use this package with Laravel's default \Log
class. Example usage:
\Log::error('Service error', ['message' => 'Message details', 'user_id' => \Auth()?->user_id]);
\Log::debug("Check status", [ "status" => "ok", "ver" => app()->version(), "env" => env("APP_ENV"), "api_url" => env("APP_URL"), ]);
AWS Policy Configuration
Create an IAM role -> Users -> appName or select an existing one.
Set the Permissions policies: (This example provides full access for test/dev environments)
Log group and log stream will be created automatically (not recommended for production)
{ "Version": "2012-10-17", "Statement": [ { "Sid": "CloudWatchLogsFullAccess", "Effect": "Allow", "Action": [ "logs:CreateLogGroup", "logs:CreateLogStream", "logs:PutLogEvents", "logs:DescribeLogGroups", "logs:DescribeLogStreams" ], "Resource": "*" } ] }
Recommended configuration policies (more secure):
You must create the log group and log stream manually and set in config 'createGroup' => false,
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "logs:PutLogEvents", "logs:DescribeLogGroups", "logs:DescribeLogStreams" ], "Resource": "*" } ] }
Laravel Configuration
Open config/logging.php
and find the channels
array, then add the cloudwatch
key with minimal configuration:
'channels' => [ ... 'cloudwatch' => [ 'driver' => 'custom', 'via' => \DiePHP\LaravelCloudWatchLog\Logger::class, 'region' => env('AWS_REGION', 'eu-west-1'), 'credentials' => [ 'key' => env('AWS_ACCESS_KEY_ID'), 'secret' => env('AWS_SECRET_ACCESS_KEY'), ], ], ... ]
For a more detailed configuration, you might want the following:
'channels' => [ ... 'cloudwatch' => [ 'driver' => 'custom', 'region' => env('AWS_REGION', 'eu-west-1'), 'credentials' => [ 'key' => env('AWS_ACCESS_KEY_ID'), 'secret' => env('AWS_SECRET_ACCESS_KEY'), ], 'stream_name' => env('CLOUDWATCH_LOG_STREAM', 'general'), 'retention' => env('CLOUDWATCH_LOG_RETENTION_DAYS', 31), 'group_name' => env('CLOUDWATCH_LOG_GROUP_NAME', env('AWS_SDK_LOG_GROUP_PREFIX', '')."general"), 'version' => env('CLOUDWATCH_LOG_VERSION', 'latest'), 'formatter' => \Monolog\Formatter\JsonFormatter::class, 'batch_size' => env('CLOUDWATCH_LOG_BATCH_SIZE', 10000), // max buffer size to send in one batch 'level' => env('LOG_LEVEL', 'debug'), 'createGroup' => true, // This is related to the AWS policy you choose. 'bubble' => true, // Whether the messages that are handled can bubble up the stack or not 'extra' => [ 'env' => env('APP_ENV'), 'php' => PHP_VERSION, 'laravel' => app()->version(), ], 'tags' => ['tag1', 'tag2'], 'via' => \DiePHP\LaravelCloudWatchLog\Logger::class, ], ... ]
If you use AWS infrastructure for deployment, you can remove the credentials
section from the config because AWS containers already have credentials for aws-sdk.
Then, you should set the LOG_CHANNEL
in your environment variables to cloudwatch
.
Keep in mind that you should replace the env
values with the actual ones you plan to use.