Настройка трассировкиConfiguring Tracing

В этом разделе описывается, как включить трассировку, настроить создание трассировки источниками трассировки и задать уровни трассировки, задать распространение и трассировку действий для поддержки сквозной корреляции трассировки, а также настроить доступ прослушивателей трассировки к трассировкам.This topic describes how you can enable tracing, configure trace sources to emit traces and set trace levels, set activity tracing and propagation to support end-to-end trace correlation, and set trace listeners to access traces.

Рекомендации по параметрам трассировки в рабочей или отладочной среде см. в разделе Рекомендуемые параметры для трассировки и ведения журнала сообщений.For tracing settings recommendations in production or debugging environment, refer to Recommended Settings for Tracing and Message Logging.

Важно!

В Windows 8, чтобы приложение могло создавать журналы трассировки, необходимо запустить его с расширенными правами доступа (запуск от имени администратора).On Windows 8 you must run your application elevated (Run as Administrator) in order for your application to generate trace logs.

Включение трассировкиEnabling Tracing

Windows Communication Foundation (WCF) выводит следующие данные для диагностической трассировки:Windows Communication Foundation (WCF) outputs the following data for diagnostic tracing:

  • Трассировки основных этапов процесса по всем компонентам приложений, таких как вызовы операций, исключения кода, предупреждения и прочие значительные события обработки.Traces for process milestones across all components of the applications, such as operation calls, code exceptions, warnings and other significant processing events.

  • События ошибок Windows при сбоях возможности трассировки.Windows error events when the tracing feature malfunctions. См. раздел ведение журнала событий.See Event Logging.

Трассировка WCF построена поверх System.Diagnostics.WCF tracing is built on top of System.Diagnostics. Чтобы воспользоваться трассировкой, необходимо определить источники трассировки в файле конфигурации или в коде.To use tracing, you should define trace sources in the configuration file or in code. WCF определяет источник трассировки для каждой сборки WCF.WCF defines a trace source for each WCF assembly. Источник System.ServiceModel трассировки — это наиболее общий источник трассировки WCF, который записывает этапы обработки в стеке связи WCF, от ввода/вывода транспорта до ввода/вывода пользовательского кода.The System.ServiceModel trace source is the most general WCF trace source, and records processing milestones across the WCF communication stack, from entering/leaving transport to entering/leaving user code. Источник трассировки System.ServiceModel.MessageLogging записывает все сообщения, проходящие через систему.The System.ServiceModel.MessageLogging trace source records all messages that flow through the system.

По умолчанию трассировка отключена.Tracing is not enabled by default. Чтобы активировать трассировку, необходимо создать прослушиватель трассировки и установить уровень трассировки, отличный от "Выкл.", для выбранного источника трассировки в конфигурации. в противном случае WCF не создает никакие трассировки.To activate tracing, you must create a trace listener and set a trace level other than "Off" for the selected trace source in configuration; otherwise, WCF does not generate any traces. Если прослушиватель не указан, трассировка автоматически отключается.If you do not specify a listener, tracing is automatically disabled. Если прослушиватель определен, но уровень не указан, по умолчанию устанавливается уровень «Off», при котором трассировка не создается.If a listener is defined, but no level is specified, the level is set to "Off" by default, which means that no trace is emitted.

При использовании точек расширения WCF, таких как пользовательские вызывающие операции, следует создавать собственные трассировки.If you use WCF extensibility points such as custom operation invokers, you should emit your own traces. Это связано с тем, что при реализации точки расширяемости WCF больше не может создавать стандартные трассировки в пути по умолчанию.This is because if you implement an extensibility point, WCF can no longer emit the standard traces in the default path. Если поддержка трассировки вручную путем создания трассировки не реализована, можно не увидеть ожидаемые трассировки.If you do not implement manual tracing support by emitting traces, you may not see the traces you expect.

Трассировку можно настроить, внеся изменения в файл конфигурации приложения: Web.config (для веб-приложений) или Appname.exe.config (для резидентных приложений).You can configure tracing by editing the application’s configuration file—either Web.config for Web-hosted applications, or Appname.exe.config for self-hosted applications. Ниже приводится пример подобного изменения.The following is an example of such edit. Дополнительные сведения об этих параметрах см. в разделе "Настройка прослушивателей трассировки для использования трассировок".For more information on these settings, see the "Configuring Trace Listeners to Consume Traces" section.

