AWS CloudWatch Logs Handler for Monolog

https://github.com/phpnexus/cwh
Admin
AWS CloudWatch Logs Handler for Monolog is a PHP library that provides a handler for the Monolog...
Tokens:18,391
Snippets:105
Trust Score:4.7
License:MIT
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Install with Composer

Source: https://github.com/phpnexus/cwh/blob/master/README.md

Install the latest version of the package using Composer. Requires PHP >=8.1 and an AWS account with proper permissions.

```bash
$ composer require phpnexus/cwh:^3.0
```

--------------------------------

### Subclassing hooks example

Source: https://github.com/phpnexus/cwh/blob/master/_autodocs/api-reference/CloudWatch.md

Advanced usage example showing how to override willMessageSizeExceedLimit to flush sooner than the hard 1 MiB AWS limit. The override behavior is illustrative; the base conditions are the contract guaranteed by the package.

```php
use Monolog\LogRecord;
use PhpNexus\Cwh\Handler\CloudWatch;

final class TightLimitCloudWatch extends CloudWatch
{
    protected function willMessageSizeExceedLimit(array $record): bool
    {
        // flush sooner than the hard 1 MiB AWS limit
        return parent::willMessageSizeExceedLimit($record) || $this->bufferedBytes() >= 100000;
    }
}
```

--------------------------------

### Configure CloudWatch handler with PSR-6 cache for initialization

Source: https://github.com/phpnexus/cwh/blob/master/README.md

Use this PHP snippet to set up the Monolog CloudWatch handler with PSR-6 caching for log group/stream initialization. Requires a cache adapter implementing Psr\Cache\CacheItemPoolInterface; the default TTL is 5 minutes, but you can override it with the cacheItemTtl parameter. The example also shows optional JSON formatting and logging of debug, warning, and error records.

```php
<?php

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

$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';

// Create cache adapter (must implement Psr\Cache\CacheItemPoolInterface)
$cacheAdapter = new MyCacheAdapter('test-namespace');

// Set cache TTL of 1 hour (default: 5 minutes)
$cacheTtl = 3600;

// Instantiate handler
$handler = new CloudWatch(
    $client,
    $groupName,
    $streamName,
    cacheItemPool: $cacheAdapter,
    cacheItemTtl: $cacheTtl,
);

// 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');
```

--------------------------------

### Basic CloudWatch Handler Usage with Monolog

Source: https://github.com/phpnexus/cwh/blob/master/_autodocs/api-reference/CloudWatch.md

Example 1: basic usage. Creates a CloudWatchLogsClient with credentials, instantiates the CloudWatch handler with a log group 'php-logtest' and stream 'ec2-instance-1', sets a JsonFormatter, and pushes the handler to a Monolog logger. Logs below the handler's level (Level::Info) are not handled.

```php
use Aws\CloudWatchLogs\CloudWatchLogsClient;
use Monolog\Level;
use Monolog\Logger;
use Monolog\Formatter\JsonFormatter;
use PhpNexus\Cwh\Handler\CloudWatch;

$client = new CloudWatchLogsClient([
    'region'      => 'eu-west-1',
    'version'     => 'latest',
    'credentials' => [
        'key'    => 'your AWS key',
        'secret' => 'your AWS secret',
        'token'  => 'your AWS session token', // optional
    ],
]);

$handler = new CloudWatch(
    $client,
    'php-logtest',
    'ec2-instance-1',
    retentionDays: 30,                    // keep logs 30 days
    batchSize: 10000,                     // default flush threshold
    tags: ['my-awesome-tag' => 'tag-value'],
    level: Level::Info,
);

$handler->setFormatter(new JsonFormatter());

$log = new Logger('name');
$log->pushHandler($handler);

$log->debug('Foo'); // below Level::Info, not handled
$log->warning('Bar');
$log->error('Baz');
```

--------------------------------

### Constructor error handling for batchSize > 10000

Source: https://github.com/phpnexus/cwh/blob/master/_autodocs/api-reference/CloudWatch.md

Wrap the CloudWatch handler constructor in a try/catch to handle InvalidArgumentException when batchSize exceeds 10000. The exception is thrown during construction, and the example logs the error message.

```php
use Aws\CloudWatchLogs\CloudWatchLogsClient;
use InvalidArgumentException;
use PhpNexus\Cwh\Handler\CloudWatch;

try {
    $handler = new CloudWatch(
        new CloudWatchLogsClient(['region' => 'eu-west-1', 'version' => 'latest']),
        'group', 'stream',
        batchSize: 10001, // > 10000 -> InvalidArgumentException
    );
} catch (InvalidArgumentException $e) {
    error_log('Invalid CloudWatch handler config: ' . $e->getMessage());
}
```

