README

AWS CloudWatch Logs Handler for Monolog

Handler for PHP logging library Monolog for sending log entries to AWS CloudWatch Logs service.

Before using this library, it's recommended to get acquainted with the pricing for AWS CloudWatch services.

Please press ★ Star button if you find this library useful.

Disclaimer

Logs are shipped to AWS CloudWatch Logs synchronously inside your PHP process. For very high-throughput workloads (thousands of records/sec sustained per process), consider an out-of-process pipeline — for example, logging to stdout and forwarding with the CloudWatch agent — that decouples log shipping from request latency and isolates AWS API failures from your app. For typical web and worker workloads, this handler is fine.

Requirements

• PHP ^8.1
• Monolog ^3.0
• AWS account with proper permissions (see list of permissions below)

Features

• Batches up to 10,000 events per PutLogEvents call (the AWS per-batch maximum), with automatic flush on size (1 MB), event-timespan (24 h), or buffer-full thresholds
• Splits oversized records (> 1 MB) into multiple events automatically
• Optional log-group creation with tags and retention policy
• Lazy log-group / log-stream initialization on first write
• Public flush() and reset() for long-lived workers (Symfony Messenger, Laravel queues / Octane, custom daemons)
• Suitable for web applications and for long-running CLI daemons and workers

Installation

Install the latest version with Composer by running

$ composer require maxbanton/cwh:^3.0

Basic Usage

<?php

use Aws\CloudWatchLogs\CloudWatchLogsClient;
use Maxbanton\Cwh\Handler\CloudWatch;
use Monolog\Formatter\JsonFormatter;
use Monolog\Level;
use Monolog\Logger;

$sdkParams = [
    'region' => 'eu-west-1',
    'version' => 'latest',
    'credentials' => [
        'key' => 'your AWS key',
        'secret' => 'your AWS secret',
        'token' => 'your AWS session token', // token is optional
    ]
];

// Instantiate AWS SDK CloudWatch Logs Client
$client = new CloudWatchLogsClient($sdkParams);

// Log group name, will be created if none
$groupName = 'php-logtest';

// Log stream name, will be created if none
$streamName = 'ec2-instance-1';

// Days to keep logs, 14 by default. Set to `null` to allow indefinite retention.
$retentionDays = 30;

// Instantiate handler (tags are optional)
$handler = new CloudWatch($client, $groupName, $streamName, $retentionDays, 10000, ['my-awesome-tag' => 'tag-value'], Level::Debug);

// Set $createStream to false (10th argument) when the log stream is provisioned out of band
// (e.g. via Terraform `aws_cloudwatch_log_stream`). This skips DescribeLogStreams + CreateLogStream
// and lets you drop the matching IAM permissions.
// $handler = new CloudWatch($client, $groupName, $streamName, $retentionDays, 10000, [], Level::Debug, true, true, false);

// Optionally set the JsonFormatter to be able to access your log messages in a structured way
$handler->setFormatter(new JsonFormatter());

// Create a log channel
$log = new Logger('name');

// Set handler
$log->pushHandler($handler);

// Add records to the log
$log->debug('Foo');
$log->warning('Bar');
$log->error('Baz');

Using IAM Task Roles on ECS / EC2

When running on ECS or EC2, prefer the task/instance IAM role over hard-coded credentials. Wrap the credential provider in memoize() so long-running workers don't hit metadata-endpoint timeouts:

<?php

use Aws\CloudWatchLogs\CloudWatchLogsClient;
use Aws\Credentials\CredentialProvider;

$provider = CredentialProvider::memoize(
    CredentialProvider::ecsCredentials()        // or ::instanceProfile() on EC2
);

$client = new CloudWatchLogsClient([
    'region'      => 'eu-west-1',
    'version'     => 'latest',
    'credentials' => $provider,
]);

Frameworks integration

• Symfony (Example)
• Laravel (Example)

And many others

Migrating from 2.x to 3.x

3.x is a breaking release that drops Monolog 2 and PHP 7.x support. The constructor parameter order, names, and defaults are preserved — existing Symfony YAML and Laravel with/handler_with configs continue to work after the platform upgrades below.

Required changes:

• Bump PHP to 8.1 or newer.
• Bump Monolog to 3.x.
• The Monolog\Logger::DEBUG (and other) constants were removed in Monolog 3. Use Monolog\Level::Debug instead — int|string|Level are all accepted by the $level constructor argument.
• Symfony service definitions referencing !php/const Monolog\Logger::WARNING must change to !php/const Monolog\Level::Warning.
• Laravel channels using 'level' => 'warning' (string form) keep working unchanged.
• Subclasses overriding protected function write(array $record): void must update the signature to protected function write(\Monolog\LogRecord $record): void and access fields via $record->property instead of $record['key'].

New (optional):

• A 10th constructor argument $createStream (default true). Set to false to skip DescribeLogStreams/CreateLogStream for pre-provisioned streams; lets you drop those IAM permissions.

AWS IAM needed permissions

if you prefer to use a separate programmatic IAM user (recommended) or want to define a policy, make sure following permissions are included:

1. CreateLogGroup aws docs
2. CreateLogStream aws docs
3. PutLogEvents aws docs
4. PutRetentionPolicy aws docs
5. DescribeLogStreams aws docs
6. DescribeLogGroups aws docs

When setting the $createGroup argument to false, permissions DescribeLogGroups and CreateLogGroup can be omitted.

When setting the $createStream argument to false, permissions DescribeLogStreams and CreateLogStream can be omitted. Use this when the log stream is provisioned out of band (e.g. via Terraform). If the stream does not exist at runtime, PutLogEvents will fail with ResourceNotFoundException.

AWS IAM Policy full json example

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "logs:CreateLogGroup",
                "logs:DescribeLogGroups"
            ],
            "Resource": "*"
        },
        {
            "Effect": "Allow",
            "Action": [
                "logs:CreateLogStream",
                "logs:DescribeLogStreams",
                "logs:PutRetentionPolicy"
            ],
            "Resource": "{LOG_GROUP_ARN}"
        },
        {
            "Effect": "Allow",
            "Action": [
                "logs:PutLogEvents"
            ],
            "Resource": [
                "{LOG_STREAM_1_ARN}",
                "{LOG_STREAM_2_ARN}"
            ]
        }
    ]
}

Issues

Feel free to report any issues

Contributing

Please check this document

Made in Ukraine 🇺🇦