TraceView Utility Overview

Information in this document is subject to change without notice.

TraceView is a utility which can be used to control and display Event Tracing for Windows (ETW) information. The goal of this tool is to facilitate driver developers in using ETW in their drivers. TraceView provides an intuitive, configurable, and easy to use graphical user interface and an optional command-line interface, allowing the user to control trace log sessions. Control of trace log sessions includes starting, stopping, updating and joining currently active log sessions in progress. TraceView can also be used to consume trace events, allowing graphical display of trace event messages either from a real-time trace log provider, or from a saved log file.

Graphical User Interface

Command-Line Interface

TraceView requires that 3 DLLs be present either in the save directory with TraceView.exe or in the execution path on the system where TraceView is being executed. These DLLs are: mspdb70.dll, msvcr70.dll, and traceprt.dll. If any of these 3 DLLs are not present, TraceView will display an error when it is run, identifying the DLL that is missing. You can find mspdb70.dll and msvcr70.dll for x86 architecture systems in the \winddk\buildNumber\bin\x86 directory. You will find traceprt.dll in the \winddk\buildNumber\tools\tracing\i386 directory.

© Microsoft Corporation 2002


Creating Trace Log Sessions

Handling Trace Log Sessions

The TraceView utility is designed to handle trace log session control and trace event consumption in a coordinated, easy to use setup. TraceView is specifically geared towards the driver development community. As such, TraceView can be used to capture and display real-time trace output from drivers or display data generated previously, or off site, stored in trace log files. The following sections discuss the features, and setup details of TraceView in more detail:

  • Creating New Trace Log Sessions
  • Joining Existing Trace Log Sessions
  • Controlling Trace Log Sessions
  • Opening Existing Log Files For Display
  • User Interface Features


Creating Trace Log Sessions

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 Se ssion Window to describe that session, and creation of a new Output Display Window. This is shown below:

Top of page


Joining Existing Trace Log Sessions

If an attempt is made to create or start a trace log session in TraceView, as described in Creating New Trace Log Sessions, and that trace log session is already active on the system, a warning dialog is displayed:

The user is given three possible options at this point:

1.) Stop the session and restart it, allowing TraceView to exercise full control over the session.

2.) Join the session in progress. TraceView will still allow updates to the session, but will never attempt to stop such a session. As such, the trace log session will be unstoppable and non-removable without restarting TraceView.

3.) Abort the start operation altogether.

It can be desirable to have multiple trace event consumers consume events from the same trace provider. In addition, it is often desirable to join the NT Kernel Logger in process to access system events, or events from boot-start drivers.


Joining Existing Trace Log Sessions

Controlling Trace Log Sessions

Once a trace log session has been created, as explained in Creating New Trace Log Sessions, TraceView can be used to control activities of that session. All control options for a given session are available by right clicking the session’s line in the Trace Log Session List window in TraceView as shown here:

The possible options are:

  • Start Trace
  • Stop Trace
  • Group Sessions
  • Ungroup Sessions
  • Remove Log Session

Starting Trace Log Sessions

Newly created log sessions are started automatically. But, once stopped a log session has to be explicitly started again from the the menu above. Starting the log session both starts the providers associated with the trace log session and starts TraceView consuming events from those providers. Only stopped trace log sessions will have Start Trace as an option. Grouped trace log sessions all start together, and cannot be started individually while grouped.

Stoping Trace Log Sessions

Stopping a currently active trace log session causes the providers associated with the trace log session to stop generating events and it stops TraceView from attempting to consume events from those providers. Only currently active trace log sessions will have Stop Trace as an option. Grouped sessions all stop together and cannot be individually stopped while grouped.

Grouping Trace Log Sessions

It is possible to group multiple distinct trace log sessions together in TraceView, such that all trace log sessions have their events displayed in a single display window. Grouping is accomplished in a similar fashion to start or stop by right clicking on the session’s line in the Trace Log Session List window and selecting the appropriate option from the pop-up menu. Grouping of active trace log sessions is only supported on .NET and later operating systems. Grouping of multiple existing log file sessions is supported on all platforms supporting TraceView. ‘Group Sessions’ will only appear as a valid option if multiple trace log sessions for real-time trace providers are selected, or multiple existing log file sessions are selected, but not both. Also, for real-time trace log sessions, the sessions must all be stopped in order for the ‘Group Sessions’ to be a valid option. Again, ‘Group Sessions’ will not show up as a valid option for real-time trace log sessions on any platform prior to the .NET platforms. Once grouped, all trace log session trace output will displayed to a single display window for all trace log sessions in the group. Upon grouping, if any display windows end up having no trace log sessions associated with them, they are removed.