--------------------------------

### Usage example: constants as guard rails

Source: https://github.com/phpnexus/cwh/blob/master/_autodocs/api-reference/CloudWatch.md

Shows how to access the public constants EVENT_SIZE_LIMIT and TIMESPAN_LIMIT. EVENT_SIZE_LIMIT is the maximum size in bytes of one log event (1048550), and TIMESPAN_LIMIT is the maximum span in milliseconds for a batch (86400000, 24 hours).

```php
use PhpNexus\Cwh\Handler\CloudWatch;

// A single formatted message may be up to 1,048,550 bytes; the handler splits
// longer payloads into chunks of EVENT_SIZE_LIMIT before queuing.
$maxEventBytes = CloudWatch::EVENT_SIZE_LIMIT; // 1048550
$maxBatchSpanMs = CloudWatch::TIMESPAN_LIMIT;  // 86400000 = 24h
```

--------------------------------

### Basic Usage with Monolog and AWS CloudWatch Logs

Source: https://github.com/phpnexus/cwh/blob/master/README.md

Configure the AWS SDK client, create a CloudWatch handler with optional tags and retention, set a JSON formatter, and log messages. The handler sends up to 10000 batch logs to avoid rate exceeded errors and creates log groups/streams if they don't exist.

```php
<?php

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

$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::Info);

// 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');
```

--------------------------------

### Rate limiting with rpsLimit for CLI daemons and workers

Source: https://github.com/phpnexus/cwh/blob/master/README.md

Use batchSize of 1 and rpsLimit to limit putLogEvents requests per second for long-lived CLI daemons and workers. The limit applies per instance; adjust rpsLimit for multiple instances. Includes optional JsonFormatter and a loop to send many log records quickly.

```php
<?php

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

$sdkParams = [
    'region' => 'ap-northeast-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 = 'cli-worker';

// Instantiate handler
$handler = new CloudWatch($client, $groupName, $streamName, batchSize: 1, level: Level::Info, rpsLimit: 100);

// 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 lots of records to the log very quickly
$i = 0;
do {
    $log->info('Foo');
} while ($i++ < 500);
```

--------------------------------

### Sample 1: Write to any log stream in any log group

Source: https://github.com/phpnexus/cwh/blob/master/README.md

IAM policy allowing PutLogEvents to any log stream in any log group, with permissions to create log groups and streams. Remove the 'AllowCreateLogGroup' statement when setting $createGroup to false, and remove the 'AllowCreateLogStream' statement when setting $createStream to false.

```json
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AllowCreateLogGroup",
      "Effect": "Allow",
      "Action": [
        "logs:CreateLogGroup",
        "logs:DescribeLogGroups",
        "logs:PutRetentionPolicy"
      ],
      "Resource": "arn:aws:logs:*:*:log-group:*"
    },
    {
      "Sid": "AllowCreateLogStream",
      "Effect": "Allow",
      "Action": ["logs:CreateLogStream", "logs:DescribeLogStreams"],
      "Resource": "arn:aws:logs:*:*:log-group:*:*"
    },
    {
      "Sid": "AllowPutLogEvents",
      "Effect": "Allow",
      "Action": "logs:PutLogEvents",
      "Resource": "arn:aws:logs:*:*:log-group:*:*"
    }
  ]
}
```

--------------------------------

### Sample 2: Write to any log stream in a log group

Source: https://github.com/phpnexus/cwh/blob/master/README.md

IAM policy allowing PutLogEvents to any log stream in the 'my-app' log group, with permissions to create log groups and streams. Remove the 'AllowCreateLogGroup' statement when setting $createGroup to false, and remove the 'AllowCreateLogStream' statement when setting $createStream to false.

```json
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AllowCreateLogGroup",
      "Effect": "Allow",
      "Action": [
        "logs:CreateLogGroup",
        "logs:DescribeLogGroups",
        "logs:PutRetentionPolicy"
      ],
      "Resource": "arn:aws:logs:*:*:log-group:*"
    },
    {
      "Sid": "AllowCreateLogStream",
      "Effect": "Allow",
      "Action": ["logs:CreateLogStream", "logs:DescribeLogStreams"],
      "Resource": "arn:aws:logs:*:*:log-group:my-app:*"
    },
    {
      "Sid": "AllowPutLogEvents",
      "Effect": "Allow",
      "Action": "logs:PutLogEvents",
      "Resource": "arn:aws:logs:*:*:log-group:my-app:*"
    }
  ]
}
```

--------------------------------

### CloudWatch::__construct

Source: https://github.com/phpnexus/cwh/blob/master/_autodocs/configuration.md

Constructor for the CloudWatch Monolog handler. All configuration is passed through this single constructor; there are no config files or environment variables.

