This command-line tool starts, stops, or enables trace logging. The
results of event logging can be viewed with either the TraceDmp or
Reducer tools.
TraceLog acts like a Windows Management Instrumentation (WMI)
controller link in that it helps control the various parameters
associated with the logging of event traces.
You can use TraceLog to do the following:
Start, stop, update, and query a trace session.
Set up a buffer in which the event traces are logged by the
provider.
Create a log file to which the buffer is flushed. You can also set
up a real-time mode in which the buffer is delivered directly to the
consumer.
Provide more specific control over system-level tracing.
Control the level of tracing required.
TraceLog first creates a cyclical buffer and enables tracing. The
WMI provider, such as the operating system or an application (the
directory service, for example), starts tracing events. These traces
are written to the buffer. As the buffer is filled, the data is
written to a log file. If real-time mode is set, the consumer (such
as TraceDmp or another application) can take data directly from the
buffer.
TraceLog Display Logger Name Name of the logging instance. For the
kernel, the name is NT Kernel Logger. Otherwise, it defaults to what
you have provided. (See Example 2 in "TraceLog Examples.")
Logger Id ID of the logger.
Logger Thread Id Thread ID of the logger.
Buffer Size The size of the buffer allocation.
Maximum Buffers The maximum buffers in pool.
Minimum Buffers The number of buffers to pre-allocate.
Number of Buffers The number of buffers in use.
Free Buffers The number of buffers in the free list.
Buffers Written The number of buffers that have already been written
to.
Files Required
Tracelog.exe
Control.guid (contains the GUIDs of the providers for which tracing
is possible)
TraceLog Topics
TraceLog Syntax
TraceLog Examples
Overview of Event Tracing
Management options: Starting, stopping, updating, and querying a
trace session
-guid file
starts tracing for providers in the file specified. The file with a
list of GUIDs for event tracing. Each GUID corresponds to a
traceable event. You cannot just provide a GUID, even if it is just
one GUID; it has to be included in a file. To begin system tracing,
no GUID file is necessary (see Example 1 in "TraceLog Examples"). To
enable directory service event tracing, the control.guid file has
been provided with the tool (see Example 2 in "TraceLog Examples").
-start [logger_name]
starts a trace session. You need to give a logger name for the
events to trace. If it is a system trace, you don't need to specify
a logger name, since the default logger name would be taken as "NT
kernel logger" (see Example 1 and Example 2 in "TraceLog Examples").
Note
System and application traces could be started simultaneously, but
you must specify a different logger name for the application trace.
-stop [logger_name]
stops a trace session. You have to specify the instance name of the
events for which you would like tracing to discontinue. For stopping
system tracing, you need not specify any logger name (see Example 4
in "TraceLog Examples").
-update [options] [logger_name]
updates the current trace session. This would be useful when you
would like to change the file name of the log file (maybe directing
it to a different disk) or change some buffer parameters, or change
to real time mode, or some other changes. The following options can
be updated for the kernel logger (system trace): Option Action
-rt Mode switch. To switch to and from real time mode.
-f logfile_name New logfile name to switch logfile.
-ft n Change the flush timer.
-max n Change the maximum number of buffers.
"-nodisk" "-noprocess" "-nothread" "-nonet" "-fio" "-pf" "-hf" "-img"
"-cm" Flags. These flags apply only to the NT kernel logger.
All updates should be provided in a single update statement. For
example, to switch to real-time processing and increase the maximum
number of buffers, type the following at the command line:
tracelog –update –rt –max 40-x
stops all active trace sessions. Stops all system and otherwise
traces. Completes halt to event tracing.
-l
queries to list all the ongoing traces.
-q
queries to list the system trace only.
Buffer options
-b n
sets the buffer size to n kilobytes. Gives the buffer size. You
would generally like the size to be a multiple of the page size (for
Intel architecture-based computers the page size is 4 kilobytes). A
small size increases the flush frequency. The kernel, depending on
the memory capacity, chooses the default.
-min n
sets minimum buffers. This is the number of buffers to pre-allocate.
If logging is frequent, set a higher number. Default is 2.
-max n
sets maximum buffers in pool. This limits the amount of memory
consumed for each tracing session. Default is 25.
-ft n_seconds
sets flush timer to n seconds. After a buffer gets filled up, it
gets flushed to the log file or to the consumer for real-time
tracing. This option allows you to specify the time after which to
force a flush. Especially useful for real-time tracing.
-age n_minutes
modifies aging decay time. If a buffer has been allocated but isn't
being used, or the last n minutes have passed, it is freed. This is
generally useful for light tracing, so that memory is freed. This
has nothing to do with maximum buffers that have been allocated.
That value remains the same. Default is 15 minutes.
Log file options
-rt [b]
enables tracing in real-time mode.
-f name
logs to name file. Specifies the log file to which the buffer will
be flushed. The consumer will use this file for its analysis. The
default name and location is c:\logfile.etl. Use a different file
name for each instance of tracing required (-o filename option).
-seq n_mbytes
creates sequential logfile of up to n megabytes. Indicates that the
logging should be sequential and the file size is n megabytes. By
default, logging is sequential.
-cir n_mbytes
creates cyclical logfile of n megabytes. Indicates that logging
should be cyclical. After the file size is reached, logging starts
from the beginning of the file again. The header information is not
lost, however.
System level tracing options
These options provide more specific control over system level
(kernel) tracing. In order to understand these controls, it is
important to understand something about system level tracing. The
following events can be traced at the system level:
Process start/end
Disk I/O
Network TCP/IP, UDP/IP
Thread start/end
Image load
Registry calls
File I/O
Page fault
Of these, the first four are enabled by default. The last four are
not enabled, as this would generate a significant amount of extra
load (resource utilization), which is best to avoid.
-nf n
logs sequentially to new file every n Mb.
-fio
enables file I/O tracing.
-pf
enables page faults tracing.
-hf
enables hard faults tracing. Hard page faults are those that involve
a physical read, such as: read from the disk.
-img
enables image load tracing.
-um
processes private tracing. In this case, the buffer is established
in the private process space instead of the kernel space.
Note
By default, the buffer is started in the kernel space.
Provider-specific options: Provider-level options
In order to use the following options, the provider should have this
functionality enabled. One would therefore have to check with the
provider (like the operating system or the directory service),
before using these options.
-level n
provider-specific: A provider could have number of levels of
tracing. A higher number would indicate a deeper level of tracing.
-flags n
provider-specific: Performs more specific tracing. The flag passed
depends on functionality available in the provider used.
[-h | -help | -?]
displays command-line help.
The default with no options is tracelog -q
Example 1: System Event Tracing Sample Output
The default log file is c:\logfile.etl
Logger Started...
Operation Status: 0L
The operation completed successfully.
Logger Name: NT Kernel Logger
Logger Id: ffff
Logger Thread Id: 1360
Buffer Size: 8 Kb
Maximum Buffers: 25
Minimum Buffers: 2
Number of Buffers: 2
Free Buffers: 1
Buffers Written: 3
Events Lost: 0
Log Buffers Lost: 0
Real Time Buffers Lost: 0
Log File Mode: Sequential
Enabled tracing: Process Thread Disk TcpIp
Log Filename: C:\LogFile.EtlExample 2: Start Directory Service Event
Tracing to Logfile
Directory service (logger name) tracing is started and results are
written to log file mylogfile.etl.
Example 3: Start Directory Service Event Tracing to Command Window
To start directory service event tracing and route the output to the
command window, type the following at the command line:
tracelog –start ds
Information on the event tracing is displayed in the command window.
The output will look similar to the following sample:
Logger Started...
Operation Status: 0L
The operation completed successfully.
Logger Name: ds
Logger Id: 2
Logger Thread Id: 1360
Buffer Size: 8 Kb
Maximum Buffers: 25
Minimum Buffers: 2
Number of Buffers: 2
Free Buffers: 1
Buffers Written: 1
Events Lost: 0
Log Buffers Lost: 0
Real Time Buffers Lost: 0
Log File Mode: Sequential
Log Filename: C:\LogFile.Etl
Example 4: Stop Event Tracing
When you want to stop directory tracing, type the following at the
command line:
tracelog–stop
Output like the following sample will be displayed in the command
window:
Operation Status: 0L
The operation completed successfully.
Logger Name: NT Kernel Logger
Logger Id: ffff
Logger Thread Id: 1360
Buffer Size: 8 Kb
Maximum Buffers: 25
Minimum Buffers: 2
Number of Buffers: 2
Free Buffers: 2
Buffers Written: 7
Events Lost: 0
Log Buffers Lost: 0
Real Time Buffers Lost: 0
Log File Mode: Sequential
Log Filename: C:\LogFile.Etl
Event tracing is a new capability in Windows 2000 that can measure
activity as it happens on your system. It works on the Windows
Management Instrumentation (WMI) model. In this model, there is a
provider, a controller, and a consumer, which all act independently.
An event is any operating system or application activity of interest
generated by a provider, especially relevant to issues of
performance. Typically the activity is related to the use of a
resource such as the processor or disk. Examples of operating system
events are disk I/O and page faults. Examples of application events
are the start and end of a transaction such as the start and end of
a directory service search operation.
A trace is a continuous series of snapshots of the system
performance. Information related to system performance is recorded
simultaneously with each snapshot.
A provider can be the operating system or the directory service. It
registers traceable events, and each event is associated with a
specific, unique GUID. You can get a list of all the events and
their GUIDs by running WBEMTest from the Run dialog box. After
registering its traceable events, the provider continues its usual
activity.
When tracing starts, the controller takes over. It creates a buffer,
where the event traces are recorded. Tracing is then enabled for
those events that the controller has been instructed to monitor,
typically by supplying the event’s GUID. The controller can be made
more complex by giving it the ability to control various parameters
with respect to the buffer, the log file, the type of tracing, and
so on.
The consumer converts the logged traces to a readable form for
further analysis. Once again, the consumer could be a more
sophisticated application, which could trigger an event based on a
value in the event trace log.
Event tracing has several uses. It can do the following:
Supplement counters to derive various system metrics. Not all system
metrics are acquired by using simple, raw counters. For example,
event tracing allows you to determine the response time metric.
Perform a more detailed analysis of system events. Because you can
get additional system metrics with the use of event tracing, you are
better able to understand your system performance and to do capacity
planning.
Identify system problems and bottlenecks. Developers can use event
tracing for initial problem identification and detection of system
bottlenecks.
Notes
Because event tracing is more resource-intensive than regular
performance counters, it should not be used on a continuous basis.
For WMI model details, see the Microsoft Platform SDK.