<configuration>  
   <system.diagnostics>  
      <sources>  
            <source name="System.ServiceModel"   
                    switchValue="Information, ActivityTracing"  
                    propagateActivity="true">  
            <listeners>  
               <add name="traceListener"   
                   type="System.Diagnostics.XmlWriterTraceListener"   
                   initializeData= "c:\log\Traces.svclog" />  
            </listeners>  
         </source>  
      </sources>  
   </system.diagnostics>  
</configuration>  

Примечание

Чтобы изменить файл конфигурации проекта службы WCF в Visual Studio, щелкните правой кнопкой мыши файл конфигурации приложения — Web. config для веб-приложений или имя_приложения. exe. config для самостоятельно размещенного приложения в Обозреватель решений.To edit the configuration file of a WCF service project in Visual Studio, right click the application’s configuration file—either Web.config for Web-hosted applications, or Appname.exe.config for self-hosted application in Solution Explorer. Затем выберите пункт изменить пункт контекстного меню для настройки WCF .Then choose the Edit WCF Configuration context menu item. Запускается средство редактора конфигурации (SvcConfigEditor. exe), которое позволяет изменять параметры конфигурации для служб WCF с помощью графического пользовательского интерфейса.This launches the Configuration Editor Tool (SvcConfigEditor.exe), which enables you to modify configuration settings for WCF services using a graphical user interface.

Настройка создания трассировки источниками трассировкиConfiguring Trace Sources to Emit Traces

WCF определяет источник трассировки для каждой сборки.WCF defines a trace source for each assembly. Трассировки, созданные в пределах сборки, доступны прослушивателям, определенным для этого источника.Traces generated within an assembly are accessed by the listeners defined for that source. Определяются следующие источники трассировки:The following trace sources are defined:

  • System. ServiceModel: Записывает в журнал все этапы обработки WCF, при каждом считывании конфигурации, обработке сообщения, обработке безопасности, отправке сообщения в пользовательском коде и т. д.System.ServiceModel: Logs all stages of WCF processing, whenever configuration is read, a message is processed in transport, security processing, a message is dispatched in user code, and so on.

  • System. ServiceModel. Мессажелоггинг: Записывает в журнал все сообщения, которые проходят через систему.System.ServiceModel.MessageLogging: Logs all messages that flow through the system.

  • System.IdentityModel.System.IdentityModel.

  • System.ServiceModel.Activation.System.ServiceModel.Activation.

  • System. IO. log: Ведение журнала для интерфейса .NET Framework файловая система CLFS (CLFS).System.IO.Log: Logging for the .NET Framework interface to the Common Log File System (CLFS).

  • System. Runtime. Serialization: Регистрируется при чтении или записи объектов.System.Runtime.Serialization: Logs when objects are read or written.

  • CardSpace.CardSpace.

Можно настроить все источники трассировки так, чтобы они использовали один и тот же (общий) прослушиватель, как показано в следующем примере конфигурации.You can configure each trace source to use the same (shared) listener, as indicated in the following configuration example.

<configuration>  
    <system.diagnostics>  
        <sources>  
            <source name="System.ServiceModel"   
                    switchValue="Information, ActivityTracing"  
                    propagateActivity="true">  
                <listeners>  
                    <add name="xml" />  
                </listeners>  
            </source>  
            <source name="CardSpace">  
                <listeners>  
                    <add name="xml" />  
                </listeners>  
            </source>  
            <source name="System.IO.Log">  
                <listeners>  
                    <add name="xml" />  
                </listeners>  
            </source>  
            <source name="System.Runtime.Serialization">  
                <listeners>  
                    <add name="xml" />  
                </listeners>  
            </source>  
            <source name="System.IdentityModel">  
                <listeners>  
                    <add name="xml" />  
                </listeners>  
            </source>  
        </sources>  
  
        <sharedListeners>  
            <add name="xml"  
                 type="System.Diagnostics.XmlWriterTraceListener"  
                 initializeData="c:\log\Traces.svclog" />  
        </sharedListeners>  
    </system.diagnostics>  
</configuration>  