```APIDOC
## CloudWatch::__construct

### Description
Constructor for the CloudWatch Monolog handler. All configuration is passed through this single constructor; there are no config files or environment variables.

### Method
Constructor

### Signature
`__construct(array $options)`

### Parameters
- **client** (`Aws\CloudWatchLogs\CloudWatchLogsClient`) - Required - AWS SDK client used for all CloudWatch Logs API calls.
- **group** (`string`) - Required - Log group name; 1–512 chars from `a-z A-Z 0-9 _ - / .`; auto-created if missing when `createGroup` is true.
- **stream** (`string`) - Required - Log stream name; 1–512 chars, no `:` or `*`; auto-created if missing when `createStream` is true.
- **retention** (`int|null`) - Optional - Default: `14` - Retention days applied via `PutRetentionPolicy` only when the handler creates the log group; `null` = indefinite (no call).
- **batchSize** (`int`) - Optional - Default: `10000` - Records queued before a `putLogEvents` flush; must be ≤ 10000 (constructor throws `InvalidArgumentException` otherwise).
- **tags** (`array`) - Optional - Default: `[]` - Tags for `createLogGroup` (`tags` argument); omitted when empty.
- **level** (`int|string|Monolog\Level`) - Optional - Default: `Level::Debug` - Minimum Monolog logging level handled by the handler.
- **bubble** (`bool`) - Optional - Default: `true` - Whether handled records bubble up the Monolog handler stack.
- **createGroup** (`bool`) - Optional - Default: `true` - `false` disables all group description/creation API calls (`DescribeLogGroups`, `CreateLogGroup`, `PutRetentionPolicy`).
- **createStream** (`bool`) - Optional - Default: `true` - `false` disables all stream description/creation API calls (`DescribeLogStreams`, `CreateLogStream`).
- **rpsLimit** (`int`) - Optional - Default: `0` - Cap on `putLogEvents` requests per second for this handler instance; sleeping 1 s when exhausted. `0` disables.
- **cacheItemPool** (`?Psr\Cache\CacheItemPoolInterface`) - Optional - Default: `null` - PSR-6 pool caching the group/stream initialization state. Rejected when both `createGroup` and `createStream` are `false`.
- **cacheItemTtl** (`int`) - Optional - Default: `300` (`60 * 5`) - Cache TTL in seconds for the initialization state.

### Notes
Cache keys are derived from the group/stream names: `cwh-group-` + `hash('crc32c', $group)` and `cwh-stream-` + `hash('crc32c', $stream)`.
```

--------------------------------

### Sample 3: Write to specific log streams in a log group

Source: https://github.com/phpnexus/cwh/blob/master/README.md

IAM policy allowing PutLogEvents to specific log streams 'my-stream-1' and 'my-stream-2' in the 'my-app' log group, with permissions to create log groups and streams. Remove the 'AllowCreateLogGroup' statement when setting $createGroup to false, and remove the 'AllowCreateLogStream' statement when setting $createStream to false.

```json
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AllowCreateLogGroup",
      "Effect": "Allow",
      "Action": [
        "logs:CreateLogGroup",
        "logs:DescribeLogGroups",
        "logs:PutRetentionPolicy"
      ],
      "Resource": "arn:aws:logs:*:*:log-group:*"
    },
    {
      "Sid": "AllowCreateLogStream",
      "Effect": "Allow",
      "Action": ["logs:CreateLogStream", "logs:DescribeLogStreams"],
      "Resource": "arn:aws:logs:*:*:log-group:my-app:*"
    },
    {
      "Sid": "AllowPutLogEvents",
      "Effect": "Allow",
      "Action": "logs:PutLogEvents",
      "Resource": [
        "arn:aws:logs:*:*:log-group:my-app:log-stream:my-stream-1",
        "arn:aws:logs:*:*:log-group:my-app:log-stream:my-stream-2"
      ]
    }
  ]
}
```

--------------------------------

### write() method signature

Source: https://github.com/phpnexus/cwh/blob/master/_autodocs/api-reference/CloudWatch.md

Monolog's AbstractProcessingHandler callback. Formats the record, splits it into EVENT_SIZE_LIMIT-sized chunks, and queues each chunk. Flushes the buffer when a chunk would breach batch data or 24-hour timespan limits, or when the buffer reaches batchSize. Throws \Psr\Cache\InvalidArgumentException when a cache pool is configured.

```php
/**
 * @throws \Psr\Cache\InvalidArgumentException
 */
protected function write(LogRecord $record): void
```

--------------------------------

### Catch construction and runtime errors in consumer code

Source: https://github.com/phpnexus/cwh/blob/master/_autodocs/errors.md

