Bitrix логи ошибок

  Введение

В ядро добавлены логгеры, реализующие интерфейс PSR-3:

• базовый абстрактный класс BitrixMainDiagLogger, реализующий интерфейс PSR-3;
• файловый логгер BitrixMainDiagFileLogger;
• syslog логгер BitrixMainDiagSysLogger.

Логгеры пользуются форматтером логов BitrixMainDiagLogFormatter, который делает замены плейсхолдеров в соответствии с PSR-3.

Примечание: Библиотека доступна с версии main 21.900.0.

  Logger Interface

Интерфейс PsrLogLoggerInterface довольно прост, это — набор функций логирования, поддерживающих уровни логирования. Уровни задаются константами PsrLogLogLevel::*.

interface LoggerInterface
{
    public function emergency($message, array $context = array());
    public function alert($message, array $context = array());
    public function critical($message, array $context = array());
    public function error($message, array $context = array());
    public function warning($message, array $context = array());
    public function notice($message, array $context = array());
    public function info($message, array $context = array());
    public function debug($message, array $context = array());
    public function log($level, $message, array $context = array());
}

В сообщении могут быть {плейсхолдеры}, которые заменяются данными из ассоциативного массива $context.

Также полезным может быть интерфейс PsrLogLoggerAwareInterface, если вы хотите сообщить, что ваш объект готов принять логгер PSR-3:

interface LoggerAwareInterface
{
    public function setLogger(LoggerInterface $logger);
}

  Логгеры в продукте

Логгеры в продукте расширены по сравнению с PSR-3. Можно:

• установить минимальный уровень логирования, ниже которого логгер ничего не выведет,
• установить форматтер.

Файловый логгер BitrixMainDiagFileLogger умеет записывать сообщения в файл, указанный в конструкторе. Если размер лога превышает указанный максимальный, производится однократная ротация файла. Ноль означает не делать ротацию. По умолчанию размер 1 Мб.

$logger = new DiagFileLogger($logFile, $maxLogSize);
$logger->setLevel(PsrLogLogLevel::ERROR);
// выведет в лог
$logger->error($message, $context);
// НЕ выведет в лог
$logger->debug($message, $context);

Syslog логгер BitrixMainDiagSysLogger является надстройкой над функцией php syslog. Конструктор принимает параметры, использующиеся функцией openlog.

$logger = new DiagSysLogger('Bitrix WAF', LOG_ODELAY, $facility);
$logger->warning($message);

На файловый логгер переведена функция AddMessage2Log и класс BitrixMainDiagFileExceptionHandlerLog, а также логирование в модуле Проактивная защита (security).

  Форматирование сообщения

В логгер можно установить форматтер сообщения. По умолчанию используется форматтер BitrixMainDiagLogFormatter, реализующий интерфейс BitrixMainDiagLogFormatterInterface:

interface LogFormatterInterface
{
	public function format($message, array $context = []): string;
}

Конструктор форматтера принимает параметры $showArguments = false, $argMaxChars = 30 (показывать значение аргументов в трейсе, максимальная длина аргумента).

$logger = new MainDiagFileLogger(LOG_FILENAME, 0);
$formatter = new MainDiagLogFormatter($showArgs);
$logger->setFormatter($formatter);

Основная задача форматтера — подставлять значения в плейсхолдеры сообщения из массива контекста. Форматтер умеет обрабатывать определенные плейсхолдеры:

• {date} — текущее время * ;
• {host} — HTTP host * ;
• {exception} — объект исключения (Throwable);
• {trace} — массив бектрейса;
• {delimiter} — разделитель сообщений * .

* — не обязательно передавать в массиве контекста, подставляется автоматически.

$logger->debug(
    "{date} - {host}n{trace}{delimiter}n", 
    [
        'trace' => DiagHelper::getBackTrace(6, DEBUG_BACKTRACE_IGNORE_ARGS, 3)
    ]
);

Значения из массива контекста форматтер старается привести к удобному виду в зависимости от типа значения. Принимаются строки, массивы, объекты.

Использование

В простом виде объект может принять логгер снаружи, поддерживая интерфейс PsrLogLoggerAwareInterface. Можно использовать соответствующий трейт:

use BitrixMainDiag;
use PsrLog;

class MyClass implements LogLoggerAwareInterface
{
	use LogLoggerAwareTrait;
	
	public function doSomething()
	{
	    if ($this->logger)
	    {
	        $this->logger->error('Error!');
	    }
	}
}

$object = new MyClass();
$logger = new DiagFileLogger("/var/log/php/error.log");
$object->setLogger($logger);
$object->doSomething();

Однако, не удобно менять код на работающем проекте, чтобы передать логгер в нужный объект. Для этого в классе логгера предусмотрена своя фабрика. На вход фабрике передается строка-идентификатор логгера:

use BitrixMainDiag;
use PsrLog;

class MyClass implements LogLoggerAwareInterface
{
	use LogLoggerAwareTrait;
	
	public function doSomething()
	{
	    if ($logger = $this->getLogger())
	    {
	        $logger->error('Error!');
	    }
	}

	protected function getLogger()
	{
		if ($this->logger === null)
		{
			$logger = DiagLogger::create('myClassLogger', [$this]);
			$this->setLogger($logger);
		}

		return $this->logger;
	}
}

Настройка

В корневой секции файла .settings.php логгеры указываются в ключе loggers. Синтаксис описания совпадает с настройками ServiceLocator. Отличие состоит в том, что сервис-локатор является реестром, а здесь настраивается фабрика.

В замыкание-конструктор constructor можно передать дополнительные параметры через второй параметр фабрики DiagLogger::create('logger.id', [$this]). Параметры позволяют гибко включать логирование в зависимости от переданных параметров, в том числе вызывать методы самого объекта.

Дополнительно можно указать минимальный уровень журналирования (level) и собственный форматтер (formatter). Форматтер ищется в сервис локаторе по его идентификатору.

// /bitrix/.settings.php
return [
	//...
	'services' => [
		'value' => [
			//...
			'formatter.Arguments' => [
				'className' => 'BitrixMainDiagLogFormatter',
				'constructorParams' => [true],
			],
		],
		'readonly' => true,
	]
	'loggers' => [
		'value' => [
			//...
			'main.HttpClient' => [
//				'className' => '\Bitrix\Main\Diag\FileLogger',
//				'constructorParams' => ['/home/bitrix/www/log.txt'],
//				'constructorParams' => function () { return ['/home/bitrix/www/log.txt']; },
				'constructor' => function (BitrixMainWebHttpClient $http, $method, $url) { 
					$http->setDebugLevel(BitrixMainWebHttpDebug::ALL);
					return new BitrixMainDiagFileLogger('/home/bitrix/www/log.txt');
				},
				'level' => PsrLogLogLevel::DEBUG,
				'formatter' => 'formatter.Arguments',
			],
		],
		'readonly' => true,
	],
	//...
];

При указании замыкания-конструктора constructor желательно использовать файл .settings_extra.php, чтобы не потерять код при сохранении настроек из API.

Существует PsrLogNullLogger, его можно установить, если не хочется писать if($logger) перед каждым вызовом логгера. Однако, следует учитывать, стоит ли делать дополнительную работу по формированию сообщения и контекста.

  Классы

Список классов, поддерживающих фабрику логгеров: