Laravel CloudWatch Logger

A Laravel logging driver for seamless integration with AWS CloudWatch Logs.

Features

• Custom Monolog channel for sending logs to CloudWatch.
• Configurable AWS credentials, log group, stream, and retention period.
• Support for custom log formatters (e.g., JSON, line format).
• Compatible with Laravel’s native logging system via the Log facade.
• Built-in configuration publishing for easy setup.

Requirements

• PHP: 8.2 or higher
• Laravel: 10.x, 11.x, 12.x
• AWS SDK: Provided via phpnexus/cwh dependency

Installation

Install the package via Composer:

composer require aporat/laravel-cloudwatch-logger

The service provider (CloudWatchLoggerServiceProvider) is automatically registered via Laravel’s package discovery. If auto-discovery is disabled, add it to config/app.php:

'providers' => [
    // ...
    Aporat\CloudWatchLogger\Laravel\CloudWatchLoggerServiceProvider::class,
],

Publish the configuration file:

php artisan vendor:publish --provider="Aporat\CloudWatchLogger\Laravel\CloudWatchLoggerServiceProvider" --tag="config"

This copies cloudwatch-logger.php to your config/ directory.

Configuration

Step 1: Add the CloudWatch Channel

Merge the CloudWatch configuration into config/logging.php under the channels key:

use Aporat\CloudWatchLogger\CloudWatchLoggerFactory;
use Monolog\Formatter\LineFormatter;
use Monolog\Level;

'channels' => [
    // Other channels...
    'cloudwatch' => [
        'driver' => 'custom',
        'via' => Aporat\CloudWatchLogger\CloudWatchLoggerFactory::class,
        'aws' => [
            'region' => env('AWS_DEFAULT_REGION', 'us-east-1'),
            'version' => env('AWS_VERSION', 'latest'),
            'credentials' => [
                'key' => env('AWS_ACCESS_KEY_ID', ''),
                'secret' => env('AWS_SECRET_ACCESS_KEY', ''),
            ],
        ],
        'group' => env('CLOUDWATCH_LOG_GROUP_NAME', env('APP_NAME', 'laravel') . '-' . env('APP_ENV', 'production')),
        'stream' => env('CLOUDWATCH_LOG_STREAM', 'default'),
        'name' => env('CLOUDWATCH_LOG_NAME', env('APP_NAME', 'laravel')),
        'retention' => env('CLOUDWATCH_LOG_RETENTION', 14),
        'level' => env('CLOUDWATCH_LOG_LEVEL', Level::Error->value),
        'batch_size' => env('CLOUDWATCH_LOG_BATCH_SIZE', 10000),
        'formatter' => function (array $config) {
            return new LineFormatter(
                format: '%channel%: %level_name%: %message% %context% %extra%',
                dateFormat: null,
                allowInlineLineBreaks: false,
                ignoreEmptyContextAndExtra: true
            );
        },
    ],
],

Step 2: Set the Log Channel

Update your .env file to use the cloudwatch channel:

LOG_CHANNEL=cloudwatch

Step 3: Configure AWS Credentials

Add your AWS credentials and optional CloudWatch settings to .env:

AWS_ACCESS_KEY_ID=your-aws-key
AWS_SECRET_ACCESS_KEY=your-aws-secret
AWS_DEFAULT_REGION=us-east-1
CLOUDWATCH_LOG_GROUP_NAME=myapp-prod
CLOUDWATCH_LOG_STREAM=app-logs
CLOUDWATCH_LOG_NAME=myapp
CLOUDWATCH_LOG_RETENTION=14
CLOUDWATCH_LOG_LEVEL=error
CLOUDWATCH_LOG_BATCH_SIZE=10000

Usage

Log messages using Laravel’s Log facade, and they’ll be sent to CloudWatch:

use Illuminate\Support\Facades\Log;

Log::info('User logged in successfully', [
    'id' => 1,
    'username' => 'JohnDoe',
    'ip' => '127.0.0.1',
]);

Custom Formatter

Override the default formatter in config/logging.php:

'formatter' => Monolog\Formatter\JsonFormatter::class,

Or use a custom callable:

'formatter' => function (array $config) {
    return new Monolog\Formatter\JsonFormatter();
},

Testing

Run the test suite:

composer test

Generate coverage reports:

composer test-coverage

Contributing

Contributions are welcome! Please:

1. Fork the repository.
2. Create a feature branch (git checkout -b feature/new-feature).
3. Commit your changes (git commit -m "Add new feature").
4. Push to the branch (git push origin feature/new-feature).
5. Open a pull request.

Report issues at GitHub Issues.

License

This package is licensed under the MIT License. See the License File for details.

Support

• Issues: GitHub Issues
• Source: GitHub Repository