Wrap handler construction, logging, and close() in try/catch to handle validation errors (InvalidArgumentException) and runtime AWS/cache failures (CloudWatchLogsException, CacheInvalidArgumentException). Construction errors are deterministic for batch size, rps limit, or cache-pool-without-create misconfigurations. Runtime failures include final putLogEvents() retry failure and cache pool rejection of an initialization key.

```php
use Aws\CloudWatchLogs\Exception\CloudWatchLogsException;
use InvalidArgumentException;
use Psr\Cache\InvalidArgumentException as CacheInvalidArgumentException;
use PhpNexus\Cwh\Handler\CloudWatch;

// 1) Construction-time validation errors
try {
    $handler = new CloudWatch($client, $group, $stream, batchSize: 10001);
} catch (InvalidArgumentException $e) {
    // deterministic: batch size / rps limit / cache-pool-without-create misconfiguration
    error_log('Handler misconfigured: ' . $e->getMessage());
}

// 2) Runtime AWS and cache failures around logging/shutdown
try {
    $log->pushHandler($handler);
    $log->info('send me');
    $log->close(); // flush pending buffer
} catch (CloudWatchLogsException $e) {
    // final putLogEvents() retry failed (already error_log()'d and slept 1s once)
    error_log('CloudWatch send failed: ' . $e->getMessage());
} catch (CacheInvalidArgumentException $e) {
    // cache pool rejected an initialization cache key
    error_log('CloudWatch init cache failed: ' . $e->getMessage());
}
```

--------------------------------

### Configure CloudWatchLogsClient with region, version, and credentials

Source: https://github.com/phpnexus/cwh/blob/master/_autodocs/configuration.md

Instantiate the AWS SDK v3 CloudWatchLogsClient with region, API version, and credentials. The handler delegates AWS settings to this injected client and does not read environment variables itself.

```php
$client = new CloudWatchLogsClient([
    'region'      => 'eu-west-1',
    'version'     => 'latest',
    'credentials' => [
        'key'    => '...',
        'secret' => '...',
        'token'  => '...', // optional session token
    ],
]);
```

--------------------------------

### Import CloudWatch handler class

Source: https://github.com/phpnexus/cwh/blob/master/_autodocs/api-reference/CloudWatch.md

Imports the CloudWatch handler class for use in your code. This is the recommended way to consume the handler from the Composer package.

```php
use PhpNexus\Cwh\Handler\CloudWatch;
```

--------------------------------

### Non-trivial options: no auto-create, rate limit, cache

Source: https://github.com/phpnexus/cwh/blob/master/_autodocs/api-reference/CloudWatch.md

Configure the CloudWatch handler with pre-created group/stream, batch size 1 for long-running CLI workers, and a putLogEvents rate limit of 100 req/s. Set createGroup and createStream to false to avoid Describe/Create calls and quota pressure.

```php
use Aws\CloudWatchLogs\CloudWatchLogsClient;
use Monolog\Level;
use PhpNexus\Cwh\Handler\CloudWatch;

$client = new CloudWatchLogsClient(['region' => 'ap-northeast-1', 'version' => 'latest']);

// Group/stream are pre-created in AWS: no Describe/Create calls, no quota pressure.
$handler = new CloudWatch(
    $client,
    'php-logtest',          // must already exist
    'cli-worker',           // must already exist
    batchSize: 1,           // flush every record (long-running CLI worker)
    level: Level::Info,
    createGroup: false,
    createStream: false,
    rpsLimit: 100,          // cap putLogEvents at ~100 req/s; 0 disables
);
```

--------------------------------

### CloudWatch::__construct

Source: https://github.com/phpnexus/cwh/blob/master/_autodocs/index.md

Constructor for the CloudWatch handler. Initializes the handler with AWS credentials, log group/stream names, and optional configuration options.

```APIDOC
## CloudWatch::__construct

### Description
Constructor for the CloudWatch handler. Initializes the handler with AWS credentials, log group/stream names, and optional configuration options.

### Method
Constructor

### Signature
`public function __construct(...)`

### Parameters
- **awsClient** (Aws\CloudWatchLogs\CloudWatchLogsClient) - Required - AWS CloudWatch Logs client instance.
- **groupName** (string) - Required - Name of the CloudWatch log group.
- **streamName** (string) - Required - Name of the CloudWatch log stream.
- **level** (Monolog\Level) - Optional - Minimum log level to handle (default: debug).
- **bubble** (bool) - Optional - Whether to bubble up records to parent handlers (default: true).
- **options** (array) - Optional - Additional configuration options (see configuration.md for all 13 options).

### Response
No return value.
```

--------------------------------

### getDefaultFormatter() method