Ungrouping Trace Log Sessions

‘Ungroup Sessions’ is only a valid option for stopped trace log sessions. When ungrouped, all trace log sessions are automatically restarted. Ungrouped sessions are given a new display window for output.

Removing Trace Log Sessions

Only stopped trace log sessions can be removed. Removal of a log session will cause the removal of the trace log session’s information from the Trace Log Session List window, and will cause the associated display window to be deleted, if the trace log session is the last associated session with that display window.

© Microsoft Corporation 2002


Creating Trace Log Sessions

Opening Existing Log Files

Using TraceView To Open An Existing Log File

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 “Open Existing Log File” pops up the Log File Selection window. The ‘Log File Name’ edit box is where the name of the log file (.etl file) to be opened is specified. The box is initially blank, as no log file is specified. The other options let the user specify whether or not to create listing and/or summary output files, and to name those files.

The ‘…’ button to the right of the ‘Log File Name’ edit box is a browse button that brings up a file open dialog allowing the user to browse the system for the appropriate log file as shown below:

Clicking the ‘Open’ button will cause TraceView to open the log file for reading. The log file must exist, and a warning will be displayed if it does not. Once a valid log file is selected, and the ‘Open’ button selected, the Log File Selection window is updated with the new log file name:

Click the ‘OK’ button to bring up the Format Information Setup window.

Two options are available for providing trace event format information to TraceView.

1.) A PDB file which contains the format GUID information internally.

2.) TMF file(s) which have the format GUID information for the trace events.

A PDB file can be entered directly into the PDB edit box in the window above, or the ‘…’ button can be used to browse for a suitable PDB file. If a valid PDB file is selected, the previously specified log file is opened and the trace event data displayed:

Notice that the ‘State’ column in the Trace Log Session List window shows the session as ‘Existing’. This is always the state of an existing log file opened in TraceView.

If the user selected the TMF file(s) option back in the Format Information Setup window, then when the ‘OK’ button is clicked, the Format Information Source Select window appears.

The TMF location can be specified in two ways. Either the TMF files can be specified directly, or a TMF path can be specified which tells TraceView the location of the files, but lets TraceView determine which files at that location are needed. If the ‘Select TMF Files’ radio button is selected, and the user subsequently clicks ‘OK’, the following Trace Format Information Setup window is displayed:

The ‘Trace Format and Display Information’ list control lists all TMF files selected for the given log file. The list is blank in the screenshot above as no TMF files have been selected. To add a TMF file or files to the list the user clicks the ‘Add’ button and a file open dialog appears:

Multiple TMF files can be selected from this dialog. Whenever all files have been selected, clicking ‘Open’ returns back to the previous window. The window is updated with the new TMF information:

Once all desired TMFs have been listed clicking ‘Done’ causes TraceView to open the log file and display the trace event data.

If the user specifed the ‘Set TMF Search Path’ option in the Format Information Source Select window, then the Select Directory window would appear when ‘OK’ is clicked:

This window allows the user to select the path to the TMF file(s). Only one path can be used for a given log file. When ‘OK’ is clicked from this window, TraceView will open the log file and display the trace event information.

Top of page


Configurable Display

User Interface Features

In-place Editable Parameters

The parameters for a trace log session can be modified directly from the Trace Log Session List Window as shown below. All modifiable parameters are shown with dark text. Grayed out items cannot be modified. The number of parameters that can be modified changes with respect to whether the trace log session is running or not.

Modifying a value for a currently active trace log session causes an immediate update to the active trace log session. Modifying values for a stopped trace log session affects the behavior of the trace log session upon re-start.

Dockable Windows

Each of the windows can be “undocked” from the main TraceView frame window by grabbing the tool-bar type “handle” on the left of the window, and dragging it to the desired location. Such an “undocked” window is shown below:

Double clicking the gripper bar from the window will also cause the window to undock. Double clicking the title bar of an undocked window will cause it to re-dock back to the main window.

Configurable Columns

The individual columns of any of the dockable windows in TraceView can be dynamically resized. Columns can also be moved within the window. Columns may be resized in the usual way, by selecting (with the left mouse button) the divider between two columns and dragging it to the new width. To move a column, simply click and hold down the left mouse button on the column’s header and drag the column to its new position.

Pausing The Output

