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.
