LazLogger/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';

Documentation

For more features, see the unit itself and the LCL documentation.

Using LazLogger/LazLoggerBase your code can access the DebugLogger instance. This offers some properties to fine tune logging.

You can also write your own logger class and use it with LazLogger/Base.

Multithreading

• DebugLn is thread safe, since Lazarus 2.0.

Earlier versions of this text stated "since 1.0", but a further race condition was found and fixed for 2.0.

• Calls to DbgOut, DebugLnEnter, DebugLnExit can be made from threads, but may not always format/indent the output correctly.

• The creation/setup/destruction/configuration of the logger is not thread-save, and should be done before threads are started.

Creation is usually done automatically during unit initialization.

But any properties (eg ParamForLogFileName) should be set before accessing the logger from threads.

• Callback to events like OnDebugLn are made in each thread. The code in the callback must be thread save by itself.

Changing the property is NOT thread-save

See also

• TEventLog documentation Built in support for logging in FPC/Lazarus
• DebugServer Allows sending log entries to a viewer via IPC
• MultiLog
• log4delphi
• The package IdeLazLogger, which adds a dialog to the IDE allowing to enable/disable log groups used in the IDE itself.