GrayLogger PHP

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

Содержание
Требования
- 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 |
|
Примечания.
-
Строка идентификатора удовлетворяет регулярному выражению /^[a-z0-9]+$/. Допустимая длина идентификатора: 0-36 символов, по умолчанию - 7 символов.
-
В параметре $message передается сообщение, которое должно быть строкой в кодировке UTF-8 или объектом, реализующим метод __toString().
Сообщение может содержать плейсхолдеры в виде {foo}, где foo будет заменено на значение элемента массива сопутствующих данных, передаваемых в параметре $context с ключом foo.
Сообщение передается в поле short_message GELF.
Параметр $context может содержать массив сопутствующих данных в кодировке UTF-8, передаваемых в дополнительных полях (additional field) GELF.
-
Возможные значения параметра $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, запускаемых командой:
Анализ кода
Для анализа нарушений стандарта кодирования PSR-2 используется PHP CodeSniffer,
запускаемый командой:
$ vendor/bin/phpcs --standard=PSR2 src tests examples
Автор
© 2021 andrey-tech
Лицензия
Данная библиотека распространяется на условиях лицензии MIT.