Регистрация

Yii предоставляет мощный и настраиваемый фреймворк для регистрации, который легко расширяется. С помощью этого фреймворка вы можете легко регистрировать различные типы сообщений, фильтровать их и собирать в различных целевых объектах, таких как файлы, базы данных, электронные письма.

Использование фреймворка регистрации Yii включает следующие шаги:

• Запись сообщений журнала в различных местах вашего кода;
• Настройка целевых объектов журнала в конфигурации приложения для фильтрации и экспорта сообщений журнала;
• Просмотр отфильтрованных сообщений журнала, экспортированных различными целевыми объектами (например, отладчиком Yii).

В этом разделе мы в основном опишем первые два шага.

Сообщения журнала

Запись сообщений журнала так же просто, как вызов одного из следующих методов регистрации:

• Yii::trace(): запись сообщения для отслеживания выполнения кода. В основном используется для разработки.
• Yii::info(): запись сообщения, содержащего полезную информацию.
• Yii::warning(): запись предупреждающего сообщения, указывающего на то, что произошло что-то неожиданное.
• Yii::error(): запись критической ошибки, которую следует расследовать как можно скорее.

Эти методы регистрации записывают сообщения журнала на различных уровнях серьезности и категориях. У них одинаковая сигнатура функции function ($message, $category = 'application'), где $message обозначает сообщение журнала для записи, а $category — категория сообщения журнала. Код в следующем примере записывает сообщение отслеживания в стандартной категории application:

Yii::trace('start calculating average revenue');

Информация: Сообщения журнала могут быть строками, а также сложными данными, такими как массивы или объекты. От целевых объектов журнала требуется правильная обработка сообщений журнала. По умолчанию, если сообщение журнала не является строкой, оно будет экспортировано как строка с помощью вызова yii\helpers\VarDumper::export().

Для лучшей организации и фильтрации сообщений журнала рекомендуется указывать соответствующую категорию для каждого сообщения журнала. Вы можете выбрать иерархическую схему наименования категорий, что облегчит целевым объектам журнала фильтрацию сообщений на основе их категорий. Простая и эффективная схема наименования — использовать PHP магическую константу __METHOD__ для имен категорий. Это также подход, используемый в коде ядра Yii.

Yii::trace('start calculating average revenue', __METHOD__);

Константа __METHOD__ вычисляет имя метода (с полным именем класса в качестве префикса), в котором она появляется. Например, она равна строке 'app\controllers\RevenueController::calculate', если приведенная строка кода вызывается в этом методе.

Информация: Методы регистрации, описанные выше, фактически являются сокращениями метода log() объекта объекта логгера, который является синглтоном, доступным через выражение Yii::getLogger(). Когда сообщений достаточно или приложение завершается, объект логгера вызовет диспетчер сообщений, чтобы отправить записанные сообщения журнала в зарегистрированные целевые объекты журнала.

Целевые объекты журнала

Целевой объект журнала — это экземпляр класса yii\log\Target или его дочернего класса. Он фильтрует сообщения журнала по уровням серьезности и категориям, а затем экспортирует их в какой-либо носитель. Например, целевой объект базы данных экспортирует отфильтрованные сообщения журнала в таблицу базы данных, а целевой объект электронной почты экспортирует сообщения журнала указанным адресам электронной почты.

Вы можете зарегистрировать несколько целевых объектов журнала в приложении, настроив их через log компонент приложения в конфигурации приложения, например:

return [
    // the "log" component must be loaded during bootstrapping time
    'bootstrap' => ['log'],
    
    'components' => [
        'log' => [
            'targets' => [
                [
                    'class' => 'yii\log\DbTarget',
                    'levels' => ['error', 'warning'],
                ],
                [
                    'class' => 'yii\log\EmailTarget',
                    'levels' => ['error'],
                    'categories' => ['yii\db\*'],
                    'message' => [
                       'from' => ['log@example.com'],
                       'to' => ['admin@example.com', 'developer@example.com'],
                       'subject' => 'Database errors at example.com',
                    ],
                ],
            ],
        ],
    ],
];

