Diagnostic Traces

Traces are the publishing of specific messages that are generated during application execution. When using tracing, you must have a mechanism for collecting and recording the messages that are sent. Trace messages are received by listeners. The purpose of a listener is to collect, store, and route tracing messages. Listeners direct the tracing output to an appropriate target, such as a log, window, or text file.

One such listener, the DefaultTraceListener, is automatically created and initialized when tracing is enabled. If you want trace output to be directed to any additional sources, you must create and initialize additional trace listeners. The listeners you create should reflect your individual needs. For example, you might want a text record of all trace output. In this case, you would create a listener that wrote all output to a new text file when enabled. On the other hand, you might only want to view output during application execution. In that case, you might create a listener that directed all output to a console window. The EventLogTraceListener can direct trace output to an event log, and the TextWriterTraceListener can write trace output to a stream.

Enabling Tracing

To enable traces during transaction processing, you should edit your application’s configuration file. The following is an example.

<configuration>
<system.diagnostics>
     <sources>
          <source name="System.Transactions" switchValue="Warning">
               <listeners>
                    <add name="tx" 
                     type="System.Diagnostics.XmlWriterTraceListener" 
                     initializeData= "tx.log" />
               </listeners>
          </source>
     </sources>
</system.diagnostics>
</configuration>

System.Transactions traces are written to the source named "System.Transactions". 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 "tx" and added the standard .NET Framework trace listener (XmlWriterTraceListener) as the type we want to use. Use initializeData to set the name of the log file for that listener. In addition, you can substitute a fully qualified path for a simple file name.

Each trace message type is assigned a level to indicate its degree of importance. If the app-domain’s trace level is equal or lower than the level of an event type, then that message is generated. The tracing level is controlled by the switchValue setting in the configuration file. The levels that are associated with diagnostic trace messages are defined in the following table.

Trace Codes

The following table lists the trace codes that are generated by the System.Transactions infrastructure. Included in the table are the trace code identifier, the EventType enumeration level for the trace, and the extra data contained in the TraceRecord for the trace. In addition, the corresponding trace level of the trace is also stored in the TraceRecord.

The XML schema for each of the preceding extra data items has the following format.

TransactionTraceIdentifier

<TransactionTraceIdentifier>

<TransactionIdentifier >

string representation of transaction id

</TransactionIdentifier>

< CloneIdentifier >

the clone id number

</CloneIdentifier>

</TransactionTraceIdentifier>

EnlistmentTraceIdentifier

<EnlistmentTraceIdentifier>

<ResourceManagerId>

string form of guid

</ResourceManagerId>

<TransactionTraceIdentifier>

<TransactionIdentifier >

string representation of transaction id

</TransactionIdentifier>

<CloneIdentifier >

the clone id number

</CloneIdentifier>

<TransactionTraceIdentifier>

<EnlistmentIdentifier>

the enlistment id number

</EnlistmentIdentifier>

</EnlistmentTraceIdentifier>

Resource Manager Identifier

<ResourceManagerId>

string form of guid

</ResourceManagerId>

Security Issues For Tracing

When you as an administrator turn on tracing, sensitive information might be written to a trace log that is publicly viewable by default. To mitigate any possible security threat, you should consider storing the trace log in a secure location controlled by share and file system access permissions.

Send comments about this topic to Microsoft.

Copyright © 2007 by Microsoft Corporation. All rights reserved.