Протоколирование событий

  1. При остановке сервиса dvwebclient в файл журнала Web-клиента добавляется запись о завершении Web-клиента, например:

    [2022-10-26 17:38:08.1840][Error][DocsVision.Platform.WebClient.Diagnostics.Trace.TraceError]  Application end: HostingEnvironment

  2. При старте сервиса dvwebclient создаётся новый файл журнала Web-клиента.

  3. К названию файла журнала добавляется ID процесса и дата запуска Web-клиента:

    WebClient${event-properties:item=Tenant} PID $\{processId} $\{shortdate}.log

    Например: WebClient PID 4592 2022-10-26.log

  4. В созданный файл добавляется сообщение о старте Web-клиента, например:

    [2022-10-26 17:11:56.8774][Error][DocsVision.Platform.WebClient.Diagnostics.Trace.TraceError]  Application start

Протоколирование запросов сервера Web-клиента

Протоколирование запросов полезно для анализа входящих запросов сервера Web-клиента и ответов на них, заголовков и т.д.

Журнал запросов содержит следующую информацию:

  • HTTP запросы и ответы.

  • Дата и время запросов и ответов.

  • Заголовки

Протоколирование запросов сервера Web-клиента настраивается в конфигурационном файле модуля по адресу /usr/lib/docsvision/webclient/appsettings.json, за настройку отвечает параметр W3CLogging:

"W3CLogging": {
	"IsEnabled": true, (1)
	"LogDirectory": "/var/log/docsvision/webclient/", (2)
	"LoggingFields": "Date,Time,ServerName,Method,UriStem,UriQuery,ProtocolStatus,TimeTaken,ProtocolVersion,Host,UserAgent,Referer,ConnectionInfoFields", (3)
	"FileSizeLimit": 10485760, (4)
	"RetainedFileCountLimit": 4, (5)
	"FileName": "webclient-w3c-" (6)
}
json
1 Включение/отключение протоколирования событий. Значение по умолчанию: false, в стандартной конфигурации остальные настройки отсутствуют.
2 Путь к журналу.
3 Журналируемые поля. По умолчанию указываются запросы, ответы, заголовки, дата/время (записывается в формате UTC) и имя сервера. Со всеми допустимыми значениями можно ознакомиться в документации Microsoft.
4 Максимальный размер файла журнала, после которого будет создаваться новый. Значение в байтах, по умолчанию 10485760 байт (10 Мб). Цифра 0 означает отсутствие ограничения по размеру.
5 Количество сохраняемых файлов журнала. Допустимые значения от 1 до 10000, по умолчанию используется 4.
6 Префикс имени файла журнала.

Запросы будут записаны в файл /var/log/docsvision/webclient/webclient-w3c-{YYYYMMDD.X}.txt. Настройка альтернативного расширения поддерживается только при протоколировании с NLog, см. подробнее ниже.

Протоколирование запросов с помощью NLog