Примечание: Компонент log должен загружаться во время загрузки, чтобы он мог оперативно рассылать сообщения журнала в целевые объекты. Вот почему он указан в массиве bootstrap как показано выше.

В приведенном коде в свойстве yii\log\Dispatcher::$targets зарегистрированы два целевых объекта журнала:

• Первый целевой объект выбирает сообщения об ошибках и предупреждениях и сохраняет их в таблице базы данных;
• Второй целевой объект выбирает сообщения об ошибках в категориях, имена которых начинаются с yii\db\, и отправляет их по электронной почте адресатам admin@example.com и developer@example.com.

Yii предоставляет следующие встроенные целевые объекты журнала. Обратитесь к документации API по этим классам, чтобы узнать, как их настроить и использовать.

• yii\log\DbTarget: сохраняет сообщения журнала в таблице базы данных.
• yii\log\EmailTarget: отправляет сообщения журнала по указанным адресам электронной почты.
• yii\log\FileTarget: сохраняет сообщения журнала в файлах.
• yii\log\SyslogTarget: сохраняет сообщения журнала в syslog, вызывая PHP-функцию syslog().

В дальнейшем мы опишем общие функции всех целевых объектов журнала.

Фильтрация сообщений

Для каждого целевого объекта журнала можно настроить свойства уровней и категорий, чтобы указать, какие уровни серьезности и категории сообщений должен обрабатывать целевой объект.

Свойство уровней принимает массив, состоящий из одного или нескольких следующих значений:

• error: соответствует сообщениям, зарегистрированным с помощью Yii::error().
• warning: соответствует сообщениям, зарегистрированным с помощью Yii::warning().
• info: соответствует сообщениям, зарегистрированным с помощью Yii::info().
• trace: соответствует сообщениям, зарегистрированным с помощью Yii::trace().
• profile: соответствует сообщениям, зарегистрированным с помощью Yii::beginProfile() и Yii::endProfile(), которые будут более подробно описаны в разделе Профилирование.

Если свойство уровней не указано, это означает, что целевой объект будет обрабатывать сообщения любого уровня серьезности.

Свойство категорий принимает массив, содержащий имена категорий сообщений или шаблоны. Целевой объект будет обрабатывать только сообщения, категория которых найдена или соответствует одному из шаблонов в этом массиве. Шаблон категории — это префикс имени категории с звездочкой * в конце. Имя категории соответствует шаблону категории, если оно начинается с того же префикса, что и шаблон. Например, yii\db\Command::execute и yii\db\Command::query используются в качестве имен категорий для сообщений журнала, записанных в классе yii\db\Command. Оба они соответствуют шаблону yii\db\*.

Если свойство категорий не указано, это означает, что целевой объект будет обрабатывать сообщения любой категории.

Помимо перечисления категорий через свойство категорий, вы также можете запретить определенные категории через свойство исключения. Если категория сообщения найдена или соответствует одному из шаблонов в этом свойстве, целевой объект ее не обработает.

Следующая конфигурация целевого объекта указывает, что целевой объект должен обрабатывать только сообщения об ошибках и предупреждениях в категориях, имена которых соответствуют либо yii\db\* или yii\web\HttpException:*, но не yii\web\HttpException:404.

[
    'class' => 'yii\log\FileTarget',
    'levels' => ['error', 'warning'],
    'categories' => [
        'yii\db\*',
        'yii\web\HttpException:*',
    ],
    'except' => [
        'yii\web\HttpException:404',
    ],
]

Информация: Когда HTTP-исключение перехватывается обработчиком ошибок, сообщение об ошибке записывается с именем категории в формате yii\web\HttpException:ErrorCode. Например, yii\web\NotFoundHttpException приведет к сообщению об ошибке категории yii\web\HttpException:404.

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

