README

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 or 11.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:

Fork the repository.
Create a feature branch (git checkout -b feature/new-feature).
Commit your changes (git commit -m "Add new feature").
Push to the branch (git push origin feature/new-feature).
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

aporat / laravel-cloudwatch-logger

Maintainers

Details