{"id":119,"date":"2020-10-06T15:47:43","date_gmt":"2020-10-06T22:47:43","guid":{"rendered":"https:\/\/devblogs.microsoft.com\/performance-diagnostics\/?p=119"},"modified":"2022-02-09T13:46:37","modified_gmt":"2022-02-09T21:46:37","slug":"wpr-start-and-stop-commands","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/performance-diagnostics\/wpr-start-and-stop-commands\/","title":{"rendered":"WPR Start and Stop Commands"},"content":{"rendered":"

The first step is always the hardest. It is true for WPR too. It becomes even more apparent if you try to get help text for the start command. WPR spits out a page full of texts with complex syntax options.\u00a0 It is like the first time we bought a fancy camera, eager to take a nice shot of a bird in flight but then discovering that choosing the right settings requires reading the manual. This is exactly why WPRUI exists today. It is the “Auto” setting in the Camera. Though the \u201cAuto\u201d setting of the fancy camera would take good pictures for the most time, sooner or later, the time comes to spin the dial away from the \u201cAuto\u201d. For that inevitable time, let us decipher the words.<\/p>\n

If you are not familiar with WPR, check out the previous WPR intro post<\/a>.<\/p>\n

The first step<\/h5>\n

The first step is to type wpr -help<\/code> in the command prompt. WPR provides 2 tiers of help, where the first help tier gives a list of commands about which you can request further help.<\/p>\n

\"wpr<\/p>\n

If your WPR prints out much longer list of help text, that is because you are running an older build of WPR. Current WPR in Windows ADK Insider Preview<\/a> – Build 20215 (or later) should give you the above text but, the text from older build is okay and should also give you the same help.<\/p>\n

The next step is to get help on the start command, by typing wpr -help start<\/code>. The command prints out a very long list of options and explanations. Again, if your WPR prints out much shorter texts i.e. no -onoffscenario<\/code> related options, that is also fine. It is probably because you are executing WPR from the Windows directory where the axeonoffhelper module does not exists. OnOffScenarios are used in measuring preset performance scenarios such as Boot, Standby or Shutdown. We do not need -onoffscenario<\/code> option for the purpose of this post.<\/p>\n

\"Image<\/p>\n

If we remove -onoff***<\/code> options, the start command becomes much less intimidating. The help text says -start [<filename.wprp>!]<profile><\/code> over and over. It looks like WPR needs a profile to start with. What is the profile? Is it the file with .wprp extension or something else?<\/p>\n

Profiles : Built-in and Custom<\/h5>\n

Profile is basically a preset that describes what we want to collect in the trace. There are two types of profiles, built-in and custom. The built-in profiles are like the modes in camera. The most digital camera provides modes such as Macro, Portrait, and Landscape that the camera manufacturer preset optimum shutter speed, aperture, and etc to take good photo based on the situation. WPR also provides the presets for the well-known areas such as Audio, Video, CPU, Network, and File IO\u00a0 to focus the trace for.<\/p>\n

The custom profiles are like the manual mode in camera. You need to know the events and the characteristics of the events. Making custom profiles are not very difficult. Just as with understanding the concept of camera lenses and shutter are the start of the manual mode shot, a few concepts in ETW would give you enough to start authoring the profile. The custom profile uses .wprp as the file extension. However, for the beginners, let us start looking at the presets, the built-in profiles.<\/p>\n

WPRUI conveniently shows the built-in profiles in the start UI within the check-box list whereas wpr -profiles<\/code>\u00a0command lists out all built-in profiles.<\/p>\n

\"Image
WPRUI Profiles Selection<\/figcaption><\/figure><\/p>\n

 <\/p>\n

\"Image
WPR profile list<\/figcaption><\/figure><\/p>\n

The left side is the name of the profiles and the right side is the description of the profiles. Now, we got the <profile> part of the command wpr -start [<filename.wprp>!]<profile><\/code> . Since the custom profile <filename.wprp>!<\/code> part is optional, we can start a trace by simply providing any built-in profile name, like below.<\/p>\n

To start one profile:<\/strong>\r\nwpr -start CPU\r\nwpr -start VirtualAllocation\r\nWpr -start Network\r\n\r\nTo start multiple profiles in merged sessions:<\/strong>\r\nwpr -start CPU -start VirtualAllocation -start Network<\/pre>\n
Verbosity of Profile : Verbose and Light<\/h5>\n
A profile can define two verbosity levels, verbose and light. It is like children’s building block toy where it comes with either the basic block set or a complete set. It is up to the profile author to decide what events are included in verbose and light variants. In WPR, the difference between the light and verbose variants in built-in profiles are usually the addition of stackwalk events and chatty event providers in verbose profile. One can start with the light profile and if the trace doesn’t give enough clues to investigate, then proceed with the verbose profile. The verbosity level is the last portion of the cryptic start command format in the help text [<filename.wprp>!]<profile name>[.{light|verbose}]<\/code>.<\/p>\n
wpr -start CPU.verbose (starts verbose CPU profile)<\/em>\r\nwpr -start CPU (same as above. If verbosity is omitted, verbose is selected)<\/em>\r\nwpr -start CPU.light (starts light CPU profile)<\/em><\/pre>\n
Logging Mode : File and Memory mode<\/h5>\n
Whether to log to a file or to memory is a decision we have to make. Many factors can influence the decision. In file mode, events are first collected in the buffer then flushed to the file on the disk sequentially. In memory mode, the events are written to the circular buffers in memory and only at the last moment it becomes a file through the trace merge phase. The file mode is essentially setting EVENT_TRACE_FILE_MODE_SEQUENTIAL to the session property and the memory mode is setting EVENT_TRACE_BUFFERING_MODE.<\/p>\n
Which mode to use is really based on the nature of the events and the potential impact on the system where the recording is captured. If I need to capture the trace without losing events for a long period of time, with less impact on memory, then I would use the file mode so that I can keep all the events while avoiding the circular wrap problem. If I need to capture over long period of time but only the end part is important, then I would use the memory mode or the circular file mode. Unless the events are particularly verbose that the writing to file would result in lost events or there is tight storage room for the file to grow, using the file mode make sense for most cases. There are two good articles that explain about the modes and buffers further.<\/p>\n