Оглавление

Monolog
Особенности применения в Magento 2
Реализация
Запись лога при помощи стандартного логгера
Запись лога при помощи стандартного логгера с кастомным каналом
Запись в кастомный файл при помощи собственного хендлера
Запись в кастомный файл при помощи virtualType
Быстрое логирование данных
Заключение

Monolog

use Monolog\Logger;
use Monolog\Handler\StreamHandler;
use Monolog\Formatter\HtmlFormatter;

// Создаем логгер с именем "name"
$log = new Logger('name');

// Добавляем хендлер, который будет писать логи в "path/to/your1.log" и слушать все ошибки с уровнем "WARNING" и выше (notice, info и debug не будут записаны).
$log->pushHandler(new StreamHandler('path/to/your1.log', Logger::WARNING));

// Добавляем хендлер, который будет писать логи в "path/to/your2.log" и реагировать на ошибки с уровнем "ALERT" и выше (т.е. будет писать ошибки только если их уровень alert или emergency). Будет блокировать остальные хендлеры, если этот был применен. Текст добавленный в лог файл будет отформатирован в html при помощи HtmlFormatter.
$log->pushHandler(new StreamHandler('path/to/your2.log', Logger::ALERT,false)
->setFormatter(new HtmlFormatter));

// Добавляем процессор, который добавляет ко всем записям дополнительную информацию.
$log->pushProcessor(function ($record) {
    $record['extra']['dummy'] = 'Hello world!';

    return $record;
});

// Добавляем записи
$log->warning('Foo');
$log->error('Bar',['test']);
$log->info('Test'); // не будет записан, так как ни 1 из хендлеров не слушает INFO

//your1.log
// [2019-08-12 02:57:52] name.WARNING: Foo [] ['extra'=>['dummy'=>'Hello world!']]
// [2019-08-12 02:57:53] name.ERROR: BAR ['test'] ['extra'=>['dummy'=>'Hello world!']]

//your2.log
// пустой, т.к не было ошибок ALERT и EMERGENCY

• Logger — это объект, который мы используем для записи логов. Сам логгер не занимается записью, но управляет хендлерами. Может быть создано любое количество.
• Handler — объект, который непосредственно обрабатывает данные. Вы можете добавить сколько угодно хендлеров в логгер. Все они будут вызываться по очереди, независимо от того смог данный хендлер обработать ошибку или нет. Метод isHandling определяет сможет ли этот хендлер обработать поступившую ошибку.
  
  

  public function isHandling(array $record)
  {
          return $record['level'] >= $this->level;
  }
  

  
  Самое близкое сходство с хендлером, с моей точки зрения, это Event Observer.
  
• Processor — любая вызываемая сущность (callable). Может быть несколько. Могут быть назначены как глобально, так и установлены для хендлера. Сначала запускаются глобальные процессоры. Основная задача процессора добавить дополнительные данные в лог (например IP, с которого был коннект, значение глобальных переменных, информация на какой git ветке сейчас находится код и так далее).
• Formatter — преобразует вывод сообщения перед записью. Может быть только 1 на хендлер. Нужен для изменения форматирования тела сообщения, например для преобразования текста в html или json.
• Channel — имя логгера. Оно будет написано при записи лога. Так как 1 хендлер может быть применен в 2ух разных логгерах (будет писать логи в 1 и тот же файл) это позволит определить откуда пришла ошибка.
• Level — уровень ошибки. Данный параметр у хендлера означает минимальный уровень ошибки, который будет им обрабатываться.
• Bubble — всплытие сообщения. После того, как хендлер обработал сообщение, то логгер передает сообщение следующему хендлеру. Этот процесс можно остановить с помощью свойства bubble. Если у хендлера значение этого свойства false (по умолчанию всегда true), то после того как этот хендлер выполнит свою работу (смог обработать данную ошибку), другие хендлеры уже не запустятся.
• Sort Order — порядок выполнения. Последний добавленный хендлер всегда запускается самым первым. Именно эта особенность позволяет внедрять механизм полного отключения логгера (через bubbling false). Хендлеры добавленные через конструктор идут в порядке указанном в конструкторе.

