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

From Joomla! Documentation

Revision as of 08:23, 16 January 2019 by B2z (talk | contribs)
Other languages:

Обзор

Логирование в 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, still
           // we 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')
   );

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

   {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.

Другое руководство (немного устаревшее, но все же полезное) находится по адресу Logging in Joomla with JLog.

Retrieved from "https://docs.sandbox.joomla.org/index.php?title=Using_JLog/ru&oldid=587381"