Source: https://github.com/phpnexus/cwh/blob/master/_autodocs/api-reference/CloudWatch.md

Returns the default LineFormatter used when none is set via setFormatter(). Format is "%channel%: %level_name%: %message% %context% %extra%" with no date format, no inline empty extras, and allowInlineLineBreaks = true.

```php
protected function getDefaultFormatter(): FormatterInterface
{
    return new LineFormatter("%channel%: %level_name%: %message% %context% %extra%", null, false, true);
}
```

--------------------------------

### Disable automatic log group and stream creation with createGroup and createStream

Source: https://github.com/phpnexus/cwh/blob/master/README.md

Set createGroup and createStream to false to prevent automatic creation of log groups and streams, avoiding DescribeLogGroups and DescribeLogStreams API calls. The log group and stream must already exist. Includes optional JsonFormatter for structured logs.

```php
<?php

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

$sdkParams = [
    'region' => 'ap-northeast-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 (must exist already)
$groupName = 'php-logtest';

// Log stream name (must exist already)
$streamName = 'ec2-instance-1';

// Instantiate handler
$handler = new CloudWatch($client, $groupName, $streamName, level: Level::Info, createGroup: false, createStream: 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');
```

--------------------------------

### CloudWatch Handler Constructor Signature

Source: https://github.com/phpnexus/cwh/blob/master/_autodocs/api-reference/CloudWatch.md

Full constructor signature from src/Handler/CloudWatch.php:106. Parameters control log group/stream creation, retention, batching, tagging, logging level, bubbling, rate limiting, and PSR-6 caching. Throws InvalidArgumentException for batchSize > 10000, negative rpsLimit, or cacheItemPool with both createGroup and createStream false.

```php
public function __construct(
    CloudWatchLogsClient $client,
    string $group,
    string $stream,
    int|null $retention = 14,
    int $batchSize = 10000,
    array $tags = [],
    int|string|Level $level = Level::Debug,
    bool $bubble = true,
    bool $createGroup = true,
    bool $createStream = true,
    int $rpsLimit = 0,
    ?CacheItemPoolInterface $cacheItemPool = null,
    int $cacheItemTtl = 60 * 5
)
```

--------------------------------

### CloudWatch constructor

Source: https://github.com/phpnexus/cwh/blob/master/_autodocs/api-reference/CloudWatch.md

Creates a CloudWatch handler instance for sending Monolog logs to AWS CloudWatch Logs. Supports configuration for batch size, log level, group/stream auto-creation, and rate limiting.

```APIDOC
## CloudWatch constructor

### Description
Creates a CloudWatch handler instance for sending Monolog logs to AWS CloudWatch Logs. Supports configuration for batch size, log level, group/stream auto-creation, and rate limiting.

### Method
Constructor

### Endpoint
`new CloudWatch($client, $group, $stream, ...$options)`

### Parameters
#### Constructor Parameters
- **$client** (CloudWatchLogsClient) - Required - AWS CloudWatch Logs client
- **$group** (string) - Required - Log group name
- **$stream** (string) - Required - Log stream name
- **batchSize** (int) - Optional - Number of records to batch before sending (default: 10000, max: 10000)
- **level** (Level) - Optional - Minimum log level to handle (default: Debug)
- **createGroup** (bool) - Optional - Whether to auto-create the log group if it doesn't exist (default: true)
- **createStream** (bool) - Optional - Whether to auto-create the log stream if it doesn't exist (default: true)
- **rpsLimit** (int) - Optional - Rate limit for putLogEvents requests per second (0 disables, default: 0)

### Request Example
```php
use Aws\CloudWatchLogs\CloudWatchLogsClient;
use Monolog\Level;
use PhpNexus\Cwh\Handler\CloudWatch;

$client = new CloudWatchLogsClient(['region' => 'ap-northeast-1', 'version' => 'latest']);

$handler = new CloudWatch(
    $client,
    'php-logtest',          // must already exist
    'cli-worker',           // must already exist
    batchSize: 1,           // flush every record (long-running CLI worker)
    level: Level::Info,
    createGroup: false,
    createStream: false,
    rpsLimit: 100,          // cap putLogEvents at ~100 req/s; 0 disables
);
```

### Response
#### Success Response
No return value.

#### Error Handling
- **InvalidArgumentException** - Thrown when batchSize exceeds 10000 or other invalid configuration

#### Error Example
```php
use Aws\CloudWatchLogs\CloudWatchLogsClient;
use InvalidArgumentException;
use PhpNexus\Cwh\Handler\CloudWatch;

