LazLogger/ru

Обзор

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

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

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

Просто подключив модуль 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 (см. Projct Options/Compiler options(Параметры компилятора) /Config and Target (Настройка и целевая платформа)/Target-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.

From the Free Pascal wiki, page "LazLogger/ru", as it stood on 2024-04-14 after a change by N7800, out of the wiki's dump of 2024-05-26. Copyright stays with the author who wrote it, according to the old wiki's Licensing page. If you have concerns about this material, message the admin.