LazLogger/ru

From Free Pascal wiki

English (en)русский (ru)


Обзор

Модуль LazLogger поставляется с Lazarus и обеспечивает ведение журнала в файл.

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

Добавление поддержки логирования в ваш исходный код

(По историческим причинам некоторые части также доступны через LclProc (удалено, начиная с Lazarus 1.10); этот доступ может быть удален в будущем)

Просто подключив модуль lazlogger, вы сможете использовать следующее:

  • DebugLn: который работает примерно так же, как WriteLn.
  • DebugLnEnter/DebugLnExit: так же, как debugln, но с отступом увеличить/уменьшить.
  • DbgOut: который работает примерно так же, как Write.

Все они могут быть вызваны с помощью:

  • Одной строки или списка (до 15) строк: DebugLn('Foo'); DbgOut('a','b');
  • Массива констант: DebugLn(['Foo=', 1, ' Bar=', anInteger]);
  • Тех же аргументов, что и Format(). String + array of const: DbgOut('a %d',[1]);

Также есть множество функций dbgs, которые преобразуют общие типы в строку. Например, dbgs(aRect) преобразует переменную типа TRect в строку.

Активация/Деактивация LazLogger при помощи использования правильного модуля

LazLogger предоставляет 3 модуля для использования в разделе "uses"

LazLogger
Используйте этот модуль только в вашей основной программе. Использование этих модулей активирует функционирование LazLogger.
LazLoggerBase
Используйте этот модуль, когда вы хотите использовать debugln. То, что делает LazLoggerBase, зависит от того, используется ли модуль LazLogger в каком-либо другом модуле вашего приложения. Если модуль LazLogger не используется, LazLoggerBase установит «логгер черной дыры», который отбросит все сообщения журнала. Если LazLogger используется где-либо, то все устройства, использующие LazLoggerBase, будут записывать сообщения журнала, как описано в разделе «Вывод логирования»
LazLoggerDummy
Этот модуль предоставляет вам фиктивные вызовы debugln (и всех других функций LazLagger). Это просто вызовы пустых методов. Это позволяет отключить все журналы в модуле, без необходимости удалять любой оператор debugln.

Вывод логирования

Stdout (Стандартный вывод)

В нормальных условиях выходные данные записываются в stdout. Выходные данные не записываются, если stdout закрыт - например, когда приложение имеет вид {$AppType Gui} или скомпилировано с -WG в Windows (см. Compiler options(Параметры компилятора) / Linking(Связывание) / Target OS specific options(Параметры, специфичные для целевой ОС)).

Файл

Вывод отладки также может быть записан в файл. Код инициализации модуля логирования

  • проверяет параметры командной строки вашей программы на --debug-log=<file> (в Lazarus: Run(Запуск) / Run Parameters(Параметры запуска) / Command line parameters(Параметры командной строки) - на вкладка "Локальные"). При нахождении этого параметра любые последующие выходные данные отладки отправляются в <file>.
Имя параметра можно изменить с помощью DebugLogger.ParamForLogFileName:'--debug-log'; Это свойство существует, только если используется модуль LazLogger. (LazLoggerBase не определяет это свойство).
  • Если параметр командной строки '--debug-log' не задан, он затем проверяет, существует ли переменная среды операционной системы xxx_debuglog, где xxx - имя файла программы без расширения. Например, для Lazarus это будет lazarus_debuglog. Если такая переменная среды существует, она использует файл, указанный в этой переменной среды, в качестве файла для получения отладочной информации.

Пример: если вы cделаете:

set lazarus_debuglog=c:\lazarus\debug.txt

и запустите Lazarus, вывод данных отладки будет записан в c:\lazarus\debug.txt.

Сервер отладки

Недоступно в LazLogger; см. DebugServer.

Группы журналов

Вы можете добавить группы журналов.

var MY_LOG_GROUP: PLazLoggerLogGroup; 

initialization
  MY_LOG_GROUP := DebugLogger.FindOrRegisterLogGroup('fancy_name_for_mylog' {$IFDEF MY_LOG_GROUP_ON_BY_DEFAULT} , True {$ENDIF} );

В вашем коде используйте

debugln(MY_LOG_GROUP, 'log this text');
debugln(MY_LOG_GROUP, ['a=',a,' b=',b]); // a, b должны быть базовыми типами: integer, byte, ansistring. Смотрите типы, доступные для "array of const"

и чтобы включить его, вызовите ваше приложение с

--debug-enable=fancy_name_for_mylog

--debug-enable= принимает список [значений, разделенных] запятой

Уже активированную группу (DebugLogger.FindOrRegisterLogGroup('grpname', True)) можно отключить, указав имя группы со знаком минус.

--debug-enable=-fancy_name_for_mylog

Имя параметра может быть установлено через DebugLogger.ParamForEnabledLogGroups='--debug-enable';

Документация

Для получения дополнительной информации см. сам модуль и документацию LCL.

Используя LazLogger/LazLoggerBase, ваш код может получить доступ к экземпляру DebugLogger. Это предлагает некоторые свойства для точной настройки логирования.

Вы также можете написать свой собственный класс логгера и использовать его с LazLogger/Base.

Многопоточность

  • DebugLn потокобезопасен, начиная с Lazarus 2.0.
В более ранних версиях этого текста было указано «начиная с 1.0», но было найдено и исправлено еще одно условие для 2.0.
  • Вызовы DbgOut, DebugLnEnter, DebugLnExit могут быть сделаны из потоков, но не всегда могут правильно форматировать/делать отступ в выходных данных.
  • Создание/настройка/уничтожение/конфигурирование логгера - это НЕпотокобезопасные операции и должны быть сделаны до запуска потоков.
Создание обычно выполняется автоматически во время инициализации устройства.
Но любые свойства (например, ParamForLogFileName) должны быть установлены до доступа к логгеру из потоков.
  • Обратный вызов для таких событий, как OnDebugLn, производится в каждом потоке. Код в обратном вызове должен быть сам по себе потокобезопасным.
Изменение свойства является НЕпотокобезопасным

См.также

  • TEventLog documentation Встроенная поддержка входа в FPC/Lazarus
  • DebugServer Позволяет отправлять записи журнала наблюдателю через IPC
  • MultiLog
  • log4delphi
  • Пакет IdeLazLogger, который добавляет в IDE диалог, позволяющий включать/отключать группы журналов, используемые в самой IDE.