try {
    $handler = new CloudWatch(
        new CloudWatchLogsClient(['region' => 'eu-west-1', 'version' => 'latest']),
        'group', 'stream',
        batchSize: 10001, // > 10000 -> InvalidArgumentException
    );
} catch (InvalidArgumentException $e) {
    error_log('Invalid CloudWatch handler config: ' . $e->getMessage());
}
```
```

--------------------------------

### CloudWatch::__construct

Source: https://github.com/phpnexus/cwh/blob/master/_autodocs/api-reference/CloudWatch.md

Constructor for the CloudWatch Monolog handler. Initializes the handler with AWS CloudWatch Logs client, log group/stream names, and various configuration options for batching, retention, tagging, and rate limiting.

```APIDOC
## CloudWatch::__construct

### Description
Constructor for the CloudWatch Monolog handler. Initializes the handler with AWS CloudWatch Logs client, log group/stream names, and various configuration options for batching, retention, tagging, and rate limiting.

### Method
Constructor

### Signature
```php
public function __construct(
    CloudWatchLogsClient $client,
    string $group,
    string $stream,
    int|null $retention = 14,
    int $batchSize = 10000,
    array $tags = [],
    int|string|Level $level = Level::Debug,
    bool $bubble = true,
    bool $createGroup = true,
    bool $createStream = true,
    int $rpsLimit = 0,
    ?CacheItemPoolInterface $cacheItemPool = null,
    int $cacheItemTtl = 60 * 5
)
```

### Parameters
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `client` | `Aws\CloudWatchLogs\CloudWatchLogsClient` | yes | — | AWS SDK CloudWatch Logs client used for all API calls (`describeLogGroups`, `createLogGroup`, `putRetentionPolicy`, `describeLogStreams`, `createLogStream`, `putLogEvents`). |
| `group` | `string` | yes | — | Log group name. Must be unique within a region; 1–512 chars from `a-z A-Z 0-9 _ - / .`. Created automatically when `$createGroup` is `true` and it does not exist. |
| `stream` | `string` | yes | — | Log stream name, unique within the log group, 1–512 chars; `:` and `*` are not allowed. Created automatically when `$createStream` is `true` and it does not exist. |
| `retention` | `int\|null` | no | `14` | Days to retain log entries. Only used when the handler creates the log group; `null` skips `putRetentionPolicy` (indefinite retention). |
| `batchSize` | `int` | no | `10000` | Number of records to queue before flushing to CloudWatch. Must be ≤ 10000, else `InvalidArgumentException`. |
| `tags` | `array` | no | `[]` | Tags applied to the log group on creation; passed as the `tags` argument of `createLogGroup`. An empty array is omitted from the API call. |
| `level` | `int\|string\|Level` | no | `Level::Debug` | Minimum Monolog logging level at which this handler triggers. |
| `bubble` | `bool` | no | `true` | Whether handled records bubble up the Monolog handler stack. |
| `createGroup` | `bool` | no | `true` | When `true`, initialization checks/creates the log group (`describeLogGroups` + optional `createLogGroup`/`putRetentionPolicy`). `false` skips all group API calls. |
| `createStream` | `bool` | no | `true` | When `true`, initialization checks/creates the log stream (`describeLogStreams` + optional `createLogStream`). `false` skips all stream API calls. |
| `rpsLimit` | `int` | no | `0` | Requests-per-second cap for `putLogEvents`; when exhausted within the current second, a 1-second `sleep()` is triggered. `0` disables throttling. Negative values throw `InvalidArgumentException`. |
| `cacheItemPool` | `?CacheItemPoolInterface` | no | `null` | PSR-6 cache pool for the log group/stream initialization state. Rejects combination with `createGroup = false` and `createStream = false`. |
| `cacheItemTtl` | `int` | no | `300` (`60 * 5`) | TTL in seconds for the cached initialization state. |

### Return
`void`. Assignments to `readonly` properties and `parent::__construct($level, $bubble)` occur; rate-limit bookkeeping (`resetRemainingRequests()`, `rpsTimestamp = new DateTime()`) is initialized inline.

### Throws
| Error | Condition |
|-------|-----------|
| `InvalidArgumentException` | `batchSize > 10000` — message: `'Batch size can not be greater than 10000'` |
| `InvalidArgumentException` | `rpsLimit < 0` — message: `'RPS limit can not be a negative number'` |
| `InvalidArgumentException` | `cacheItemPool` given while `createGroup === false && createStream === false` — message: `'Cache pool can not be used without creating log group or stream'` |

### Example 1: basic usage
```php
use Aws\CloudWatchLogs\CloudWatchLogsClient;
use Monolog\Level;
use Monolog\Logger;
use Monolog\Formatter\JsonFormatter;
use PhpNexus\Cwh\Handler\CloudWatch;

