Writing to the Trace Log

Writing to the trace log involves using unmanaged code to create a custom header structure, combining the custom header with a Microsoft Windows system header, registering your application as a trace provider with the Event Tracing for Windows APIs, and then calling Event Tracing for Windows APIs to write these headers to the trace log.

Trace Log Sample Code

The Trace Log Example [ http://msdn.microsoft.com/en-us/library/aa979522.aspx ] code sample shows how to write to the trace log. Following is a discussion of some of the structures, enumerations, and functions included in the example.

The ULSTraceHeader Structure

The ULSTraceHeader structure contains properties that define the trace message. Each ULSTraceHeader structure represents a single line to write to the trace log. Trace log messages may span multiple lines.

The structure definition follows:

internal struct ULSTraceHeader
{
  internal ushort Size;
  internal uint dwVersion;
  internal uint Id;
  internal Guid correlationID;
  internal TraceFlags dwFlags;
  [MarshalAs(UnmanagedType.ByValTStr, SizeConst = 32)]
  internal string wzExeName;
  [MarshalAs(UnmanagedType.ByValTStr, SizeConst = 32)]
  internal string wzProduct;
  [MarshalAs(UnmanagedType.ByValTStr, SizeConst = 32)]
  internal string wzCategory;
  [MarshalAs(UnmanagedType.ByValTStr, SizeConst = 800)]
  internal string wzMessage;
  }

Size

Total size of the ulstraceheader structure.

dwVersion

The trace log version. For Windows SharePoint Services, always set this to TRACE_VERSION_CURRENT. This enumeration is also defined in the trace log code sample.

The unique identifier for this trace message.

correlationID

A unique identifier that can be used to correlate this trace messages with other messages.

dwFlags

Specifies whether the header is the beginning, middle, or end of a specific trace log message. Each trace message has a maximum length of 800 characters. Because of this, a given trace log message may span multiple headers.

A trace log message can have multiple "middle" sections. Trace log messages are not guaranteed to appear consecutively within the trace log. However, the "middle" and "end" messages contain an asterisk beside the timestamp in the trace log. Developers can use the presence of this asterisk to identify whether a line is a continuation of a previous message. In addition, each line of the trace log includes the ProcessID and ThreadID, enabling a developer to follow the flow of a specific thread to see the surrounding messages.

The dwFlags property can be set to one of the following TraceFlags enumerations, which are also defined in the trace log code sample:

TRACE_FLAG_START This trace line is the start of a multiline trace log message.
TRACE_FLAG_MIDDLE This trace line is the middle of a multiline trace log message.
TRACE_FLAG_END This trace line is the end of a multiline trace log message.
TRACE_FLAG_ID_AS_ASCII Display each Byte from the uint contained in the ID field as an ASCII character. For example, the "a" character is "0x61" in ASCII format. Therefore, if the ID of a trace message is "0x61616161", the ID is written to the trace log as "aaaa".

A NULL value for the dwFlags property indicates no special processing has been applied.

wzExeName

The name of the application that generated the trace log message.

wzProduct

The name of the product that generated the trace log message.

wzCategory

The trace log category assigned to the trace log message. This should match one of the trace log categories defined for the application generating the trace log message.

For more information about defining categories, see Trace Log Categories [ http://msdn.microsoft.com/en-us/library/aa979668.aspx ] .

wsMessage

The text of the trace log message. Each trace message line has a maximum length of 800 characters.

The TraceSeverity Enumeration

The TraceSeverity enumeration defines the trace levels that are written to the Severity column in the trace log. These are the only valid values accepted by Windows SharePoint Services; if a trace log message line is submitted with any other value, it is written to the trace log with a severity level of "Undefined".

The trace levels defined in the code sample follow:

public enum TraceSeverity
{
  Unassigned = 0,
  CriticalEvent = 1,
  WarningEvent = 2,
  InformationEvent = 3,
  Exception = 4,
  Assert = 7,
  Unexpected = 10,
  Monitorable = 15,
  High = 20,
  Medium = 50,
  Verbose = 100,
 }

The ULSTrace Structure

The ULSTrace structure combines a Windows event trace header with the specific ULSTraceHeader structure for the trace message line.

The structure definition follows:

internal struct ULSTrace
{
  internal EVENT_TRACE_HEADER Header;
  internal ULSTraceHeader ULSHeader;
}

The ControlCallback Function

This implementation of the Event Tracing for Windows ControlCallback [ http://msdn.microsoft.com/en-us/library/aa363693.aspx ] calls Windows and requests to write trace message lines to the trace log. Windows responds with a request code of WMI_ENABLE_EVENTS when the application is enabled to write to the trace log.

The WriteTrace Function

The WriteTrace function takes the arguments passed to it and uses them to construct a ulstrace structure. It then invokes the Event Tracing for Windows TraceEvent [ http://msdn.microsoft.com/en-us/library/aa364137.aspx ] function to send the trace message to the trace log.

The Main Function

The Main function demonstrates how to use the ControlCallback and WriteTrace functions to write trace messages to the trace log. It shows how to use the ControlCallback function when registering for logging with Windows by invoking the Event Tracing for Windows RegisterTraceGuids [ http://msdn.microsoft.com/en-us/library/aa364105.aspx ] . It then invokes the WriteTrace function to write two sample message lines to the trace log. Finally, it invokes the UnregisterTraceGuids [ http://msdn.microsoft.com/en-us/library/aa364154.aspx ] to unregister the application as an event trace provider.