Целевые объекты журнала экспортируют отфильтрованные сообщения журнала в определенном формате. Например, если вы установите целевой объект журнала класса yii\log\FileTarget, в файле runtime/log/app.log вы можете найти сообщение журнала, подобное следующему:

2014-10-04 18:10:15 [::1][][-][trace][yii\base\Module::getModule] Loading module: debug

По умолчанию, сообщения журнала будут форматироваться целевым объектом yii\log\Target::formatMessage() следующим образом:

Timestamp [IP address][User ID][Session ID][Severity Level][Category] Message Text

Вы можете настроить этот формат, настроив свойство yii\log\Target::$prefix, которое принимает PHP-вызов, возвращающий настраиваемый префикс сообщения. Например, следующий код настраивает целевой объект журнала для добавления префикса к каждому сообщению журнала с текущим идентификатором пользователя (IP-адрес и идентификатор сеанса удалены по соображениям конфиденциальности).

[
    'class' => 'yii\log\FileTarget',
    'prefix' => function ($message) {
        $user = Yii::$app->has('user', true) ? Yii::$app->get('user') : null;
        $userID = $user ? $user->getId(false) : '-';
        return "[$userID]";
    }
]

Помимо префиксов сообщений, целевые объекты журнала также добавляют некоторую контекстную информацию к каждой группе сообщений журнала. По умолчанию включаются значения следующих глобальных PHP-переменных: $_GET, $_POST, $_FILES, $_COOKIE, $_SESSION и $_SERVER. Вы можете настроить это поведение, настроив свойство yii\log\Target::$logVars с именами глобальных переменных, которые вы хотите включить целевым объектом журнала. Например, следующая конфигурация целевого объекта журнала указывает, что только значение переменной $_SERVER будет добавлено к сообщениям журнала.

[
    'class' => 'yii\log\FileTarget',
    'logVars' => ['_SERVER'],
]

Вы можете настроить logVars на пустой массив, чтобы полностью отключить включение контекстной информации. Или, если вы хотите реализовать свой собственный способ предоставления контекстной информации, вы можете переопределить метод yii\log\Target::getContextMessage().

Уровень отслеживания сообщений

Во время разработки часто бывает желательно видеть, откуда исходит каждое сообщение журнала. Это можно сделать, настроив свойство traceLevel компонента log следующим образом:

return [
    'bootstrap' => ['log'],
    'components' => [
        'log' => [
            'traceLevel' => YII_DEBUG ? 3 : 0,
            'targets' => [...],
        ],
    ],
];

Вышеприведённая конфигурация приложения устанавливает traceLevel в 3, если YII_DEBUG включено, и 0, если YII_DEBUG выключено. Это означает, что если YII_DEBUG включено, каждое сообщение журнала будет дополнено не более чем 3 уровнями стека вызовов, в котором было записано сообщение журнала; а если YII_DEBUG выключено, информация о стеке вызовов не будет включена.

Информация: Получение информации о стеке вызовов — нетривиальная задача. Поэтому вы должны использовать эту функцию только во время разработки или при отладке приложения.

Сброс и экспорт сообщений

Как уже упоминалось, сообщения журнала хранятся в массиве объектом объекта logger. Чтобы ограничить потребление памяти этим массивом, logger сбрасывает записанные сообщения в цели логирования каждый раз, когда массив накапливает определённое количество сообщений журнала. Вы можете настроить это число, настроив свойство flushInterval компонента log.

return [
    'bootstrap' => ['log'],
    'components' => [
        'log' => [
            'flushInterval' => 100,   // default is 1000
            'targets' => [...],
        ],
    ],
];

Информация: Сброс сообщений также происходит при завершении приложения, что гарантирует, что цели логирования получат полные сообщения журнала.

