A new TraceListener in Orcas: EventSchemaTraceListener [Inbar Gazit]

  • Article

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.

Comments

  • Anonymous
    March 09, 2007
    If you're using orcas, can't you just say: var myTraceSource = new System.Diagnostics.TraceSource("MyTraceSource");

  • Anonymous
    March 09, 2007
    Bruce, just because you can doesn't mean that you should and it certainly doesn't mean that you must use local type inference :)

  • Anonymous
    March 12, 2007
    Very, Very nice feature!! I gives customers to build systmes and then define what to audit no matter what dictates it - perf issues, debugging, or compliance like SOX, PCI, and others. i am taking it too far :)?

  • Anonymous
    March 12, 2007
    Could you please elaborate on where/how the schema for the events is specified? Also what happens if an event does not match the schema? Thank you.

  • Anonymous
    March 13, 2007
    The schema for the listener is specified in a validation file - event.xsd (this is a schema file)  that describes the different elements of the event that the listener will listen to. . The XSD is available from the Vista Platform SDK available here: http://www.microsoft.com/downloads/details.aspx?FamilyId=C2B1E300-F358-4523-B479-F53D234CDCCF&displaylang=en There shouldn't be any issue if the event mismatches the schema, unless validation is actually run on the resultant output. Tools that may be relying on certain elements in the schema will naturally not run if those elements are not present.

  • Anonymous
    April 03, 2007
    For developer level tracing the tracing classes held within the System.Diagnostics namespace are often

  • Anonymous
    November 19, 2007
    .NET Framework 3.5 and Visual Studio 2008 have officially shipped! Soma has the announcement on his blog