Так как PSR-3 не обязывает разработчиков реализовывать автозамену значений в тексте, то по умолчанию Monolog этого не делает. Если вы напишите ->emerg('test 1111 {placeholder}', ['placeholder'=> 'foo']) то получите следующее
[2019-08-12 02:57:52] main.EMERGENCY: test 1111 {placeholder} {«placeholder»:«foo»} []

Чтобы замена работала вам необходимо подключить дополнительный процессор — \Monolog\Processor\PsrLogMessageProcessor.

Особенности применения в Magento 2

2019-08-12T01:00:27+00:00 DEBUG (7): ALARM!

[2019-08-12 02:56:43] main.INFO: ALARM! [] []

Если такого свойства (_logger или logger) нет у объекта, тогда нам понадобится сначала добавить в ваш класс зависимость \Psr\Log\LoggerInterface и записать полученный объект в свойство $logger (согласно PSR-2 пункту 4.2 и примеру, представленному на сайте Magento).

$this->_logger->{level}($message, $context = []);
//$this->_logger->log('{level}', $message, $context = []);

public function commit()
{
     $this->getConnection()->commit();
 
      if ($this->getConnection()->getTransactionLevel() === 0) {
          $callbacks = CallbackPool::get(spl_object_hash($this->getConnection()));
          try {
                foreach ($callbacks as $callback) {
                    call_user_func($callback);
                }
            } catch (\Exception $e) {
                $this->getLogger()->critical($e);
            }
        }
    return $this;
}

…
private function getLogger()
{
     if (null === $this->_logger) {
         $this->_logger = ObjectManager::getInstance()->get(\Psr\Log\LoggerInterface::class);
     }
     return $this->_logger;
}

…
<preference for="Psr\Log\LoggerInterface" type="Magento\Framework\Logger\Monolog" />
...
<type name="Magento\Framework\Logger\Monolog">
    <arguments>
        <argument name="name" xsi:type="string">main</argument>
        <argument name="handlers" xsi:type="array">
            <item name="system" xsi:type="object">Magento\Framework\Logger\Handler\System</item>
            <item name="debug" xsi:type="object">Magento\Framework\Logger\Handler\Debug</item>
            <item name="syslog" xsi:type="object">Magento\Framework\Logger\Handler\Syslog</item>
        </argument>
    </arguments>
</type>
...

...
public function write(array $record)
    {
        if (isset($record['context']['exception'])) {
            $this->exceptionHandler->handle($record);

            return;
        }

        $record['formatted'] = $this->getFormatter()->format($record);

        parent::write($record);
    }
...

В Magento 2 до 2.2 была проблема связанная с тем, что логгер не мог перепрыгивать на другой хендлер после первого найденного. Данная проблема была вызвана тем, что Monolog рассчитывал что к нему все хендлеры приходят в массиве с цифровыми ключами, а приходили с буквенными (['system'=>,'debug'=>,...]). Разработчики Magento позже исправили ситуацию — они преобразуют хеш в обычный массив с цифровыми ключами прежде чем передать его в Monolog. Monolog сейчас так же изменил алгоритм перебора хендлеров и использует метод next().

Реализация

1. Запись лога при помощи стандартного логгера

class RandomClass
{
    private $logger;

    public function __construct(\Psr\Log\LoggerInterface $logger)
    {
         $this->logger = $logger;
    }

    public function foo()
    {
         $this->logger->info('Something went wrong');
         //[...some date...] main.INFO: Something went wrong [] []
    }
}

…
$this->_logger->info('Something went wrong'); // можно использовать метод ->debug, если вы хотите, чтобы сообщение писалось только в debug.log
...

2. Запись лога при помощи стандартного логгера с кастомным каналом

class RandomClass
{
    private $logger;

    public function __construct(\Psr\Log\LoggerInterface $logger)
    {
         $this->logger = $logger->withName('api'); //может быть любое имя
    }

    public function foo()
    {
         $this->logger->info('Something went wrong');
         //[...some date...] api.INFO: Something went wrong [] []
    }
}

grep -rn 'api' var/log/system.log

3. Запись в кастомный файл при помощи собственного хендлера

<?php
namespace Oxis\Log\Logger\Handler;

use Magento\Framework\Filesystem\DriverInterface;
use Magento\Framework\Logger\Handler\Base;
use Monolog\Logger;

