VSPerfCmd

The VSPerfCmd tool is used to start and stop performance data collection. It uses the following syntax:

VSPerfCmd [/U] [/options]

The following table describes VSPerfCmd tool options:

Option Description

START:mode

Starts VSPerfMon and waits until it is initialized. Requires OUTPUT switch.

mode can be one of the following:

COVERAGE - collects code coverage data

SAMPLE - collects sampling data

TRACE - collects instrumentation data

OUTPUT:filename

Specifies the output file name.

U

Redirected console output is written as Unicode. Must be first option specified.

USER:[domain\]username

Used with START option. Allows client access to the monitor from the specified account.

WAITSTART[:n]

Waits for the data collection logger to initialize. If n is specified, VSPerfCmd will wait at most n seconds. If n is not specified, VSPerfCmd will wait indefinitely. This eases use of VSPerfCmd as part of a batch process.

COUNTER:cfg

Specifies a performance counter to include in data collection. You can specify more than one counter.

cfg is counter configuration string with the following format:

  • Generic Counters

    g,counter_id[,initial_value[,name]]

  • Pentium 4 Counters

    p4,Group,EventSelect,EscrSelect,Mask[,Reload[,Name]]

where group is one of the following:

BPU

FLAME

IQ

MS

These counter groups are defined in the Intel processor manual.

QUERYCOUNTERS

Displays a list of valid counters for the platform.

EVENTS:option

The EVENTS option controls Event Trace Window (ETW) event collection. The data collected is provided by the ETW provider. The option format is:

<on | off>, <guid>[,flags[,level]]

<on | off>, <provider name>[,flags[,level]]

guid - the provider control GUID. Alternatively, a provider name may be specified in place of the guid if it is registered with WMI.

flags - a '0x' prefixed hexadecimal flags value. It is defined by the event provider. For more information, refer to ETW provider documentation.

level - determines how much information is collected. It is defined by the event provider. For more information, refer to ETW provider documentation.

Important

When CLR ETW events are enabled, additional startup data is also collected in the Trace View report. To exclude startup events from appearing in the report, use the following command:

C:\<path>VSPerfCmd -events:on, \".NET Common Language Runtime\", 0x7fffffff, 5

If you do not exclude the startup events, because these events are not listed in the Managed Object Format (MOF) file, they appear as GUIDS in the report. For more information, see Sample Managed Object Format (MOF) File.

Additionally, EVENTS option understands the following common kernel options:

on, option[,option]

where option is one of the following:

Process - Process events

Thread - Thread events

Image - Image load and unload events

Disk - Disk I/O events

Hardfault - Hard page faults

Pagefault - Soft page faults

Network - Network events

Registry - Registry access events

Note that the Kernel Provider can only be enabled. It is not disabled, nor can its flags be modified, until the monitor shuts down.

STATUS

Status applied to those processes that are profiled. It lists processes and threads and their current profile state (On/Off). For example, if a process was stopped, STATUS will not indicate this in the report. It will show the process is either profiled or not.

SHUTDOWN:[n]

Waits for monitored applications to shutdown or detach and then shuts down VSPerfMon.exe and wait for the shutdown completion. If n is specified, VSPerfCmd will wait at most n seconds. If n is not specified, VSPerfCmd will wait indefinitely. This eases use of VSPerfCmd as part of a batch process.

GLOBALON

The GLOBALON option enables profiling after a GLOBALOFF. Internally, GLOBALON option sets the global Start/Stop count to one. For more information, see GLOBALOFF.

GLOBALOFF

The GLOBALOFF option disables all profiling and no data is collected. This option does not shutdown the performance session. You can use this option to avoid collecting data during application startup or initialization phase.

To avoid collecting irrelevant data:

Start the performance monitor, VSPerfMon

PROCESSON:pid

The PROCESSON restarts profiling for a specific process using its process id (pid) after a call to PROCESSOFF. Internally, PROCESSON option sets the Start/Stop count to one for the specified process.

PROCESSOFF:pid

The PROCESSOFF option stops profiling and data collection of a specific process using its process id (pid). Other processes or threads continue to collect data. This is useful if you want to avoid gathering data before the process reaches a certain state. You can use the PROCESSON option, after the process reaches a certain state, to begin data collection. Internally, PROCESSOFF sets the Start/Stop count to zero for the specified process.

THREADON:tid

The THREADON restarts profiling for a specific thread using its thread id (tid) after a call to THREADOFF. Internally, THREADON option sets the Start/Stop count to one for the specified thread.

This option is valid only in TRACE mode.

THREADOFF:tid

The THREADOFF option stops profiling and data collection for a specific thread using its thread id (tid).

Other processes or threads continue to collect data. This is useful if you want to avoid gathering data before the thread reaches a certain state. You can use the THREADON option, after the thread reaches a certain state, to begin data collection. Internally, THREADOFF sets the Start/Stop count to zero for the specified thread.

This option is valid only in TRACE mode.

MARK:marknum[,marktext]

Inserts a mark into the global event stream, with optional text. This is useful if you want to examine the data between two marks.

marknum - any value of ULONG data type

Alternatively, you can call the MarkProfile API in your code to mark specific areas of the application. This information is only available in Call Trace report.

GC[:(allocation | lifetime)]

This option is available in sampling mode only. Enables managed memory profiling. It is possible to enable tracing of allocations only GC:allocation or allocations and lifetime of objects GC:lifetime. Default is allocations only. It is valid only with /LAUNCH option.

The following options are available in SAMPLE mode only:

Option Description

LAUNCH:executable

Launches the specified command and attaches the sample based profiler.

ARGS:args

Arguments for the launched application.

CONSOLE

Launches the specified command in a new console.

ATTACH:pid[,pid]

Attaches the sample based profiler to the specified process ids - pid or process name.

DETACH:pid[,pid]

Detaches the sample based profiler from the specified process ids - pid or process name.

DETACH

Detaches the sample based profiler from all processes.

PF[:n]

Samples on every n-th page fault (default=10).

SYS[:n]

Samples on every n-th system call (default=10).

TIMER[:n]

Samples on every n-th cycle (default=10000000).

The VSPerfDrv.Sys file allows collection of CPU data. It requires administrative privileges on the computer to install and set up VSPerfDrv.Sys file. The following options are for controlling the kernel mode device driver:

Option Description

DRIVER:Install

Installs VSPerfDrv.sys

DRIVER:Start

Starts VSPerfDrv.sys. It will attempt to install the driver if it is not already installed.

DRIVER:Stop

Stops VSPerfDrv.sys

DRIVER:Uninstall

Uninstalls VSPerfDrv.sys. It will attempt to stop the driver if it is running.

DRIVER:AddUser [ domain\] (user | group)

Adds read/write access to the kernel mode driver for the specified identity.

DRIVER: RemoveUser [domain\](user | group)

Removes all access to the kernel mode driver for the specified identity.

DRIVER:Status

Displays driver status, including a list of authorized users.

DRIVER:Autostart [(on | off)]

Enables or disables automatically starting VSPerfDrv.sys when the system is rebooted.

See Also

Reference

VSInstr
VSPerfMon
VSPerfReport
Performance Report Column Definition