Creating New Trace Log Sessions

Using TraceView To Create A New Log Session

TraceView can be started by running it from the command-line with no options, or double clicking its icon in Windows Explorer. A new trace logging session may be started by selecting "File" and then "Create New Log Session". Alternatively, right clicking any blank area of the Log Session window causes a pop-up menu to appear from which appropriate action can be selected.

Selecting “Create New Log Session” pops up the Create New Log Session window. This window lists all the providers that are active for this log session by PDB file name, CTL file name, Kernel Logger name, or control GUID, depending on how the control information is provided. Since no trace providers have been defined yet, the Provider List is initially empty.

To add a trace provider, click the Add Provider button to launch the Provider Control GUID Setup dialog:

There are four possible way to identify a trace provider to TraceView:

1. Identify a PDB file associated with the trace provider. For example, when building a driver that includes support for ETW, the created PDB file contains both the Control and Format GUID information used by the driver. Identifying the PDB file associated with a trace provider is the quickest and easiest way to get started with tracing.

2. Identify a GUID control file (by convention, file type .CTL), which is a text file containing the control GUID. This is the same .CTL file type that may be familiar from using the TraceLog command-line utility.

3. Manually enter (or paste) the control GUID into the space provided by TraceView in the format: 00000000-0000-0000-0000-000000000000.

4. The NT Kernel Logger can be selected as a provider and the Kernel Logger control information will be used automatically.

The method used to identify the trace provider is selected by clicking on the appropriate radio button in the dialog above. If the PDB File or CTL File method is selected, the file name and path information may be entered manually or the browse button (the button with “…” to the right of the edit box for the file name) may be used to browse for the correct file. For example, clicking the “…” browse button to the right of the PDB file edit box, brings up the following dialog, which has been used to selected the file tracedrv.pdb:

Clicking “Open” in the Open PDB File dialog opens the indicated file and returns to the Provider Control GUID Setup dialog:

Clicking “OK” in the Provider Control GUID Setup dialog returns to the Log Session Providers Dialog. The name of the PDB file has now been filled into the Provider List indicating a provider has been supplied.

At this point, additional providers may be added to this log session by clicking “Add Provider” again and following the procedures above.

When all providers have been identified, the “Next” button is selected to display the Log Session Options pane of the Create New Log Session dialog:

The Log Session Options pane allows the user to define whether the trace log session will generate real-time output, or whether data will be logged to a trace log data (.etl) file, or both. The name of the binary log file may be changed or browsed for from this dialog. A unique name for the log session may be provided as well. Default names for both the log file and log session are provided as shown.

Trace log listing and summary output files can also be generated by TraceView. These files are identical to those generated by the TraceFmt command-line utility. Control of the generation of these files, and setting of their names, is accomplished by clicking on the “Advanced Log Session Options >>” button.

The default log session options can be changed by clicking on the “Advanced Log Session Options >>” button and selecting the Log Session Parameter Options tab of the Advanced Log Session Options dialog:

Grayed out items cannot be modified, but parameters listed with dark text may have their values altered. Some parameters are exclusive of others, so providing values for certain parameters may clear or alter the values of others. Clicking on the “OK” button exits the Advanced Log Session Options dialog.

Clicking on the “Finish” button back in the Create New Log Session dialog exits the dialog. TraceView displays information about the newly created log session in the Log Session Window (the top window pane in the screen shot below), and an empty (until trace event are picked up) Log Session Output Display Window (the bottom pane):

IMPORTANT NOTE: There is a column in the log session display titled ‘State’ which indicates the running state of the log session. The possible values in this column are “GROUPING”, “UNGROUPING”, “RUNNING”, “STOPPING”, “STOPPED”, or “EXISTING”.

The trace log session will start automatically upon successful creation. Right clicking on the log session line associated with the desired log session in the upper window brings up a menu with options for the log session:

Trace output will begin to appear in the (lower) Output Display Window as soon as it’s created.

In addition to displaying the trace log session parameters and the state of the log session in the Trace Log Session List Window, three columns, Event Count, Lost Events, and Buffers Read, give up to date values for active log sessions.

Creating Additional Log Sessions

Additional Log Sessions may be added to TraceView the same way as the first. Each log session results in a new line being added to the Log Session Window to describe that session, and creation of a new Output Display Window. This is shown below:

Top of page