Using JLog/ru

Обзор

Логирование в Joomla дает вам возможность логировать сообщения в файлы и на экран (в консоли отладки Joomla внизу веб-страницы), а основным классом Joomla, который для этого используется, является JLog.

Логирование, в некоторой степени, может контролироваться динамически через общие настройки Joomla и путем настройки плагина «Система - Отладка» (поставляется с Joomla). В целом эти возможности позволяют вам:

• включать или отключать систему отладки - чтобы вы не потребляли ресурсы без необходимости, но при этом у вас оставалась информация для того, чтобы помочь в устранении неполадок, когда есть проблемы. Например, на живом сайте, на котором установлено ваше расширение.
• направлять сообщения логов в определенный файл логов вашего собственного расширения
• просматривать сообщения логов в консоли отладки - вы можете выбрать группу пользователей, для которых должны отображаться сообщения логов, чтобы на живом сайте разработчики могли видеть сообщения, в то время как другие пользователи не затрагивались.
• фильтровать сообщения консоли отладки по приоритету (например, INFO, DEBUG, WARNING и т. д.) и по категориям (вы можете сами определять свои категории).

Кроме того, сообщения логов могут быть переведены на разные языки.

Основные параметры конфигурации, относящиеся к ведению логов, показаны ниже.

Включение отладки и отображение консоли отладки Joomla контролируется через общие настройки.

Логирование в общий файл логов контролируется с помощью вкладки Журнал (логи) конфигурации плагина Joomla «Система - Отладка» (в меню администратора нажмите «Расширения / Плагины», найдите плагин «Система - Отладка» и нажмите на него, чтобы изменить его параметры).

Параметры на вкладке "Плагин" контролируют отображение в консоли отладки Joomla.

Базовое логирование в файл

Чтобы отправить сообщение в лог, используйте функцию JLog::add(). Например:

JLog::add('my error message', JLog::ERROR, 'my-error-category');

Параметры

1. Строка сообщения. Вы можете использовать перевод, например, JText::_('MY_EXTENSION_ERR_MSG'). Вы также можете отображать значения переменных при условии, что вы конвертируете их в строковый формат (например, с помощью __toString (), если тип переменной это поддерживает).
2. Приоритет, который может быть одним из: JLog::EMERGENCY, JLog::ALERT, JLog::CRITICAL, JLog::ERROR, JLog::WARNING, JLog::NOTICE, JLog::INFO, JLog::DEBUG (основано на уровнях серьёзности syslog / RFC 5424 – подробнее в материале Wikipedia о syslog).
3. Категория, которая является просто текстовой строкой. Вы можете определить любые категории, которые вам нравятся. Лучше всего определять их, чтобы избежать возможных конфликтов с другими расширениями.

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

if (JDEBUG)
{
    JLog::add('my debug message', JLog::DEBUG, 'my-debug-category');
}

Логирование в определённый файл логов

Вы можете использовать JLog::addLogger(), чтобы настроить ведение логов в дополнительный файл логов, отфильтровывая сообщения логов по приоритету (уровень серьезности) и / или категории. Параметры JLog::addLogger():

1. массив с деталями конфигурации - включая имя файла логов
2. уровни серьезности, которые будут логироваться в этом файле
3. массив категорий, которые будут логироваться в этом файле (или если для параметра 4 установлено значение true, тогда этот массив определяет категории, которые НЕ должны регистрироваться в файле)
4. (часто пропускается) логическое значение, указывающее, является ли параметр 3 списком включения (по умолчанию P4 = false) или списком исключения (P4 = true)

Например, если вы разработали расширение 'com_helloworld', вы можете использовать следующее:

JLog::addLogger(
    array(
         // Sets file name
         'text_file' => 'com_helloworld.log.php'
    ),
    // Sets messages of all log levels to be sent to the file.
    JLog::ALL,
    // The log category/categories which should be recorded in this file.
    // In this case, it's just the one category from our extension.
    // We still need to put it inside an array.
    array('com_helloworld')
);

Затем, когда вы логируете сообщение, укажите категорию 'com_helloworld', как в примере ниже

JLog::add(JText::_('COM_HELLOWORLD_ERROR_MESSAGE_123'), JLog::ERROR, 'com_helloworld');

Это приведет к тому, что ваше сообщение будет записано в com_helloworld.log.php. Если в настройках плагина «Система - Отладка» для параметра «Протоколировать все» задано значение «Да», то это сообщение появится и в общем файле журнала everything.php.

