Журналирование КриптоПро Ключ

Сообщения о работе служб КриптоПро Ключ записываются в автоматически создаваемые при установке журналы событий:

В *nix-системах:

  • /var/log/cprokey/{{Имя сервиса}}/{{Имя экземпляра сервиса при создании}}/cprokey-{{Имя сервиса}}-{{Имя экземпляра сервиса}}*.log - если используется текстовое журналирование;
  • /var/log/cprokey/{{Имя сервиса}}/{{Имя экземпляра сервиса при создании}}/cprokey-{{Имя сервиса}}-{{Имя экземпляра сервиса}}*.clef - если используется структурированное журналирование.

В Windows:

C:\Program Files\Crypto Pro\KEY\{{Имя сервиса}}\log
Сервис Имя сервиса
Сервис Подписи signsrv
Центр Идентификации idsrv
Сервис Обработки Документов docsrv
Сервис Аудита auditsrv
Сервис взаимодействия с SDK mdagsrv
Сервис PUSH-уведомлений pushsrv

Поддерживаемые типы и форматы журналов событий

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

Настройка журналирования и ротации журналов

Настройка журналов производится при помощи командлета Set-{{Имя компонента}}LoggingProperties.

Сервис Имя сервиса в командлете
Сервис Подписи Sign
Центр Идентификации Ids
Сервис Обработки Документов Ds
Сервис Аудита Audit
Сервис PUSH-уведомлений Push

Настройки журналирования:

Название свойства Описание
LogLevel Уровень логирования по умолчанию.
OutputTemplate Шаблон сообщения. Параметры и вид шаблона по умолчанию описаны ниже.
RollingInterval Задает частоты создания нового файла журнала. Доступны значения:
Minute,Hour,Day,Month,Year, Infinite. По умолчанию имеет значение Day.
FileSizeLimitBytes Максимальный размер файла журнала в байтах, при достижении заданного размера будет создан новый файл. Для неограниченного роста необходимо указать 0. По умолчанию имеет значение 1MB.
RetainedFileCountLimit Максимальное количество файлов журналов, при достижении этого значения старые файлы будут удаляться. Для отключения удаления необходимо указать 0.
IsAsync Используется ли асинхронная запись в файл. Данный режим ускоряет производительность, но снижает надежность. По умолчанию false.
AsyncBufferSize Размер очереди для асинхронной записи. Определяется опытным путем, по умолчанию имеет значение 10000. Слишком большие значения увеличат объем занятой памяти и снизят надежность из-за риска потерять все содержимое очереди в результате сбоя, слишком маленькие значения нивелируют преимущество асинхронной записи.
AsyncBlockWhenFull Определяет режим работы асинхронной записи при превышении размера очереди, блокирование записи новых событий или игнорирование (отбрасывание не помещающихся сообщений с их потерей. По умолчанию false.
FlushToDiskIntervalSeconds Интервал записи в файл на диск. По умолчанию 2 секунды.
UseRenderedClef Построение текстовок записей журнала в удобно читаемом формате с учетом подстановочных параметров. По умолчанию false. Рекомендуется использовать при включении структурированного журналирования (параметр UseStructuredLogging).
UseStructuredLogging Включение структурированного журналирования. По умолчанию false.
EnableDebugLogging Параметр зарезервирован для дальнейшего использования.

После выполнения настроек необходимо перезапустить сервис:

Restart-{{Имя компонента}}Instance

Поддерживаются следующие виды журналирования:

Текстовое журналирование

Режим журналирования используется по умолчанию. Журналы событий имеют расширение *.log. Шаблон форматирования по умолчанию имеет следующий вид.

[{Level:u3}] {EventId}: {Timestamp:o } | {RequestId,22} | {Message:lj} | {Properties:j} |{NewLine}{Exception}<|

Компоненты шаблона (в случае если компонент отсутствует, он будет представлять собой пустое значение | |:

  • {Level:u3} - уровень логирования в виде трехбуквенного сокращения в верхнем регистре: DBG, INF, WRN, ERR, CRT.
  • {EventId} - идентификатор события .
  • {Timestamp:o} - метка времени в формате YYYY-MM-DDThh:mm:ss.fffffffzzz (ISO 8601).
  • {RequestId,22} - уникальный идентификатор запроса. Представляет из себя 22 символа в формате ConnectionId:RequestNumber, где ConnectionId - это идентификатор HTTP соединения, а RequestNumber - номер HTTP запроса, полученного по данному соединению.
  • {Message:lj} - текст сообщения.
  • {Propertie:j} - дополнительные свойства сообщения, не вошедшие в текстовку {Message}, в виде сериализованного в строку объекта JSON.
  • {NewLine} - специальное свойство, отображающее новую строку.
  • {Exception} - сообщение об ошибке вместе со стектрейсом (при наличии).

Символы {, }, :u3, :o, :lj, :j являются специальными элементами самого шаблона, они не попадают в результирующий вывод. Специальные символы | и <| облегчают его автоматизированный разбор.

Пример записи:

[INF] { Id: 1 }: 2024-11-15T13:54:45.4041441+03:00 | 0HN82BCC94RU0:00000001 | Request starting HTTP/1.0 POST http://localhost:60000/api/signatures/presign - application/json 1167 | {"SourceContext":"Microsoft.AspNetCore.Hosting.Diagnostics","RequestPath":"/api/signatures/presign","ConnectionId":"0HN82BCC94RU0","ProcessId":81153,"ThreadId":11} |

Структурированное журналирование

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

Set-{{Имя компонента}}LoggingProperties -UseStructuredLogging $true -UseRenderedClef $true

После выполнения настроек необходимо перезапустить сервис:

Restart-{{Имя компонента}}Instance

Журналы событий имеют расширение *.clef. Шаблон форматирования по умолчанию имеет следующий вид.

Компонент Имя Описание Обязательность
@t Timestamp Метка времени в формате YYYY-MM-DDThh:mm:ss.fffffffzzz (ISO 8601). Обязательный
@m Message Текст сообщения
@mt Message Template Шаблон сообщения. Будет отображен вместо поля Message, если при настройке структурированного журналирования не был взведен флаг -UseRenderedClef $true
@l Level Уровень логирования Отсутствие означает, чтобы событие является информационным
@x Exception Сообщение об ошибке вместе со стектрейсом (при наличии).
@i Event id Идентификатор события

Пример записи:

{"@t":"2024-11-15T10:55:43.7311260Z","@m":"Content root path: \"/var/opt/cprokey/litesrv/lite\"","@i":"cc26f24e","ContentRoot":"/var/opt/cprokey/litesrv/lite","SourceContext":"Microsoft.Hosting.Lifetime","ProcessId":84635,"ThreadId":1}