andrey-tech/graylogger-php

Простой PSR-3 логгер в Graylog в формате GELF версии 1.1 по протоколу TCP

Maintainers

Details

github.com/andrey-tech/graylogger-php

Homepage

Source

Issues

Installs: 9

Dependents: 0

Suggesters: 0

Security: 0

Stars: 0

Watchers: 1

Forks: 0

Open Issues: 0

v1.4.0 2021-05-31 16:55 UTC

Requires

Requires (Dev)

Provides

MIT 7dae118bf4f5e8b59bd79f0b938baf4724c96a48

logloggingloggertcpPSR31.1grayloggelf

This package is auto-updated.

Last update: 2024-03-29 04:26:42 UTC

README

Graylog logo

Простой PSR-3 логгер в Graylog в формате GELF версии 1.1 по протоколу TCP.

Latest Stable Version Total Downloads License

Содержание

Требования

  • PHP >= 5.4;
  • Произвольный автозагрузчик классов, реализующий стандарт PSR-4, и необходимый когда Composer не используется.

Установка

Установка через composer:

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

Класс GrayLogger

Класс \GrayLogger\GrayLogger реализует интерфейс \Psr\Log\LoggerInterface, согласно стандарту PSR-4, и обеспечивает логирование в Graylog в формате GELF версии 1.1 по протоколу TCP.

При возникновении ошибок может выбрасываться исключение класса \GrayLogger\GrayLoggerException (по умолчанию отключено, см. метод класса setThrowException()).

Методы класса

Класс \GrayLogger\GrayLogger имеет следующие публичные методы:

Метод Описание По умолчанию
setServer(string $server): void Устанавливает адрес сервера Graylog localhost
setPort(string $port): void Устанавливает TCP-порт сервера Graylog 12201
setConnectTimeout(float $connectTimeout): void Устанавливает таймаут соединения с сервером Graylog в секундах 10.0
setHost(string $host): void Устанавливает имя хоста для логирования gethostname()
setThrowExceptions(bool $throwExceptions): void Устанавливает флаг - выбрасывать ли исключение класса GrayLoggerException при возникновении ошибки: true - выбрасывать, false - не выбрасывать false
setContext(array $context): void Устанавливает массив сопутствующих данных в кодировке UTF-8, передаваемых в дополнительных полях (additional field) GELF во всех последующих лог-сообщениях
addContext(array $context): void Добавляет новые элементы в массив сопутствующих данных в кодировке UTF-8, передаваемых в дополнительных полях (additional field) GELF во всех последующих лог-сообщениях
getLastMessage(): ?string Возвращает последнее сформированной сообщение GELF
getLastErrorMessage(): ?string Возвращает последнее сообщение об ошибке (исключении)
getUniqId(int $length = 7) :string Возвращает уникальный буквенно-цифровой идентификатор, связанный с объектом класса GrayLogger и необходимый для поиска в Graylog всех лог-сообщений, сформированных в рамках одного запуска PHP-скрипта1
static instance(): self Возвращает единственный объект класса GrayLogger (синглтон)
Методы PSR-4 2
emergency(string|object $message, array $context = []): void Выполняет логирование с уровнем EMERGENCY
alert(string|object $message, array $context = []): void Выполняет логирование с уровнем ALERT
critical(string|object $message, array $context = []): void Выполняет логирование с уровнем CRITICAL
error(string|object $message, array $context = []): void Выполняет логирование с уровнем ERROR
warning(string|object $message, array $context = []): void Выполняет логирование с уровнем WARNING
notice(string|object $message, array $context = []): void Выполняет логирование с уровнем NOTICE
info(string|object $message, array $context = []): void Выполняет логирование с уровнем INFO
debug(string|object $message, array $context = []): void Выполняет логирование с уровнем DEBUG
log(int $level, string|object $message, array $context = []): void Выполняет логирование с уровнем, заданным параметром $level3

Примечания.

  1. Строка идентификатора удовлетворяет регулярному выражению /^[a-z0-9]+$/. Допустимая длина идентификатора: 0-36 символов, по умолчанию - 7 символов.

  2. В параметре $message передается сообщение, которое должно быть строкой в кодировке UTF-8 или объектом, реализующим метод __toString(). Сообщение может содержать плейсхолдеры в виде {foo}, где foo будет заменено на значение элемента массива сопутствующих данных, передаваемых в параметре $context с ключом foo. Сообщение передается в поле short_message GELF.
    Параметр $context может содержать массив сопутствующих данных в кодировке UTF-8, передаваемых в дополнительных полях (additional field) 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.