README

简单的PSR-3日志记录器，支持在Graylog中以GELF格式（版本1.1）通过TCP协议进行日志记录。

内容

• 要求
• 安装
• 类 GrayLogger
  • 类方法
  • 示例
• 测试
  • 功能测试
  • 代码分析
• 作者
• 许可证

要求

• PHP >= 5.4;
• 实现PSR-4标准的任意自动加载器类，当不使用Composer时需要。

安装

通过composer安装

$ composer require andrey-tech/graylogger-php:"^1.4"

类 GrayLogger

类 \GrayLogger\GrayLogger 实现了PSR-4标准下的 \Psr\Log\LoggerInterface 接口，并支持将日志记录到 Graylog，格式为 GELF（版本1.1），通过 TCP 协议。

在出现错误时，可能会抛出 \GrayLogger\GrayLoggerException 类型的异常（默认不启用，请参阅类方法 setThrowException()）。

类方法

类 \GrayLogger\GrayLogger 有以下公开方法

注意。

1. 标识符字符串满足正则表达式 /^[a-z0-9]+$/。标识符的允许长度：0-36个字符，默认为7个字符。

2. $message 参数传递需要记录的消息，该消息应为UTF-8编码的字符串或实现 __toString() 方法的对象。消息可以包含占位符，例如 {foo}，其中 foo 将由传递给 $context 参数且具有键 foo 的数组元素的值替换。消息将传递给 short_message 字段 GELF。
   $context 参数可以包含UTF-8编码的附加数据数组，这些数据将作为 GELF 的附加字段传递。

3. $level 参数的可能值由类的公开常量指定：GrayLogger::EMERGENCY、GrayLogger::ALERT、GrayLogger::CRITICAL、GrayLogger::ERROR、GrayLogger::WARNING、GrayLogger::NOTICE、GrayLogger::INFO、GrayLogger::DEBUG。

示例

示例文件位于目录 examples 中。

使用类 GrayLogger 并捕获 GrayLoggerException 类型的异常的示例

use GrayLogger\GrayLogger;
use GrayLogger\GrayLoggerException;

try {
    // Создаем объект класса GrayLogger
    $logger = new GrayLogger();

    // Устанавливаем адрес сервера Graylog
    $logger->setServer('graylog.example.com');

    // Устанавливаем TCP-порт сервера Graylog
    $logger->setPort(9000);

    // Устанавливаем таймаут соединения с сервером Graylog равный 5 секундам
    $logger->setConnectTimeout(5.0);

    // Разрешаем выбрасывать исключение класса GrayLoggerException при возникновении ошибки
    $logger->setThrowExceptions(true);

    /*
     * Устанавливаем массив сопутствующих данных в кодировке UTF-8,
     * передаваемых в дополнительных полях (additional field) GELF
     * во всех последующих лог-сообщениях 
     */
    $logger->setContext([
        /*
         * Уникальный буквенно-цифровой идентификатор, необходимый для поиска в Graylog 
         * всех лог-сообщений в рамках одного запроса
         */
        'request_id' => $this->getUniqId(),

        // Имя файла скрипта, который сейчас выполняется, относительно корня документов
        'script'     => $_SERVER['PHP_SELF']
    ]);

    /*
     * Выполняем логирование с уровнем INFO
     * Пример сформированного сообщения GELF (pretty print):
     * {
     *     "version": "1.1",
     *     "host": "localhost",
     *     "timestamp": 1622394990.561,
     *     "short_message": "Request", 
     *     "level": 6,
     *     "_request_id": "w1fv73k",
     *     "_script": "/index.php",
     *     "_request": "{ \"id\": \"12345\" }"
     * } 
     */
    $logger->info('Request', [
        'request'    => $_POST // Данные POST-запроса в кодировке UTF-8
    ]);

    /*
     * Добавляем новые элементы в массив сопутствующих данных в кодировке UTF-8,
     * передаваемых в дополнительных полях (additional field) GELF
     * во всех последующих лог-сообщениях 
     */
    $logger->addContext([
        'param'     => 6459
    ]);

    /*
     * Выполняем логирование с уровнем WARNING
     * Пример сформированного сообщения GELF (pretty print):
     * {
     *     "version": "1.1",
     *     "host": "localhost",
     *     "timestamp": 1622394991.113,
     *     "short_message": "Value of parameter is 6459", 
     *     "level": 4,
     *     "_request_id": "w1fv73k",
     *     "_script": "/index.php",
     *     "_param": 6459,
     *     "_foo": "bar"
     * } 
     */
    $logger->log(GrayLogger::WARNING, 'Value of parameter is {param}', [ 'foo' => 'bar' ]);

} catch (GrayLoggerException $exception) {
    printf('Ошибка (%d): %s' . PHP_EOL, $exception->getCode(), $exception->getMessage());
}

