Настройка ведения журнала сообщений

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

Включение ведения журнала сообщений

Windows Communication Foundation (WCF) не регистрирует сообщения по умолчанию. Чтобы активировать ведение журнала сообщений, необходимо добавить прослушиватель System.ServiceModel.MessageLogging трассировки в источник трассировки и задать атрибуты для элемента <messagelogging> в файле конфигурации.

В следующем примере показано, как включить ведение журнала и указать дополнительные параметры.

<system.diagnostics>
  <sources>
    <source name="System.ServiceModel.MessageLogging">
      <listeners>
         <add name="messages"
              type="System.Diagnostics.XmlWriterTraceListener"
              initializeData="c:\logs\messages.svclog" />
        </listeners>
    </source>
  </sources>
</system.diagnostics>

<system.serviceModel>
  <diagnostics>
    <messageLogging
         logEntireMessage="true"
         logMalformedMessages="false"
         logMessagesAtServiceLevel="true"
         logMessagesAtTransportLevel="false"
         maxMessagesToLog="3000"
         maxSizeOfMessageToLog="2000"/>
  </diagnostics>
</system.serviceModel>

Дополнительные сведения о параметрах ведения журнала сообщений см. в разделе "Рекомендуемые параметры для отслеживания и ведения журнала сообщений".

Можно указать add имя и тип прослушивателя, который вы хотите использовать. В примере конфигурации прослушиватель называется "сообщения" и добавляет стандартный прослушиватель трассировки .NET Framework (System.Diagnostics.XmlWriterTraceListener) в качестве используемого типа. При использовании System.Diagnostics.XmlWriterTraceListenerнеобходимо указать расположение и имя выходного файла в файле конфигурации. Для этого задайте initializeData имя файла журнала. В противном случае система создает исключение. Вы также можете реализовать пользовательский прослушиватель, который записывает лог-файлы в файл по умолчанию.

Замечание

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

Уровень ведения журнала, а также дополнительные параметры рассматриваются в разделе "Уровень ведения журнала" и "Параметры".

Атрибут switchValue a source является допустимым только для трассировки. Если указать switchValue атрибут для System.ServiceModel.MessageLogging источника трассировки следующим образом, он не действует.

<source name="System.ServiceModel.MessageLogging" switchValue="Verbose">
</source>

Если вы хотите отключить источник трассировки, вместо этого следует использовать атрибуты logMessagesAtServiceLevel, logMalformedMessages и logMessagesAtTransportLevel элемента messageLogging. Необходимо задать для всех этих атрибутов falseзначение . Это можно сделать с помощью файла конфигурации в предыдущем примере кода, через интерфейс пользовательского интерфейса редактора конфигурации или с помощью WMI. Дополнительные сведения о средстве редактора конфигурации см. в разделе "Редактор конфигурации" (SvcConfigEditor.exe). Дополнительные сведения о WMI см. в разделе "Использование инструментирования управления Windows для диагностики".

Уровни ведения журнала и параметры

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

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

WCF регистрирует сообщения на двух разных уровнях, службе и транспорте. Также регистрируются искажённые сообщения. Три категории не зависят друг от друга и могут быть активированы отдельно в конфигурации.

Вы можете управлять уровнем ведения журнала, задав атрибуты logMessagesAtServiceLevel, logMalformedMessages, и logMessagesAtTransportLevel элемента messageLogging.

Уровень обслуживания

Сообщения, зарегистрированные на этом уровне, собираются ввести (при получении) или оставить (при отправке) пользовательский код. Если фильтры определены, регистрируются только сообщения, соответствующие фильтрам. В противном случае регистрируются все сообщения на уровне службы. Сообщения инфраструктуры (транзакции, одноранговые каналы и безопасность) также регистрируются на этом уровне, за исключением сообщений Reliable Messaging. В потоковых сообщениях регистрируются только заголовки. Кроме того, на этом уровне зашифрованные сообщения регистрируются в расшифрованном виде.

Уровень транспорта

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

Искаженный уровень

Неправильно сформированные сообщения — это сообщения, которые отвергаются стеком WCF на любом этапе обработки. Неправильные сообщения регистрируются as-is: шифруются, если они зашифрованы, с некорректным XML и т. д. maxSizeOfMessageToLog определяет размер сообщения, регистрированного как CDATA. По умолчанию maxSizeOfMessageToLog равно 256K. Дополнительные сведения об этом атрибуте см. в разделе "Другие параметры".

Другие параметры

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

• logEntireMessage Журналировать все сообщение (атрибут): данное значение указывает, следует ли регистрировать все сообщение (заголовок и тело сообщения). Значение по умолчанию — false, что означает, что регистрируется только заголовок. Этот параметр влияет на уровни ведения журнала сообщений о службе и транспорте.

• Максимальное количество сообщений в журнал (maxMessagesToLog атрибут): это значение указывает максимальное количество сообщений для журнала. Все сообщения (служебные, транспортные и неправильно сформированные) учитываются в счет этой квоты. При достижении квоты выводится трассировка, и дополнительное сообщение не регистрируется. Значение по умолчанию — 10000.

