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.

Enabling Tracing

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 error events when the tracing feature malfunctions. See Event Logging.

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 defines a trace source for each WCF assembly. 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. The System.ServiceModel.MessageLogging trace source records all messages that flow through the system.

Tracing is not enabled by default. 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. 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.

If you use WCF extensibility points such as custom operation invokers, you should emit your own traces. 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.

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>

Configuring Trace Sources to Emit Traces

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: 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.MessageLogging: Logs all messages that flow through the system.

• System.IdentityModel.

• System.ServiceModel.Activation.

• System.IO.Log: Logging for the .NET Framework interface to the Common Log File System (CLFS).

• System.Runtime.Serialization: Logs when objects are read or written.

• 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

At runtime, WCF feeds trace data to the listeners which process the data. WCF provides several predefined listeners for System.Diagnostics, which differ in the format they use for output. You can also add custom listener types.

You can use add to specify the name and type of the trace listener you want to use. 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. 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. 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. For more information, see How to: Create and Initialize Trace Listeners and Creating a Custom TraceListener.

Caution:
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

The tracing level is controlled by the switchValue setting of the trace source. The available tracing levels are described in the following table.

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. For example, a listener listening at the Warning level receives Critical, Error, and Warning traces. The All level includes events from Verbose to Critical and Activity tracing events.

Caution:
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

The activityTracing value specified for the switchValue attribute is used to enable activity tracing, which emits traces for activity boundaries and transfers within endpoints.

The propagateActivity attribute indicates whether the activity should be propagated to other endpoints that participate in the message exchange. 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 Activity Tracing and Propagation.

Both propagateActivity and ActivityTracing Boolean values apply to the System.ServiceModel TraceSource. The ActivityTracing value also applies to any trace source, including WCF or user-defined ones.

You cannot use the propagateActivity attribute with user-defined trace sources. 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

Concepts

Administration and Diagnostics

Other Resources

Tracing
How to: Create and Initialize Trace Listeners
Creating a Custom TraceListener