Примечание: Вы можете объединить это с Display error messages and notices для отображения видимых уведомлений об ошибках для пользователей.

Вы также можете добавить дополнительный логгер для сбора только критических и аварийных уведомлений:

JLog::addLogger(
    array(
         // Sets file name.
         'text_file' => 'com_helloworld.critical_emergency.php'
    ),
    // Sets critical and emergency log level messages to be sent to the file.
    JLog::CRITICAL + JLog::EMERGENCY,
    // The log category which should be recorded in this file.
    array('com_helloworld')
);

Вы также можете исключить определенный уровень приоритета от включения в файл логов. Например, чтобы логировать все сообщения кроме DEBUG:

JLog::addLogger(
    array(
         // Sets file name.
         'text_file' => 'com_helloworld.all_but_debug.php'
    ),
    // Sets all but DEBUG log level messages to be sent to the file.
    JLog::ALL & ~JLog::DEBUG,
    // The log category which should be recorded in this file.
    array('com_helloworld')
);

Уровни приоритета JLog реализованы в виде отдельных битов целого числа, поэтому вы можете использовать побитовые операции (побитовое AND, &; и побитовое NOT, ~) для вычисления подходящих уровней логов. JLog::All является постоянным целым числом, в котором установлены все соответствующие биты, поэтому включены все уровни приоритета Joomla.

Форматирование файла логов

Первый параметр addLogger может иметь несколько необязательных дополнительных настроек в дополнение к параметру text_file.

Например, есть параметр text_entry_format, указывающий формат каждой строки в вашем лог файле.

Формат по умолчанию:

   '{DATETIME} {PRIORITY}      {CATEGORY}      {MESSAGE}'

Вот пример другого формата, который показывает, как пропустить категорию:

JLog::addLogger(
    array(
         // Sets file name.
         'text_file' => 'com_helloworld.critical_emergency.php',
         // Sets the format of each line.
         'text_entry_format' => '{DATETIME} {PRIORITY} {MESSAGE}'
    ),
    // Sets all but DEBUG log level messages to be sent to the file.
    JLog::ALL & ~JLog::DEBUG,
    // The log category which should be recorded in this file.
    array('com_helloworld')
);

Помимо заполнителей (placeholders), показанных выше в строке по умолчанию, доступны следующие значения:

   {CLIENTIP}      (this is the IP address of the client)
   {TIME}
   {DATE}

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

   #
   #<?php die('Forbidden.');?>

Примечание: Обычно вам не следует устанавливать для этого параметра значение false. Файлы логов не должны быть доступны для чтения извне, поскольку они могут предоставить злоумышленникам ценную информацию о вашей системе. Изменяйте этот параметр, только если вы знаете, что делаете!

Кроме того, если вы хотите сохранить файл логов где-то еще, а не по пути, указанному в общих настройках Joomla, вы можете изменить параметр text_file_path.

Логирование в другие места

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

• область сообщений Joomla (сообщение отображается, если вы вызываете JFactory::getApplication()->enqueueMessage())
• таблица базы данных
• просто echo

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

    JLog::addLogger(array('logger' => 'messagequeue'), JLog::ALL, array('msg-error-cat'));

Затем, когда вы делаете:

    JLog::add('сообщение об ошибке для отображения', JLog::ERROR, 'msg-error-cat');

вы получаете сообщение, скопированное на панель сообщений.

Обратите внимание, что код ядра Joomla настраивает запись в очередь сообщений для категории 'jerror', поэтому, если вы используете эту категорию в своих сообщениях журнала, вы получите сообщение, отображаемое на панели сообщений.

Например:

    JLog::add ('ошибка скопирована на панель сообщений', JLog::ERROR, 'jerror');

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

Исключения

JLog::add() кидает исключение, если не может записать в файл логов. Чтобы избежать этого, вам придется либо обернуть вызов в другую функцию, либо реализовать свой собственный класс логгера, а затем включить его:

JLog::addLogger(
    array(
         // Use mycustomlogger.
         'logger' => 'mycustomlogger',
         'text_file' => 'com_helloworld.errors.php'
    ),
    JLog::ALL,
    array('com_helloworld')
);

Что ещё почитать

Логирование в Joomla должно использоваться в тандеме с исключениями PHP, а не в качестве замены. Подробнее в Exceptions and Logging in Joomla 1.7 and Joomla Platform 11.1.