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\Log\LoggerInterface, согласно стандарту PSR-4, и обеспечивает логирование в 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, передаваемых в дополнительных полях (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.