The output of the display windows can be paused by selecting a row, or moving the scroll handle on the right of the display. Traces will continue to be added, but the display will stay on the current line. Hitting ‘Enter’ will start the display showing the most current line again.

Eliminating Unwanted Output

It is possible to select or deselect the display of any column in any display except the “Group ID / Session Name” column in the Log Session List window which is always displayed.

Right clicking on the column header of any column will bring up a menu for that display window which has all of the columns listed with the ability to check or uncheck the name to add or remove the column from the display.

Column Sorts

Left clicking the header of any column in the display output windows will cause the data in that window to be sorted by the data in the selected column. Click the header once to sort ascending, click again to sort descending.

© Microsoft Corporation 2002


Creating Trace Log Sessions

Command-Line Interface

The TraceView utility is designed to be useful as a command line utility in addition to providing a useful graphical user interface. TraceView is intended to operate as three command-line tools in one.

  • A trace logger control tool as described in Logger Control Interface.
  • A trace event consumption tool as described in Trace Event Consumption Interface.
  • a trace format extraction tool for parsing program database files described in PDB Parsing Interface.


Creating Trace Log Sessions

Logger Control Interface

The TraceView command-line interface uses the following command-line syntax:

traceview [action] [options] | [-h | -help | -?]

The possible actions for the TraceView command-line interface are broken down into three categories:

  • Control
  • Consumption
  • Parsing

The Control actions are used to control active trace loggers. The following table describes the control interface options:

Control Actions: |
-start [LoggerName] | Starts up the [LoggerName] trace session
-stop [LoggerName] | Stops the [LoggerName] trace session
-update [LoggerName] | Updates the [LoggerName] trace session
-enable [LoggerName] | Enables providers for the [LoggerName] session
-disable [LoggerName] | Disables providers for the [LoggerName] session
-flush [LoggerName] | Flushes the [LoggerName] active buffers
-enumguid | Enumerate Registered Trace Guids
-q [LoggerName] | Query status of [LoggerName] trace session
-l | List all trace sessions
-x | Stops all active trace sessions
Control Options: |
-b <n> | Sets buffer size to <n> Kbytes
-min <n> | Sets minimum buffers
-max <n> | Sets maximum buffers
-f <name> | Log to file <name>
-append | Append to file
-prealloc | Pre-allocate
-seq <n> | Sequential logfile of up to n Mbytes
-cir <n> | Circular logfile of n Mbytes
-newfile <n> | Log to a new file after every n Mbytes
-ft <n> | Set flush timer to n seconds
-paged | Use pageable memory for buffers
-guid <file> | Start tracing for providers in file
-rt | Enable tracing in real time mode
-kd | Enable tracing in kernel debugger
-age <n> | Modify aging decay time to n minutes
-level <n> | Enable Level passed to the providers
-flag <n> | Enable Flags passed to the providers
-eflag <n> <flag...> | Enable flags (several) to providers
-pdb | Start tracing for related provider


Creating Trace Log Sessions

Trace Event Consumption Interface

The TraceView command-line interface uses the following command-line syntax:

traceview [action] [options] | [-h | -help | -?]

The possible actions for the TraceView command-line interface are broken down into three categories:

  • Control
  • Consumption
  • Parsing

The Consumption actions are used to control the receipt, formatting, and display of trace events from an active trace event provider or providers. The following table describes the trace event consumption interface options:

Consumption Actions: |
-process | Consume trace events
Consumption Options: |
-o <file> | Output filename for listing file
-display | Display output
-displayonly | Display output. Don't write to file
-nosummary | Don't create the summary file
-noprefix | Suppress any defined TRACE_FORMAT_PREFIX
-ods | Display output using OutputDebugString
-summaryonly | Don't create the listing file
-tmf <file> | Extract trace format information from specified TMF file
-pdb <file> | Extract trace format information from specified PDB file
-p <path> | TMF file search path
-v | Verbose Display


Creating Trace Log Sessions

PDB Parsing Interface

The TraceView command-line interface uses the following command-line syntax:

traceview [action] [options] | [-h | -help | -?]

The possible actions for the TraceView command-line interface are broken down into three categories:

  • Control
  • Consumption
  • Parsing

The Parsing actions are used to extract trace session control GUID, and trace event format GUID information from a program database (.PDB) file. The following table describes the PDB parsing interface options:

Parsing Actions: |
-parsepdb <pdbname> | Extract TMFs from PDB named pdbname
Parsing Options |
-p | Specifies the path to create the tmf's, by default the current directory.