• Максимальный размер сообщения в журнале (maxSizeOfMessageToLog атрибут): это значение указывает максимальный размер сообщений для записи в байтах. Сообщения, превышающие ограничение размера, не регистрируются и для этого сообщения не выполняются другие действия. Этот параметр влияет на все уровни трассировки. Если трассировка ServiceModel включена, трассировка уровня предупреждения создается в первой точке ведения журнала (ServiceModelSend* или TransportReceive), чтобы уведомить пользователя. Значение по умолчанию для сообщений уровня обслуживания и уровня транспорта — 256 КБ, а значение по умолчанию для неправильно сформированных сообщений — 4K.

  Осторожность

  Размер сообщения в памяти перед сериализацией, используемый для сравнения с maxSizeOfMessageToLog, является рассчитанным размером. Этот размер может отличаться от фактической длины строки сообщения, которая регистрируется, и во многих случаях больше фактического размера. В результате сообщения могут не регистрироваться. Вы можете учесть этот факт, указав maxSizeOfMessageToLog атрибут размером 10% больше ожидаемого размера сообщения. Кроме того, если в журнал записываются неправильные сообщения, фактическое место на диске, используемое журналами сообщений, может быть до 5 раз больше, чем указанное значение maxSizeOfMessageToLog.

Если прослушиватель трассировки не определен в файле конфигурации, логирование не выполняется, независимо от указанного уровня ведения журнала.

Параметры ведения журнала сообщений, такие как атрибуты, описанные в этом разделе, можно изменить во время выполнения с помощью инструментария управления Windows (WMI). Это можно сделать, получив доступ к экземпляру AppDomainInfo, который предоставляет следующие логические свойства: LogMessagesAtServiceLevel, LogMessagesAtTransportLevel, и LogMalformedMessages. Таким образом, если настроить прослушиватель трассировки для ведения журнала сообщений, но задать эти параметры false в конфигурации, их можно изменить на true позже, когда приложение работает. Фактически это позволяет вести журнал сообщений во время выполнения. Аналогичным образом, если включить ведение журнала сообщений в файле конфигурации, его можно отключить во время выполнения с помощью WMI. Дополнительные сведения см. в разделе "Использование инструментирования управления Windows для диагностики".

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

Для неправильно сформированных сообщений source равно Malformed. В противном случае источник имеет следующие значения на основе контекста.

Для запроса и ответа:

Уровень	Отправить запрос	Получение запроса	Отправка ответа	Получение ответа
Уровень модели службы	Услуга Уровень Отправить Просьба	Услуга Уровень Получать Просьба	Услуга Уровень Отправить Ответить	Услуга Уровень Получать Ответить
Уровень транспортировки	Транспорт Отправить	Транспорт Получать	Транспорт Отправить	Транспорт Получать

Для одностороннего запроса:

Уровень	Отправить запрос	Получение запроса
Уровень модели службы	Услуга Уровень Отправить Датаграмма	Услуга Уровень Получать Датаграмма
Уровень транспортировки	Транспорт Отправить	Транспорт Получать

Фильтры сообщений

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

Фильтры поддерживают полный синтаксис XPath и применяются в том порядке, в который они отображаются в файле конфигурации. Синтаксически неправильный фильтр приводит к исключению при конфигурации.

Фильтры также предоставляют функцию безопасности с помощью nodeQuota атрибута, которая ограничивает максимальное количество узлов в XPath DOM, которые можно проверить для сопоставления фильтра.

В следующем примере показано, как настроить фильтр, который записывает только сообщения с разделом заголовка SOAP.

<messageLogging logEntireMessage="true"
    logMalformedMessages="true"
    logMessagesAtServiceLevel="true"
    logMessagesAtTransportLevel="true"
    maxMessagesToLog="420">
    <filters>
        <add nodeQuota="10" xmlns:soap="http://www.w3.org/2003/05/soap-envelope">
                 /soap:Envelope/soap:Header
        </add>
     </filters>
</messageLogging>

Фильтры нельзя применить к тексту сообщения. Фильтры, пытающиеся управлять текстом сообщения, удаляются из списка фильтров. Также генерируется событие, указывающее на это. Например, следующий фильтр будет удален из таблицы фильтров.

<add xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">/s:Envelope/s:Body[contains(text(), "Hello")]</add>

Настройка пользовательского прослушивателя

Вы также можете настроить пользовательский прослушиватель с дополнительными параметрами. Настраиваемый прослушиватель может быть полезен при фильтрации элементов PII, специфичных для приложений, из сообщений перед записью в журнал. В следующем примере показана настраиваемая конфигурация прослушивателя.

<system.diagnostics>
   <sources>
     <source name="System.ServiceModel.MessageLogging">
           <listeners>
             <add name="MyListener"
                    type="YourCustomListener"
                    initializeData="c:\logs\messages.svclog"
                    maxDiskSpace="1000"/>
           </listeners>
     </source>
   </sources>
</system.diagnostics>

Следует учитывать, что type атрибут должен иметь полное имя сборки типа.

См. также

• <логирование сообщений>
• ведение журнала сообщений
• Рекомендуемые параметры для трассировки и ведения журналов сообщений