Если требуется отображать в журналах локальное время или расширить список журналируемой информации, есть возможность подключения Nlog. При этом стандартное журналирование "W3CLogging" будет отключено (вне независимости от значения параметра W3CLogging  IsEnabled.

Протоколирование запросов с использованием NLog имеет ряд преимуществ перед журналированием W3CLogging. NLog предлагает больше параметров логирования (38 против 17),указывает в журнале местное время с точностью до миллисекунды, позволяет задать свои форматы для отображаемых данных и даёт гибкость в управлении файлами журнала.

Чтобы активировать протоколирование запросов с помощью NLog, измените параметры журналирования в параметре: NLog  targets:
"NLog": {
   "extensions": [
    { "assembly": "DocsVision.WebClient" } (1)
   ],
   "targets": {
    "w3cFile": {
      "type": "File",
      "fileName": "${gdc:baseLogFolder}/docsvision/webclient/webclient-w3c-${date:format=yyyyMMdd}.${processId}.log",
      "layout": {
        "type": "W3CLoggingLayout",
        "columns": [ (2)
		{ "column": "date" },
		{ "column": "time", "layout": "${longdate}" }, (3)
		{ "column": "c-ip" },
	    ]
      }
    }
   },
   "rules": [
    {
      "logger": "*",
      "minLevel": "Debug",
      "writeTo": "w3cFile"
    }
   ]
}
json
1 Обязательный параметр, если он не указан, NLog не будет записывать обычные сообщения в журнал.
2 Секция задаёт собственный набор колонок. Если список колонок не указан, в журнал будут включены только колонки по умолчанию date, time, c-ip, s-ip, cs-username, s-computername, cs-method, cs-uri-stem, cs-uri-query, sc-statuscode, sc-bytes, cs-bytes, time-taken, cs-host, cs(User-Agent).
3 Формат представления данных колонки может быть изменён. Если формат не указан, будут использоваться значения по умолчанию. В layout можно использовать любые переменные NLog, подробнее см. в документации NLog.
Полный список колонок и допустимых значений для журналирования:

  • date — Дата начала обработки запроса. Значение по умолчанию: ${date:format=yyyy-MM-dd}.

  • time — Время начала обработки запроса. Значение по умолчанию: ${date:format=HH:mm:ss.fff}.

  • webclient-version — Версия Web-клиента. Например 6.1.725+a4c9b271d7. Значение по умолчанию: ${webclient-version}. Для протоколирования запросов сервера приложений аналогичная колонка называется appserver-version.

  • c-ip — IP-адрес клиента. Значение по умолчанию: ${aspnet-request-ip}.

  • cs(Auth-Type) — Тип используемой аутентификации (например, Cookie). Значение по умолчанию: ${aspnet-user-authtype}.

  • cs(Certificate) — Сертификат клиента текущего запроса. Значение по умолчанию: ${aspnet-request-client-certificate}.

  • cs(Content-Type) — Тип контента: text/html, multipart/form-data и т.д.. Значение по умолчанию: ${aspnet-request-contenttype}.

  • cs(Cookie) — Cookie, подробнее о допустимых параметрах в документации NLog. Значение по умолчанию: ${aspnet-request-cookie}.

  • cs(Referer) — Значение поля Referer из заголовка запроса. Значение по умолчанию: ${aspnet-request-referrer}.

  • cs(User-Agent) — User agent. Значение по умолчанию: ${aspnet-request-useragent}.

  • cs-bytes — Получено байтов. Значение по умолчанию: ${aspnet-request-contentlength}.

  • cs-connectionid — Идентификатор соединения, см. в документации Microsoft. Значение по умолчанию: ${aspnet-request-connection-id}.

  • cs-form — Данные формы из запроса. Подробнее о параметрах в документации NLog. Значение по умолчанию: ${aspnet-request-form}.

  • cs-headers — Заголовок запроса. Если нужно взять только определенные заголовки, можно воспользоваться параметрами, подробнее см. в документации NLog. Значение по умолчанию: ${aspnet-request-headers}.

  • cs-host — Значение Host из заголовка запроса. Значение по умолчанию: ${aspnet-request-url:includeScheme=false:includeHost=true:includePath=false}.

  • cs-fullhostname — Полное имя хоста (с портом). Значение по умолчанию: ${aspnet-request-host}.

  • cs-isauthenticated — Состояние аутентификации (значения 0 или 1). Значение по умолчанию: ${aspnet-user-isAuthenticated}.

  • cs-method — Метод (get/post и т.п.). Значение по умолчанию: ${aspnet-request-method}.

  • cs-mvc-action — Вызываемое действие. Значение по умолчанию: ${aspnet-mvc-action}.

  • cs-mvc-controller — Вызываемый контроллер. Значение по умолчанию: ${aspnet-mvc-controller}.

  • cs-posted-body — Значение по умолчанию ${aspnet-request-posted-body}.

    Значения:

    • 1, если:

      • Это запрос HTTP/1.x с ненулевым значением Content-Length или заголовком "Transfer-Encoding: chunked".

      • Это запрос HTTP/2, который не установил флаг END_STREAM на исходном фрейме заголовка.

    • 0, если:

      • Это запрос HTTP/1.x без заголовка Content-Length или "Transfer-Encoding: chunked", или Content-Length равен 0.

      • Это запрос HTTP/1.x с Connection: Upgrade (например, WebSockets). Для этих запросов не существует тела HTTP-запроса, и никакие данные не должны быть получены до тех пор, пока не будет выполнено обновление.

      • Это запрос HTTP/2, который устанавливает END_STREAM на начальном фрейме заголовка.

  • cs-tracking-consent — Согласие на отслеживание (значения 0 или 1). Значение по умолчанию: ${aspnet-request-tracking-consent}.

    Возможные параметры:

    • property.

      Допустимые значения:

      • CanTrack —  Указывает, было ли дано согласие, или если согласие не требуется (1 или 0);

      • HasConsent —  было ли дано согласие;

      • IsConsentNeeded —  требуется ли согласие для данного запроса.

    Пример вызова в собственном формате: ${aspnet-request-tracking-consent:property=CanTrack}.

  • cs-uri-query — Значение по умолчанию: ${aspnet-request-url:includeScheme=false:includeHost=false:includePath=false:includeQueryString=true}. Запрос URI.

  • cs-uri-stem — Ресурс URI. Значение по умолчанию: ${aspnet-request-url:includeScheme=false:includeHost=false}.

  • cs-username — Имя пользователя. Значение по умолчанию: ${aspnet-user-identity}.

  • is-websocket — Является ли запрос запросом на установку WebSocket (0 или 1). Значение по умолчанию: ${aspnet-request-is-web-socket}.

  • s-basepath — Значение ContentRootPath. Значение по умолчанию: ${aspnet-appbasepath}.

  • s-computername --Имя сервера. Значение по умолчанию: ${machinename}.

  • s-environment — Значение ASPNETCORE_ENVIRONMENT. Значение по умолчанию: ${aspnet-environment}.

  • s-ip — IP-адрес сервера. Значение по умолчанию: ${aspnet-request-local-ip}.

  • s-port — Порт. Значение по умолчанию: ${aspnet-request-local-port}.

  • s-sitename — Имя сайта. Значение по умолчанию: ${iis-site-name}.

  • s-webrootpath — WebRootPath. Значение по умолчанию: ${aspnet-webrootpath}.

  • sc(Content-Type) — Тип контента ответа. Значение по умолчанию: ${aspnet-response-contenttype}.

  • sc-bytes — Отправлено байт. Значение по умолчанию: ${aspnet-response-contentlength}.

  • sc-response-has-started — Были ли отправлены заголовки ответа, т.е. начался ли уже ответ или нет. Значения 0 или 1. Значение по умолчанию: ${aspnet-response-has-started}.

  • sc-status — Код статуса ответа (200, 404 и т.д.). Значение по умолчанию: ${aspnet-response-statuscode}.

  • time-taken — Сколько времени заняла обработка запроса (в миллисекундах). Значение по умолчанию: ${aspnet-request-duration}.