Простой PSR-3 логгер в Graylog в формате GELF версии 1.1 по протоколу TCP.
- PHP >= 5.4;
- Произвольный автозагрузчик классов, реализующий стандарт PSR-4, и необходимый когда Composer не используется.
Установка через composer:
$ composer require andrey-tech/graylogger-php:"^1.4"
Класс \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 |
Выполняет логирование с уровнем, заданным параметром $level 3 |
Примечания.
-
Строка идентификатора удовлетворяет регулярному выражению /^[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, запускаемых командой:
$ vendor/bin/phpunit
Для анализа нарушений стандарта кодирования PSR-2 используется PHP CodeSniffer, запускаемый командой:
$ vendor/bin/phpcs --standard=PSR2 src tests examples
© 2021 andrey-tech
Данная библиотека распространяется на условиях лицензии MIT.