phpnexus/cwh

AWS CloudWatch 处理器，用于 Monolog 库

维护者

详细信息

github.com/phpnexus/cwh

主页

源代码

问题

安装次数: 758,314

依赖关系: 5

建议者: 0

安全性: 0

星标: 20

关注者: 1

分支: 1

开放问题: 1

v3.1.2 2024-08-02 08:48 UTC

Requires

Requires (Dev)

Suggests

  • maxbanton/dd: Minimalistic dump-and-die function for easy debugging

MIT cad54f4d3342112188fe660e6c8df9638e2ae2e4

monologawscloudwatch

This package is auto-updated.

Last update: 2024-09-02 10:35:11 UTC

README

Actions Status Coverage Status License Version Downloads

这是对原始 maxbanton/cwh 仓库的分支和延续。

用于将日志条目发送到 AWS CloudWatch Logs 服务的 PHP 日志库 Monolog 的处理器。

在开始使用此库之前，建议您了解 AWS CloudWatch 服务的 定价。

如果您觉得这个库很有用，请点击 ★ 星标 按钮。

免责声明

此库通过 AWS PHP SDK 使用 AWS API，该 SDK 对并发请求有限制。这意味着在高并发或高负载的应用程序中，它可能无法以最佳方式运行。请考虑使用其他解决方案，例如通过 fluentd 将日志重定向到 stdout。

要求

  • PHP >=8.1
  • 具有适当权限的 AWS 账户（以下为权限列表）

功能

  • 最多发送 10000 批次日志，以避免 速率超过 错误
  • 使用标签创建日志组
  • AWS CloudWatch Logs 员工延迟加载
  • 适用于 Web 应用程序、长期运行的 CLI 守护程序和工作进程
  • 新功能！ 可配置的速率限制，适用于具有较小批次大小的长期运行的 CLI 守护程序和工作进程

安装

通过运行以下命令使用 Composer 安装最新版本：

$ composer require phpnexus/cwh:^3.0

基本用法

<?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');

高级用法

防止自动创建日志组和流

默认行为是检查目标日志组和流是否存在，并在必要时创建日志组和流。

此活动始终向 AWS 发送 DescribeLogGroups 和 DescribeLogStreams API 调用，如果日志组或流不存在，则向 AWS 发送 CreateLogGroup API 调用或 CreateLogStream API 调用。

AWS 为每个区域每个账户的 DescribeLogGroups 提供默认配额为 每秒 10 个请求，为 DescribeLogStreams 提供默认配额为 每秒 25 个请求，这甚至在中等流量环境中也可能成为瓶颈。

通过将 $createGroup 和 $createStream 设置为 false，此库将不会自动创建目标日志组或流，因此不会向 AWS 发送任何 DescribeLogGroups 或 DescribeLogStreams API 调用。

<?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');

新功能！ 速率限制

默认行为是以每批 10000 条日志或脚本终止时发送日志。这对于短期请求是合适的，但不是长期运行的 CLI 守护程序和工作进程。

对于这些情况，较小的 $batchSize 为 1 会更合适。然而，批次大小较小时，对 AWS 的 putLogEvents 请求的数量将增加，并可能达到 每个账户每个区域的限制。

为了帮助避免此速率限制，请使用 $rpsLimit 选项来限制您的 CLI 守护程序或工作进程每秒可以发送的请求数量。

注意：此限制仅适用于 CLI 守护进程或工作进程的一个实例。对于多个实例，请相应调整 $rpsLimit。

<?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);

框架集成

以及其他许多框架

AWS IAM 需要的权限

如果您希望使用单独的程序 IAM 用户（推荐）或定义策略，您将需要以下权限，具体取决于您的配置。

始终需要

  1. PutLogEvents aws 文档

如果 $createGroup 设置为 true（默认值）

  1. DescribeLogGroups aws 文档
  2. CreateLogGroup aws 文档
  3. PutRetentionPolicy aws 文档

如果 $createStream 设置为 true（默认值）

  1. CreateLogStream aws 文档
  2. DescribeLogStreams aws 文档

注意：以下示例中包括创建日志组和流权限。当将 $createGroup 参数设置为 false 时，删除 "AllowCreateLogGroup" 语句。当将 $createStream 参数设置为 false 时，删除 "AllowCreateLogStream" 语句。

示例 1：向任何日志组中的任何日志流写入

此策略示例允许向名为 my-app 的日志组中的任何日志流写入。日志流将自动创建。

{
    "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:*:*"
        }
    ]
}

示例 2：向任何日志组中的任何日志流写入

此策略示例允许向名为 my-app 的日志组中的任何日志流写入。日志流将自动创建。

{
    "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:*"
        }
    ]
}

示例 3：向特定日志组中的特定日志流写入

此策略示例允许向名为 my-stream-1 和 my-stream-2 的特定日志流写入，在名为 my-app 的日志组中。

{
    "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",
            ]
        }
    ]
}

参考： Amazon CloudWatch Logs 的操作、资源和条件键

问题

请随意 报告任何问题

贡献

请查看 此文档

乌克兰制造 🇺🇦