Логирование в Creatio. NLog

Общие сведения

Для проверки корректности работы новой функциональности, мы рекомендуем включить логирование. Чтобы избежать ухудшения производительности, рекомендуется включать логирование только при тестировании и отладке приложения. В Creatio выполняется логирование всех основных операций. Для этого используется NLog — бесплатная библиотека логирования для .NET с широкими возможностями маршрутизации и управления высококачественными логами для приложения, независимо от его размера или сложности. Библиотека может обрабатывать диагностические сообщения, отправляемые с любого языка .NET, дополнять контекстной информацией, форматировать в соответствии с предпочтениями пользователя и отправлять одному или нескольким получателям сообщений, таким как файл или база данных.

Логирование ведется отдельно для загрузчика приложения и для конфигурации Default. Настройки логирования выполняются в каталоге ..\Terrasoft.WebApp в следующих конфигурационных файлах:

• nlog.config.
• nlog.targets.config.
• nlog.cloud.config (для приложений, развернутых в облаке).
• nlog.cloud.settings.config (для приложений, развернутых в облаке).

Логирование для приложений on-site

Хранение логов

По умолчанию файлы с логами загрузчика сохраняются по адресу:

[TEMP]\Creatio\Site_[{SiteId}]\[{ApplicationName}]\Log\[{DateTime.Today}]

Например:

C:\Windows\Temp\Creatio\Site_1\сreatio7121\Log\2018_05_22

Файлы с логами конфигурации Default сохраняются по адресу:

[TEMP]\Creatio\Site_[{SiteId}]\[{ApplicationName}]\[ConfigurationNumber]\Log\[{DateTime.Today}]

Например:

C:\Windows\Temp\Creatio\Site_1\сreatio7121\0\Log\2018_05_22

В приведенных выше примерах в квадратных скобках указаны следующие переменные:

• [TEMP] — базовый каталог. По умолчанию для IIS используется каталог C:\Windows\Temp, а для Visual Studio (IIS Express) — C:\Users\{Имя пользователя}\AppData\Local\Temp.
• [{SiteId}] — номер сайта. Для IIS указан в расширенных настройках сайта (рис. 1). Для Visual Studio номер содержит значение 2.
• [{ApplicationName}] — название приложения (рис. 1).
• [ConfigurationNumber] — номер конфигурации. Конфигурация Default, как правило, имеет номер 0.
• [{DateTime.Today}] — дата логирования.

Рис. 1. — Расширенные настройки сайта в IIS

Настройка логирования

Логирование можно настраивать следующими способами:

• через конфигурационный файл;
• через конфигурационный объект LoggingConfiguration.

Настройка логирования через конфигурационный файл

1. Задать путь к файлу с настройками логирования

Путь к файлу nlog.config задается в конфигурационном файле ..\Terrasoft.WebApp\Web.config.

<common>
    <logging>
      <factoryAdapter type="Common.Logging.NLog.NLogLoggerFactoryAdapter, Common.Logging.NLog45">
        <arg key="configType" value="FILE" />
        <arg key="configFile" value="~/nlog.config" />
      </factoryAdapter>
    </logging>
  </common>

2. Задать получателей логирования

Получатели логирования используются для отображения, хранения или передачи сообщений лога другому получателю. Есть получатели, которые получают и обрабатывают сообщения и те, которые буферизируют или направляют сообщения другому получателю.

Получатели логирования задаются в файле nlog.targets.config с помощью следующих атрибутов:

• name — имя получателя.
• xsi:type — тип получателя. Может принимать значения "File", "Database", "Mail".
• fileName — файл и путь к файлу, куда будут записываться логи.
• layout — шаблон, по которому будет заполняться файл.

Получатели логирования подробно описаны в документации NLog.

Пример. Настроить получателя логирования

Для этого необходимо в XML-элементе <target> файла ..\Terrasoft.WebApp\nlog.targets.config определить свойства получателя логирования.

<target name="universalAppender" xsi:type="File"
    layout="${DefaultLayout}"
    fileName="${LogDir}${LogDay}${logger:shortName=True}.log" />

3. Задать правило логирования

Правила логирования устанавливаются в файле nlog.config с помощью следующих атрибутов:

• name — имя лога.
• minlevel — минимальный уровень логирования.
• maxlevel — максимальный уровень логирования.
• level — логирование событий одного уровня логирования.
• levels — логирование событий нескольких уровней логирования (записываются через запятую).
• writeTo — имя получателя логирования.
• final — после совпадения окончательного правила правила не обрабатываются.
• enabled — отключить правило (установить в значение false), не удаляя его.
• ruleName — идентификатор правила.

Уровни логирования устанавливаются в файле nlog.config. По умолчанию уровень логирования для всех компонентов Creatio установлен таким образом, чтобы обеспечить максимальную производительность приложения. Возможные уровни логирования в порядке возрастания приоритета:

• Trace — логирование событий при отладке трассировки (указываются начальный и конечный методы).
• Debug — логирование всех событий при отладке.
• Info — нормальная работа приложения.
• Warn — логирование предупреждений (приложение будет продолжать работу).
• Error — логирование ошибок (возможно прекращение работы приложения).
• Fatal — логирование ошибок, приводящих к прекращению работы приложения.
• Off — логирование отключено, не используется для записей.

<logger name="IncidentRegistration" writeTo="AdoNetBufferedAppender" minlevel="Trace" final="true" />

Настройка логирования через конфигурационный объект LoggingConfiguration

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

1. Создать объект LoggingConfiguration, который будет описывать конфигурацию.

2. Создать одного или нескольких получателей.

3. Установить свойства получателей.

4. Определить правила с помощью объектов LoggingRule и добавить их в конфигурационные LoggingRules.

5. Активировать конфигурацию, указав в LogManager.Configuration созданный объект конфигурации.

Примеры настройки логирования с помощью кода C# доступны на сайте GitHub.

Логирование для приложений cloud

Для настройки логирования в приложении, развернутом в облаке, необходимо обратится в службу технической поддержки Terrasoft.