Когда объект объект logger сбрасывает сообщения журнала в цели логирования, они не экспортируются немедленно. Вместо этого экспорт сообщений происходит только тогда, когда цель логирования накапливает определённое количество отфильтрованных сообщений. Вы можете настроить это число, настроив свойство exportInterval отдельных целей логирования, как показано ниже,

[
    'class' => 'yii\log\FileTarget',
    'exportInterval' => 100,  // default is 1000
]

Из-за настройки уровней сброса и экспорта, по умолчанию, когда вы вызываете Yii::trace() или любой другой метод логирования, вы НЕ увидите сообщение журнала немедленно в целях логирования. Это может быть проблемой для некоторых долго выполняющихся консольных приложений. Чтобы каждое сообщение журнала появлялось немедленно в целях логирования, вы должны установить как flushInterval, так и exportInterval в 1, как показано ниже:

return [
    'bootstrap' => ['log'],
    'components' => [
        'log' => [
            'flushInterval' => 1,
            'targets' => [
                [
                    'class' => 'yii\log\FileTarget',
                    'exportInterval' => 1,
                ],
            ],
        ],
    ],
];

Примечание: Частый сброс и экспорт сообщений негативно повлияют на производительность вашего приложения.

Включение/выключение целей логирования

Вы можете включить или отключить цель логирования, настроив её свойство enabled. Вы можете сделать это через конфигурацию цели логирования или с помощью следующей PHP-команды в вашем коде:

Yii::$app->log->targets['file']->enabled = false;

Приведённый выше код требует, чтобы вы назвали цель как file, как показано ниже, используя строковые ключи в массиве targets:

return [
    'bootstrap' => ['log'],
    'components' => [
        'log' => [
            'targets' => [
                'file' => [
                    'class' => 'yii\log\FileTarget',
                ],
                'db' => [
                    'class' => 'yii\log\DbTarget',
                ],
            ],
        ],
    ],
];

Создание новых целей

Создание нового класса цели логирования очень просто. Вам в основном нужно реализовать метод yii\log\Target::export(), отправляя содержимое массива yii\log\Target::$messages в назначенное средство. Вы можете вызвать метод yii\log\Target::formatMessage() для форматирования каждого сообщения. Более подробную информацию можно найти в любом из классов целей логирования, включённых в выпуск Yii.

Подсказка: Вместо создания собственных логгеров, вы можете попробовать любой совместимый с PSR-3 логгер, такой как Monolog, используя расширение цели логирования PSR.

Профилирование производительности

Профилирование производительности — это особый тип логирования сообщений, используемый для измерения времени, затрачиваемого определёнными блоками кода, и выявления узких мест в производительности. Например, класс yii\db\Command использует профилирование производительности для определения времени, затрачиваемого на каждый запрос к базе данных.

Чтобы использовать профилирование производительности, сначала определите блоки кода, которые нужно проанализировать. Затем заключите каждый блок кода следующим образом:

\Yii::beginProfile('myBenchmark');

...code block being profiled...

\Yii::endProfile('myBenchmark');

где myBenchmark обозначает уникальный токен, идентифицирующий блок кода. Позже, когда вы будете изучать результаты профилирования, вы будете использовать этот токен, чтобы найти время, потраченное соответствующим блоком кода.

Важно убедиться, что пары beginProfile и endProfile правильно вложены. Например,

\Yii::beginProfile('block1');

    // some code to be profiled

    \Yii::beginProfile('block2');
        // some other code to be profiled
    \Yii::endProfile('block2');

\Yii::endProfile('block1');

Если вы пропустите \Yii::endProfile('block1') или измените порядок \Yii::endProfile('block1') и \Yii::endProfile('block2'), профилирование производительности не будет работать.

Для каждого проанализированного блока кода записывается сообщение журнала со степенью серьёзности profile. Вы можете настроить цель логирования для сбора таких сообщений и их экспорта. Отладчик Yii имеет встроенную панель профилирования производительности, отображающую результаты профилирования.