Кроме того, можно добавить пользовательские источники трассировки, создающие трассировки пользовательского кода, как показано в следующем примере.In addition, you can add user-defined trace sources, as demonstrated by the following example, to emit user code traces.

<system.diagnostics>  
   <sources>  
       <source name="UserTraceSource" switchValue="Warning, ActivityTracing" >  
          <listeners>  
              <add name="xml"  
                 type="System.Diagnostics.XmlWriterTraceListener"  
                 initializeData="C:\logs\UserTraces.svclog" />  
          </listeners>  
       </source>  
   </sources>  
   <trace autoflush="true" />   
</system.diagnostics>  

Дополнительные сведения о создании определяемых пользователем источников трассировки см. в разделе Расширение трассировки.For more information about creating user-defined trace sources, see Extending Tracing.

Настройка потребления трассировки прослушивателями трассировкиConfiguring Trace Listeners to Consume Traces

Во время выполнения веб-каналы WCF отслеживают данные в прослушиватели, которые обрабатывают данные.At runtime, WCF feeds trace data to the listeners which process the data. WCF предоставляет несколько предопределенных прослушивателей для System.Diagnostics, которые отличаются в формате, используемом для вывода.WCF provides several predefined listeners for System.Diagnostics, which differ in the format they use for output. Можно добавлять пользовательские типы прослушивателей.You can also add custom listener types.

С помощью add можно задать имя и тип прослушивателя трассировки, который требуется использовать.You can use add to specify the name and type of the trace listener you want to use. В данном примере конфигурации создается прослушиватель с именем traceListener и добавляется стандартный прослушиватель трассировки .NET Framework (System.Diagnostics.XmlWriterTraceListener) в качестве типа, который требуется использовать.In our example configuration, we named the Listener traceListener and added the standard .NET Framework trace listener (System.Diagnostics.XmlWriterTraceListener) as the type we want to use. Для каждого источника можно добавить любое количество прослушивателей трассировки.You can add any number of trace listeners for each source. Если прослушиватель трассировки выполняет трассировку в файл, необходимо указать расположение и имя выходного файла в файле конфигурации.If the trace listener emits the trace to a file, you must specify the output file location and name in the configuration file. Для этого необходимо указать имя файла для этого прослушивателя в качестве значения для initializeData.This is done by setting initializeData to the name of the file for that listener. Если имя файла не указано, используется случайное имя, сгенерированное на основе используемого типа прослушивателя.If you do not specify a file name, a random file name is generated based on the listener type used. Если используется XmlWriterTraceListener, создается имя файла без расширения.If XmlWriterTraceListener is used, a file name with no extension is generated. Если реализовать пользовательский прослушиватель, с помощью этого атрибута также можно получать другие данные инициализации, помимо имени файла.If you implement a custom listener, you can also use this attribute to receive initialization data other than a filename. Например, с его помощью можно указать идентификатор базы данных.For example, you can specify a database identifier for this attribute.

Пользовательский прослушиватель трассировки можно настроить так, чтобы он отправлял трассировку по сети, например в удаленную базу данных.You can configure a custom trace listener to send traces on the wire, for example, to a remote database. Разработчику приложения следует обеспечить надлежащее управление доступом к журналам трассировки на удаленном компьютере.As an application deployer, you should enforce proper access control on the trace logs in the remote machine.

Также можно настроить прослушиватель трассировки программно.You can also configure a trace listener programmatically. Дополнительные сведения см. в разделе Практическое руководство. Создание и инициализация прослушивателей трассировки и Создание пользовательскогопрослушивателя TraceListener.For more information, see How to: Create and Initialize Trace Listeners and Creating a Custom TraceListener.

Внимание!

Поскольку прослушиватель System.Diagnostics.XmlWriterTraceListener не является потокобезопасным, источник трассировки может монопольно блокировать ресурсы при выводе трассировки.Because System.Diagnostics.XmlWriterTraceListener is not thread-safe, the trace source may lock resources exclusively when outputting traces. Если несколько потоков выводят трассировку в источник трассировки, использующий (согласно заданным настройкам) этот прослушиватель, может возникнуть состязание за ресурсы, что приводит к существенному падению производительности.When many threads output traces to a trace source configured to use this listener, resource contention may occur, which results in a significant performance issue. Чтобы устранить эту проблему, реализуйте потокобезопасный пользовательский прослушиватель.To resolve this problem, you should implement a custom listener that is thread-safe.