使用类 GrayLogger 和方法 instance() 并禁止抛出 GrayLoggerException 类型的异常的示例

use GrayLogger\GrayLogger;

// Создаем объект класса GrayLogger
$logger = GrayLogger::instance();

// Устанавливаем адрес сервера Graylog
$logger->setServer('graylog.example.com');

// Устанавливаем TCP-порт сервера Graylog
$logger->setPort(9000);

// Устанавливаем таймаут соединения с сервером Graylog равный 5 секундам
$logger->setConnectTimeout(5.0);

/*
 * Явно запрещаем выбрасывать исключение класса GrayLoggerException 
 * при возникновении ошибки (поведение по умолчанию)
 */
$logger->setThrowExceptions(false);

/*
 * Устанавливаем массив сопутствующих данных в кодировке UTF-8,
 * передаваемых в дополнительных полях (additional field) GELF
 * во всех последующих лог-сообщениях 
 */
$logger->setContext([
    /*
     * Уникальный буквенно-цифровой идентификатор, необходимый для поиска в Graylog 
     * всех лог-сообщений в рамках одного запроса
     */
    'request_id' => $this->getUniqId()
]);

/*
 * Выполняем логирование с уровнем INFO
 * Пример сформированного сообщения GELF (pretty print):
 * {
 *     "version": "1.1",
 *     "host": "localhost",
 *     "timestamp": 1622394995.449,
 *     "short_message": "Request", 
 *     "level": 6,
 *     "_request_id": "i4prla2",
 *    "_foo": "bar"
 * } 
 */
$logger->info('Request', [ 'foo' => 'bar' ]);

/*
 * В другом месте получаем тот же объект класса GrayLogger
 * $logger === $logger2
 */
$logger2 = GrayLogger::instance();

/*
 * Выполняем логирование с уровнем WARNING
 * Пример сформированного сообщения GELF (pretty print):
 * {
 *     "version": "1.1",
 *     "host": "localhost",
 *     "timestamp": 1622394996.261,
 *     "short_message": "Value of parameter foo is bar", 
 *     "level": 7,
 *     "_request_id": "i4prla2",
 *    "_foo": "bar"
 * } 
 */
$logger2->log(GrayLogger::DEBUG, 'Value of parameter foo is {foo}');

// Выводим последнее сформированное лог-сообщение
echo $logger2->getLastMessage();

// Выводим последнее сообщение об ошибке (исключении) при его наличии
$errorMessage = $logger2->getLastErrorMessage();
if (isset($errorMessage)) {
    echo $errorMessage;
}

测试

测试使用 PHPUnit版本4 进行，以确保与PHP 5.4的兼容性。

功能测试

功能测试类位于目录 tests/Functional 中。功能测试通过类 \Test\Functional\SocketServerStub 实现，该类模拟GrayLog服务器并接受地址为 tcp://localhost:12201 的传入请求。为功能测试开发了46个PHPUnit测试，通过命令执行。

$ vendor/bin/phpunit

代码分析

为了分析编码标准PSR-2的违规情况，使用PHP CodeSniffer工具，该工具通过以下命令启动：

$ vendor/bin/phpcs --standard=PSR2 src tests examples

作者

© 2021 andrey-tech

许可证

本库在MIT许可协议下分发。