$client = new CloudWatchLogsClient([
    'region'      => 'eu-west-1',
    'version'     => 'latest',
    'credentials' => [
        'key'    => 'your AWS key',
        'secret' => 'your AWS secret',
        'token'  => 'your AWS session token', // optional
    ],
]);

$handler = new CloudWatch(
    $client,
    'php-logtest',
    'ec2-instance-1',
    retentionDays: 30,                    // keep logs 30 days
    batchSize: 10000,                     // default flush threshold
    tags: ['my-awesome-tag' => 'tag-value'],
    level: Level::Info,
);

$handler->setFormatter(new JsonFormatter());

$log = new Logger('name');
$log->pushHandler($handler);

$log->debug('Foo'); // below Level::Info, not handled
$log->warning('Bar');
$log->error('Baz');
```
```

--------------------------------

### CloudWatch::getDefaultFormatter (protected)

Source: https://github.com/phpnexus/cwh/blob/master/_autodocs/index.md

Returns the default formatter for the handler. Overrides the parent method to provide a custom formatter.

```APIDOC
## CloudWatch::getDefaultFormatter (protected)

### Description
Returns the default formatter for the handler. Overrides the parent method to provide a custom formatter.

### Method
Method

### Signature
`protected function getDefaultFormatter(): Monolog\Formatter\FormatterInterface`

### Parameters
None.

### Response
Returns a formatter instance.
```

--------------------------------

### Flush on shutdown with close()

Source: https://github.com/phpnexus/cwh/blob/master/_autodocs/api-reference/CloudWatch.md

Push the handler to a Monolog Logger and call close() to flush any buffered records immediately. This is useful for shutdown scenarios where you want to ensure all logs are sent before the application exits.

```php
$log = new Logger('app');
$log->pushHandler($handler);

$log->info('app started');
$log->info('app finished');

$log->close(); // flushes any buffered records immediately
```

--------------------------------

### willMessageTimestampExceedLimit() method signature

Source: https://github.com/phpnexus/cwh/blob/master/_autodocs/api-reference/CloudWatch.md

Returns true when the record's timestamp is more than TIMESPAN_LIMIT (24 h) after the earliest queued record, i.e. $record['timestamp'] - $this->earliestTimestamp > self::TIMESPAN_LIMIT.

```php
protected function willMessageTimestampExceedLimit(array $record): bool
```

--------------------------------

### Namespace declaration for CloudWatch handler

Source: https://github.com/phpnexus/cwh/blob/master/_autodocs/api-reference/CloudWatch.md

Declares the namespace for the CloudWatch handler class. This is the first line of the handler file and is required for PSR-4 autoloading.

```php
namespace PhpNexus\Cwh\Handler;
```

--------------------------------

### willMessageSizeExceedLimit() method signature

Source: https://github.com/phpnexus/cwh/blob/master/_autodocs/api-reference/CloudWatch.md

Returns true when currentDataAmount + getMessageSize($record) reaches DATA_AMOUNT_LIMIT (1048576). getMessageSize() counts strlen($record['message']) + 26 reserved bytes.

```php
protected function willMessageSizeExceedLimit(array $record): bool
```

--------------------------------

### CloudWatch::write (protected)

Source: https://github.com/phpnexus/cwh/blob/master/_autodocs/index.md

Protected method that writes a log record to CloudWatch. Called by Monolog's processing pipeline.

```APIDOC
## CloudWatch::write (protected)

### Description
Protected method that writes a log record to CloudWatch. Called by Monolog's processing pipeline.

### Method
Method

### Signature
`protected function write(Monolog\LogRecord $record): void`

### Parameters
- **record** (Monolog\LogRecord) - Required - The log record to write.

### Response
No return value.
```

--------------------------------

### close()

Source: https://github.com/phpnexus/cwh/blob/master/_autodocs/api-reference/CloudWatch.md

Flushes any buffered records to CloudWatch Logs and initializes the handler if not already done. This method is called by Monolog when a channel is closed.

```APIDOC
## close()

### Description
Flushes any buffered records to CloudWatch Logs (`flushBuffer()` → `send()` → `client->putLogEvents()`). If the handler has not yet been initialized, initialization (group/stream creation) runs first. This is also the hook Monolog calls when a channel is closed.

### Method
close

### Endpoint
`public function close(): void`

### Parameters
None.

### Request Example
```php
$log = new Logger('app');
$log->pushHandler($handler);

$log->info('app started');
$log->info('app finished');

$log->close(); // flushes any buffered records immediately
```

### Response
#### Success Response
Returns `void`.

#### Error Handling
- **\Psr\Cache\InvalidArgumentException** - Thrown by `cacheItemPool->getItem()` during deferred initialization when a PSR-6 pool is configured
- **Aws\CloudWatchLogs\Exception\CloudWatchLogsException** - Propagated by the final `putLogEvents()` attempt (see errors.md for retry semantics)

#### Error Example
```php
use Aws\CloudWatchLogs\Exception\CloudWatchLogsException;