Уровень трассировкиTrace Level

Уровень трассировки контролируется параметром switchValue источника трассировки.The tracing level is controlled by the switchValue setting of the trace source. Доступные уровни трассировки приведены в следующей таблице.The available tracing levels are described in the following table.

Уровень трассировкиTrace Level Характер отслеживаемых событийNature of the Tracked Events Содержимое отслеживаемых событийContent of the Tracked Events Отслеживаемые событияTracked Events Целевая категория пользователейUser Target
OffOff Н/ДN/A Н/ДN/A Трассировки не создаются.No traces are emitted. Н/ДN/A
CriticalCritical "Отрицательные" события: события, которые указывают на непредвиденную обработку или состояние ошибки."Negative" events: events that indicate an unexpected processing or an error condition. В журнал заносятся необработанные исключения, в том числе следующие:Unhandled exceptions including the following are logged:

-OutOfMemoryException- OutOfMemoryException
-ThreadAbortException (среда CLR вызывает любой Среадабортексцептионхандлер)- ThreadAbortException (the CLR invokes any ThreadAbortExceptionHandler)
-StackOverflowException (не может быть перехвачен)- StackOverflowException (cannot be caught)
-ConfigurationErrorsException- ConfigurationErrorsException
-SEHException- SEHException
— Ошибки запуска приложения- Application start errors
— События FailFast- Failfast events
-Зависание системы- System hangs
— Подозрительные сообщения: трассировки сообщений, вызывающие сбой приложения.- Poison messages: message traces that cause the application to fail.
АдминистраторыAdministrators

Разработчики приложенийApplication developers
ErrorError "Отрицательные" события: события, которые указывают на непредвиденную обработку или состояние ошибки."Negative" events: events that indicate an unexpected processing or an error condition. Возникло непредвиденное состояние обработки.Unexpected processing has happened. Приложению не удалось выполнить задачу требуемым образом.The application was not able to perform a task as expected. Впрочем, приложение все еще работает.However, the application is still up and running. Все исключения заносятся в журнал.All exceptions are logged. АдминистраторыAdministrators

Разработчики приложенийApplication developers
ПредупреждениеWarning "Отрицательные" события: события, которые указывают на непредвиденную обработку или состояние ошибки."Negative" events: events that indicate an unexpected processing or an error condition. Возникла (или может возникнуть) проблема, но приложение все же работает надлежащим образом.A possible problem has occurred or may occur, but the application still functions correctly. Впрочем, его правильное выполнение может прекратиться.However, it may not continue to work properly. — Приложение получает больше запросов, чем разрешает его параметры регулирования.- The application is receiving more requests than its throttling settings allow.
-Принимающая очередь приближается к максимальному настроенному объему.- The receiving queue is near its maximum configured capacity.
-Превышено время ожидания.- Timeout has exceeded.
— Учетные данные отклоняются.- Credentials are rejected.
АдминистраторыAdministrators

Разработчики приложенийApplication developers
СведенияInformation "Положительные" события: события, помечающие успешные вехи"Positive" events: events that mark successful milestones Успешно пройденные важные этапы выполнения приложения, вне зависимости от того, правильно ли работает приложение.Important and successful milestones of application execution, regardless of whether the application is working properly or not. Как правило, создаются сообщения, полезные для мониторинга и диагностики состояния системы, измерений производительности или профилирования.In general, messages helpful for monitoring and diagnosing system status, measuring performance or profiling are generated. Эту информацию можно использовать для планирования загрузки и управления производительностью.You can use such information for capacity planning and performance management:

— Каналы создаются.- Channels are created.
— Прослушиватели конечной точки созданы.- Endpoint listeners are created.
— Сообщение переходит/оставляет транспорт.- Message enters/leaves transport.
— Токен безопасности извлекается.- Security token is retrieved.
— Чтение параметра конфигурации.- Configuration setting is read.
АдминистраторыAdministrators

Разработчики приложенийApplication developers

Разработчики программных продуктов.Product developers.
VerboseVerbose "Положительные" события: события, помечающие успешные вехи."Positive" events: events that mark successful milestones. Создаются события низкого уровня как для пользовательского кода, так и для обслуживания.Low level events for both user code and servicing are emitted. Как правило, этот уровень можно использовать для отладки или оптимизации приложения.In general, you can use this level for debugging or application optimization.

