Skip to content

Update vcperf-commands.md #4375

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Feb 23, 2023
Merged
Changes from 2 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 7 additions & 7 deletions docs/build-insights/reference/vcperf-commands.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,23 +18,23 @@ This article lists and describes the commands available in *`vcperf.exe`*, and h
## Commands to start and stop traces

> [!IMPORTANT]
> The following commands all require administrative privileges.
> Unless /noadmin is provided, the following commands require administrative privileges.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Consider adding this note "Unless /noadmin is provided" in the vcperf documentation on GitHub as well.


| Option | Arguments and description |
|------------------|---------------------------|
| `/start` | `[/nocpusampling]` `<sessionName>` |
| | Tells *vcperf.exe* to start a trace under the given session name. There can only be one active session at a time on a given machine. <br/><br/> If the `/nocpusampling` option is specified, *vcperf.exe* doesn't collect CPU samples. It prevents the use of the CPU Usage (Sampled) view in Windows Performance Analyzer, but makes the collected traces smaller. <br/><br/> Once tracing is started, *vcperf.exe* returns immediately. Events are collected system-wide for all processes running on the machine. That means that you don't need to build your project from the same command prompt as the one you used to run *vcperf.exe*. For example, you can build your project from Visual Studio. |
| `/stop` | `<sessionName>` `<outputFile.etl>` |
| | Stops the trace identified by the given session name. Runs a post-processing step on the trace to generate a file viewable in Windows Performance Analyzer (WPA). For the best viewing experience, use a version of WPA that includes the C++ Build Insights add-in. For more information, see [Get started with C++ Build Insights](../get-started-with-cpp-build-insights.md). The `<outputFile.etl>` parameter specifies where to save the output file. |
| `/start` | `[/noadmin]` `[/nocpusampling]` `[/level1 \| /level2 \| /level3]` `<sessionName>` |
| | Tells *vcperf.exe* to start a trace under the given session name. When running vcperf without admin privileges, there can be more than one active session on a given machine. <br/><br/>If the `/noadmin` option is specified, *vcperf.exe* doesn't require admin privileges. "If the `/noadmin` option is specified, vcperf.exe doesn't require admin privileges, and the `/nocpusampling` flag is ignored." <br/><br/> If the `/nocpusampling` option is specified, *vcperf.exe* doesn't collect CPU samples. It prevents the use of the CPU Usage (Sampled) view in Windows Performance Analyzer, but makes the collected traces smaller. <br/><br/>The `/level1`, `/level2`, or `/level3` option is used to specify which MSVC events to collect, in increasing level of information. Level 3 includes all events. Level 2 includes all events except template instantiation events. Level 1 includes all events except template instantiation, function, and file events. If unspecified, `/level2` is selected by default.<br/><br/>Once tracing is started, *vcperf.exe* returns immediately. Events are collected system-wide for all processes running on the machine. That means that you don't need to build your project from the same command prompt as the one you used to run *vcperf.exe*. For example, you can build your project from Visual Studio. |
| `/stop` | (1) `[/templates]` `<sessionName>` `<outputFile.etl>`<br/>(2) `[/templates]` `<sessionName>` `/timetrace` `<outputFile.json>` |
| | Stops the trace identified by the given session name. Runs a post-processing step on the trace to generate a file specified by the `<outputFile>` parameter.<br/><br/>If the `/templates` option is specified, also analyze template instantiation events.<br/><br/>(1) Generates a file viewable in Windows Performance Analyzer (WPA). The output file requires a `.etl` extension.<br/>(2) Generates a file viewable in Microsoft Edge's trace viewer ([edge://tracing](edge://tracing)). The output file requires a `.json` extension. |
| `/stopnoanalyze` | `<sessionName>` `<rawOutputFile.etl>` |
| | Stops the trace identified by the given session name and writes the raw, unprocessed data in the specified output file. The resulting file isn't meant to be viewed in WPA. <br/><br/> The post-processing step involved in the `/stop` command can sometimes be lengthy. You can use the `/stopnoanalyze` command to delay this post-processing step. Use the `/analyze` command when you're ready to produce a file viewable in Windows Performance Analyzer. |

## Miscellaneous commands

| Option | Arguments and description |
|------------|---------------------------|
| `/analyze` | `<rawInputFile.etl> <outputFile.etl>` |
| | Accepts a raw trace file produced by the `/stopnoanalyze` command. Runs a post-processing step on this trace to generate a file viewable in Windows Performance Analyzer. For the best viewing experience, use a version of WPA that includes the C++ Build Insights add-in. For more information, see [Get started with C++ Build Insights](../get-started-with-cpp-build-insights.md). |
| `/analyze` | (1) `[/templates]` `<rawInputFile.etl>` `<outputFile.etl>`<br/>(2) `[/templates]` `<rawInputFile.etl>` `/timetrace` `<outputFile.json>` |
| | Accepts a raw trace file produced by the `/stopnoanalyze` command. Runs a post-processing step on this trace to generate a file specified by the `<outputFile>` parameter.<br/><br/>If the `/templates` option is specified, also analyze template instantiation events.<br/><br/>(1) Generates a file viewable in Windows Performance Analyzer (WPA). The output file requires a `.etl` extension.<br/>(2) Generates a file viewable in Microsoft Edge's trace viewer ([edge://tracing](edge://tracing)). The output file requires a `.json` extension. |

## See also

Expand Down