class Test extends Base
{
    protected $fileName = 'var/log/critical.log';

    protected $loggerType = Logger::CRITICAL;
    public function __construct(DriverInterface $filesystem)
    {
          parent::__construct($filesystem,null,null);
          $this->bubble = false; //так же можно и через метод setBubble()
    }
}

В Magento 2 2.2+ в конструкторе \Magento\Framework\Logger\Handler\Base изменился способ обработки пути до файла с логом

//было
BP . $this->fileName
//стало
BP. DIRECTORY_SEPARATOR . $this->fileName

Поэтому в старых хендлерах вы все еще можете найти / в начале $fileName.

use Oxis\Log\Logger\Handler\Test;
use Psr\Log\LoggerInterface;

class RandomClass
{
    private $logger;

    public function __construct(
        LoggerInterface $logger,
        Test $handler
    ) {
         $logger->pushHandler($handler); //можно использовать setHandlers([$handler]), тогда все остальные хендлеры будут заменены нашим хендлером.
         $this->logger = $logger;
    }

    public function foo()
    {
         $this->logger->critical('Something went wrong'); // запись будет добавлена только в critical.log
         //[...some date...] main.CRITICAL: Something went wrong [] []
    }
}

4. Запись в кастомный файл при помощи virtualType

В Magento 2 2.2+ был добавлен новый параметр в конструктор \Magento\Framework\Logger\Handler\Base, что позволяет создавать виртуальный хендлер и указывать через di.xml относительный путь до файл для записи лога. Ранее требовалось либо указывать полный путь через $filePath, либо создавать новый хендлер и записывать относительный путь в протектед свойство $fileName.

     <!--Создаем виртуальный хендлер и указываем ему файл, в который будем писать логи-->
     <virtualType name="ApiHandler" type="Magento\Framework\Logger\Handler\Base">
        <arguments>
            <argument name="fileName" xsi:type="string">var/log/api.log</argument>
        </arguments>
    </virtualType>
   
   <!--Создаем виртуальный логгер, в который добавляем наш хендлер-->
    <virtualType name="ApiLogger" type="Magento\Framework\Logger\Monolog">
        <arguments>
            <argument name="name" xsi:type="string">api</argument>
            <argument name="handlers" xsi:type="array">
                <item name="default" xsi:type="object">ApiHandler</item>
            </argument>
        </arguments>
    </virtualType>

   <!--Добавляем в наш класс только что созданный логгер-->
    <type name="Oxis\Log\Model\A">
        <arguments>
            <argument name="logger" xsi:type="object">ApiLogger</argument>
        </arguments>
    </type>

namespace Oxis\Log\Model;

class A
{
    private $logger;

    public function __construct(\Psr\Log\LoggerInterface $logger)
    {
         $this->logger = $logger;
    }

    public function foo()
    {
         $this->logger->info('Something went wrong');
    }
}

<virtualType name="ApiHandler" type="Magento\Framework\Logger\Handler\Base">
        <arguments>
            <argument name="fileName" xsi:type="string">var/log/api.log</argument>
        </arguments>
</virtualType>
<virtualType name="ApiLogger" type="Magento\Framework\Logger\Monolog">
        <arguments>
            <argument name="name" xsi:type="string">api</argument>
            <argument name="handlers" xsi:type="array">
                <item name="default" xsi:type="object">ApiHandler</item>
            </argument>
        </arguments>
</virtualType>

<!--Создаем виртуальный контекст и подменяем в нем logger-->
 <virtualType name="ApiLogContainingContext" type="Magento\Framework\Model\Context">
        <arguments>
            <argument name="logger" xsi:type="object">ApiLogger</argument>
        </arguments>
</virtualType>

<!--Заменяем контекст в нашем классе-->
<type name="Oxis\Log\Model\A">
        <arguments>
            <argument name="context" xsi:type="object">ApiLogContainingContext</argument>
        </arguments>
</type>

5. Быстрое логирование данных

...
$log = new \Monolog\Logger('custom', [new \Monolog\Handler\StreamHandler(BP.'/var/log/custom.log')]);
$log->error('test');
...

...
file_put_contents(BP.'/var/log/custom.log', 'test',FILE_APPEND);
...

Заключение