-Понятный заголовок сообщения.- Understood message header.
АдминистраторыAdministrators

Разработчики приложенийApplication developers

Разработчики программных продуктов.Product developers.
ActivityTracingActivityTracing События переходов между действиями по обработке и компонентами.Flow events between processing activities and components. Этот уровень позволяет администраторам и разработчикам коррелировать приложения из одного домена приложений.This level allows administrators and developers to correlate applications in the same application domain:

— Трассировка для границ действий, таких как запуск и завершение.- Traces for activity boundaries, such as start/stop.
— Трассировки для передачи.- Traces for transfers.
ВсеAll
ВсеAll Приложение может работать надлежащим образом.Application may function properly. Создаются все события.All events are emitted. Все вышеперечисленные события.All previous events. ВсеAll

Каждый уровень трассировки от Verbose до Critical включает все вышестоящие уровни, за исключением уровня "Off".The levels from Verbose to Critical are stacked on top of each other, that is, each trace level includes all levels above it except the Off level. Например, если прослушиватель прослушивает уровень Warning, он получает трассировки, имеющие уровень Critical, Error и Warning.For example, a listener listening at the Warning level receives Critical, Error, and Warning traces. Уровень All включает в себя все события уровней от Verbose до Critical, а также события ActivityTracing (прослеживание действий).The All level includes events from Verbose to Critical and Activity tracing events.

Внимание!

Уровни Information, Verbose и ActivityTracing создают большое количество трассировок, что может негативно сказаться на производительности в отношении обработки сообщений, если все доступные ресурсы компьютера использованы.The Information, Verbose, and ActivityTracing levels generate a lot of traces, which may negatively impact message throughput if you have used up all available resources on the machine.

Настройка распространения и трассировки действий для корреляцииConfiguring Activity Tracing and Propagation for Correlation

Для атрибута activityTracing можно задать значение switchValue, чтобы включить трассировку действий, создающую трассировку для границ действий и передач в пределах конечных точек.The activityTracing value specified for the switchValue attribute is used to enable activity tracing, which emits traces for activity boundaries and transfers within endpoints.

Примечание

При использовании определенных функций расширения в WCF вы можете получить NullReferenceException , когда включена трассировка действий.When you use certain extensibility features in WCF, you might get a NullReferenceException when activity tracing is enabled. Чтобы устранить эту проблему, проверьте файл конфигурации своего приложения: атрибут switchValue для соответствующего источника трассировки не должен иметь значение activityTracing.To fix this problem, check your application's configuration file and ensure that the switchValue attribute for your trace source is not set to activityTracing.

Атрибут propagateActivity указывает, должно ли действие распространяться на другие конечные точки, участвующие в обмене сообщениями.The propagateActivity attribute indicates whether the activity should be propagated to other endpoints that participate in the message exchange. Если присвоить ему значение true, можно с помощью файлов трассировки, созданных любыми двумя конечными точками, проследить прохождение набора трассировок от одной конечной точки до набора трассировок на другой конечной точке.By setting this value to true, you can take trace files generated by any two endpoints and observe how a set of traces on one endpoint flowed to a set of traces on another endpoint.

Дополнительные сведения о трассировке и распространении действий см. в разделе распространение.For more information about activity tracing and propagation, see Propagation.

Как propagateActivity , ActivityTracing так и логические значения применяются к System. ServiceModel TraceSource.Both propagateActivity and ActivityTracing Boolean values apply to the System.ServiceModel TraceSource. ActivityTracing Значение также применяется к любому источнику трассировки, включая WCF или определяемые пользователем.The ActivityTracing value also applies to any trace source, including WCF or user-defined ones.

Атрибут propagateActivity нельзя использовать для пользовательских источников трассировок.You cannot use the propagateActivity attribute with user-defined trace sources. Для распространения идентификатора действия пользовательского кода необходимо убедиться, что ServiceModel ActivityTracing не задано, тогда как ServiceModel propagateActivity имеет значение true.For user code activity ID propagation, make sure you do not set ServiceModel ActivityTracing, while still having ServiceModel propagateActivity attribute set to true.

См. такжеSee also