A new TraceListener in Orcas: EventSchemaTraceListener [Inbar Gazit]

TraceListener is an abstract class representing a listener object that is used to log event that a TraceSource is producing. In .NET 2.0 we have a few existing implementations such as ConsoleTraceListener for logging events to the standard console and TextWriterTraceListener that is used for logging events to a text file. In our new version of the .NET Framework code-named "Orcas" we introduce a new type of TraceListener. (You can download the latest CTP here)

This new trace listener introduces the concept of an event schema which is essentially an XML file that describes the meta-data that traced events would share. This is different from the existing XmlWriterTraceListener in a few ways. First, it requires all events to conform to a schema therefore enabling tools to compare events that came from a variety of sources. It is also designed with thread-safety in mind which means it is optimized for multithreading scenarios. In addition this new listener enables tracing to go beyond just the current thread or process maintaining the same information along the way. It is utilizing the same technology that exists in Window Vista's new Event Viewer and other advanced tracing tools. The technology is known as Event Tracing for Windows (ETW).

Just like any other TraceListener you can either configure it using the application’s config file or you can do it in your code by creating a new object of this type. We encourage you to use the config file as it allows you to dynamically make changes to your tracing needs w/o rebuilding the application.

Here is an example of a how to change your config file to use an EventSchemaTraceListener. We will be adding a new listener and removing the default listener for performance reasons. The new listener is found in the new System.Core.dll assembly that you can find when you install the CTP.  There a few other knobs and levers you can use to change the tracing options like buffer size, maximum file size, meta-data that is added to each event and log file options.

<configuration>

    <system.diagnostics>

        <sources>

            <source name="MyTraceSource" >

                <listeners>

                    <remove name="Default"/>

                        <add name="myListener" type="System.Diagnostics.EventSchemaTraceListener, system.core, Version=3.5.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089"

                            initializeData="myLog.xml"

                            traceOutputOptions="ProcessId, CallStack, Timestamp"

                            bufferSize="65536"

                            maximumFileSize="10240000"

                            logRetentionOption="UnlimitedSequentialFiles"

                            maximumNumberOfFiles="5"/>

                    </listeners>

            </source>

        </sources>

    </system.diagnostics>

Making the changes in the config file allows you to make changes to an existing application’s trace without the need to rebuild it. It does however require you to restart the application as the config file is only loaded once as startup. If you want to make dynamic changes while your application run — you would have to do it through the code by providing your own hooks for dynamic changes. We may consider adding features like this in future versions.

The file myLog.xml will contain the trace information which includes the following elements: CallStack, Computer, Correlation (AcitvityID), Data, Event, EventData, EventID, Execution (ProcessID & ThreadID), Level, LogicalOperationStack, OpCode, Provider (GUID), RenderingInfo (Culture), System (Name), TimeCreated (SystemTime), TimeStamp and UserData.

In order to use any listener, your application has to have a TraceSource object. Then, throughout your code you can trace various things with various switches to various listeners. If you already have an existing application using TraceSource — you can simply add the new listener type to your config file and you’re done. Note that in order to do that you must first install the new code-name "Orcas" version of the Framework. Also, to fully take advantage of the new ETW technology you need to be running Windows Vista.

Here is a quick code snippet of how that works in your app:

// create new TraceSource

System.Diagnostics.TraceSource myTraceSource;

myTraceSource = new System.Diagnostics.TraceSource("MyTraceSource");

// set switch level to critical

myTraceSource.Switch.Level = System.Diagnostics.SourceLevels.Critical;

// trace data

myTraceSource.TraceData(System.Diagnostics.TraceEventType.Critical, 1001, myClass);

Stay tuned for additional information about Tracing and Diagnostics in upcoming blogs. And feel free to ping with any questions you may have.

Update: You can find the latest information about ETW in Vista in this "hot from the press" article in MSDN magazine.

Next week Justin and Kim will finish off the three part series of blog posts on Long Paths in .NET.

Update (8/6/2007) : Updated the XML config example to fully qualify the EventSchemaTraceListener type.