try {
    $log->close();
} catch (CloudWatchLogsException $e) {
    // The handler already logged the error via error_log() and retried once
    // after a 1-second sleep; if the retry also failed, the exception reaches here.
    error_log('Failed to flush logs to CloudWatch: ' . $e->getMessage());
}
```
```

--------------------------------

### Multi-catch for close() failures in PHP 8.1

Source: https://github.com/phpnexus/cwh/blob/master/_autodocs/errors.md

PHP 8.1 allows a single multi-catch to handle both CloudWatchLogsException and CacheInvalidArgumentException during shutdown. Use this when you only need to log the exception class and message without distinguishing between AWS and cache failures.

```php
try {
    $log->close();
} catch (CloudWatchLogsException | CacheInvalidArgumentException $e) {
    error_log(get_class($e) . ': ' . $e->getMessage());
}
```

--------------------------------

### close() method signature with @throws annotation

Source: https://github.com/phpnexus/cwh/blob/master/_autodocs/api-reference/CloudWatch.md

Full signature of the close() method from src/Handler/CloudWatch.php:476. It flushes buffered records to CloudWatch Logs and is the hook Monolog calls when a channel is closed. Throws \Psr\Cache\InvalidArgumentException during deferred initialization when a PSR-6 pool is configured.

```php
/**
 * @throws \Psr\Cache\InvalidArgumentException
 */
public function close(): void
```

--------------------------------

### CloudWatch handler class declaration

Source: https://github.com/phpnexus/cwh/blob/master/_autodocs/api-reference/CloudWatch.md

Declares the CloudWatch handler class extending AbstractProcessingHandler. The class is not final, allowing extension through protected hooks. Constructed properties are private readonly (PHP 8.1+).

```php
class CloudWatch extends AbstractProcessingHandler
```

--------------------------------

### close() error handling with CloudWatchLogsException

Source: https://github.com/phpnexus/cwh/blob/master/_autodocs/api-reference/CloudWatch.md

Catch CloudWatchLogsException when calling close(). The handler already logs the error via error_log() and retries once after a 1-second sleep; if the retry also fails, the exception reaches the catch block.

```php
use Aws\CloudWatchLogs\Exception\CloudWatchLogsException;

try {
    $log->close();
} catch (CloudWatchLogsException $e) {
    // The handler already logged the error via error_log() and retried once
    // after a 1-second sleep; if the retry also failed, the exception reaches here.
    error_log('Failed to flush logs to CloudWatch: ' . $e->getMessage());
}
```

--------------------------------

### CloudWatch::willMessageSizeExceedLimit (protected)

Source: https://github.com/phpnexus/cwh/blob/master/_autodocs/index.md

Checks if a message size exceeds the configured limit. Used internally to enforce the EVENT_SIZE_LIMIT.

```APIDOC
## CloudWatch::willMessageSizeExceedLimit (protected)

### Description
Checks if a message size exceeds the configured limit. Used internally to enforce the EVENT_SIZE_LIMIT.

### Method
Method

### Signature
`protected function willMessageSizeExceedLimit(string $message): bool`

### Parameters
- **message** (string) - Required - The message to check.

### Response
Returns true if the message size exceeds the limit, false otherwise.
```

--------------------------------

### CloudWatch::willMessageTimestampExceedLimit (protected)

Source: https://github.com/phpnexus/cwh/blob/master/_autodocs/index.md

Checks if a message timestamp exceeds the configured timespan limit. Used internally to enforce the TIMESPAN_LIMIT.

```APIDOC
## CloudWatch::willMessageTimestampExceedLimit (protected)

### Description
Checks if a message timestamp exceeds the configured timespan limit. Used internally to enforce the TIMESPAN_LIMIT.

### Method
Method

### Signature
`protected function willMessageTimestampExceedLimit(int $timestamp): bool`

### Parameters
- **timestamp** (int) - Required - The timestamp to check.

### Response
Returns true if the timestamp exceeds the limit, false otherwise.
```

--------------------------------

### CloudWatch::close

Source: https://github.com/phpnexus/cwh/blob/master/_autodocs/index.md

Closes the handler, flushing any pending log events to CloudWatch. Should be called when the handler is no longer needed.

```APIDOC
## CloudWatch::close

### Description
Closes the handler, flushing any pending log events to CloudWatch. Should be called when the handler is no longer needed.

### Method
Method

### Signature
`public function close(): void`

### Parameters
None.

### Response
No return value.
```
Tokens:
Raw