It is hard to start a new blog series without an intro. WPR is an acronym for Windows Performance Recorder, which records ETW(Event Tracing for Windows) traces. WPR is one of the two main components of Windows Performance Toolkit. The other one is WPA (Windows Performance Analyzer). As one might guess from their names, WPR “records” a trace and WPA visually “plays” the trace so we can review the performance of components. Windows Performance Toolkit (WPT) is included in Windows Assessment and Deployment kit.

Before we go too much into the article, here is the list of acronyms to be used frequently.

• WPR – Windows Performance Recorder Command-line application
• WPRUI – Windows Performance Recorder User Interface application
• WPA – Windows Performance Analyzer
• WPT – Windows Performance Toolkit
• ETW – Event Tracing for Windows

Thankfully, WPR is very lightweight which allows it to ship with Windows OS. That is right. You don’t need to install anything. Just bring up Command prompt, and you can start typing WPR commands such as wpr -help. However, WPR requires knowledge about Event Tracing, and trace providers to apply manual control over the tracing session. Without that knowledge, WPR’s commands, options, and profiles are a foreign language that you have never heard of.

I hope that this blog series would help a variety of engineers by providing background and guidance without drilling too much into the technology behind. If you are one of these people, welcome!

• Software engineer who wants to diagnose his/her apps or drivers.
• Program manager who wants to profile performance of apps or drivers.
• Testers who wants to measure performance of apps or drivers.
• Someone who likes to poke around new tools.

Installation

If you want to just use wpr.exe command-line tool, it is included in the OS (Win10 or above). If you want to use the user interface version of WPR (WPRUI) or other tools that come with WPT, then the MSDN doc would help you get started. To make it easier, here are the steps to install.

1. Go to https://aka.ms/adk and download the Windows ADK for Windows 10. “Insider Preview” version ADK provides the latest binaries whereas specific version gives you “official”. Of course, if you use Windows 8, or Server 2012, download Windows ADK for windows 8.1.
2. Select “Windows Performance Toolkit” during ADK setup unless other tools are needed.

   

3. (Optional) Add the installation directory to %Path%. The installation directory is: C:\Program Files (x86)\Windows Kits\10\Windows Performance Toolkit. You may want to make sure the installed version of WPR is used vs. the default one included in the OS, i.e. from C:\windows\system32.

WPRUI vs. WPR

WPR comes in two flavors, WPRUI(wprui.exe) and CLI (Command Line Interface, Wpr.exe). They both share the same dll but not all the features can be accessed through UI. WPRUI is an entry level automatic sedan whereas WPR is a high-end manual transmission car. If you drive only to near-by groceries and the office via well-known highways you can do that with WPRUI. However, if your needs are versatile and you want to ride the car for a long time, then you would probably want to choose a high-end car though it is manual.

The common factors of both CLI and WPRUI are:

• Start/Save/Cancel trace.
• Show simple status of trace.
• Provide well-known scenario (aka. built-in) profiles.
• Support custom profiles.
• Supports on-off scenarios.

Everything else are provided by CLI. You can only do these things through CLI;

• Show detailed status of trace including profile name, collectors, and providers.
• Displays detailed information about profiles.
• Exports built-in profile to a custom profile.
• Start/stop/cancel boot traces (autologger).
• Configure and take heap snapshots.
• Provides hardware counter utility functions.

Above list are not the whole list but the popular electives.

E_WPRC_DUPLICATE_INSTANCE_RUNNING

One thing that stumbles the new WPT users is E_WPRC_DUPLICATE_INSTANCE_RUNNING error (0xc5580601). This error can happen on both CLI and UI. This error usually happens when a user executes WPRUI, has the window open, then executes WPR CLI to try something else. Then BAM! WPR complains. Another case, a user tries to open a second WPRUI, while WPRUI is already running in the background. BAM! Same error message box shows up.

WPR assigns an “instance name” to an instance of the app. When you start WPR, it gives the default instance name, “WprApp”. Unless you give another instance name, WPR won’t allow to run another instance simultaneously if the instance name is same. This is because WPR uses the instance name to be the part of “session name”. When you start a trace, WPR is starting a trace “session” on your behalf and gives it a session name. In ETW tracing world, the session name is a steering wheel to the session, directly related to the tracing handle. Other ETW tracing applications such as Xperf, and Tracelog call the session name as “LoggerName“. Most other application require the user to provide the logger name (session name) to control the session but WPR gives you the default one unless specified. This is a thoughtful gesture but sometimes, well, a stumbling block.

The solution is simple. If you start using WPRUI, just keep using it until the tracing is done. Don’t try to use WPR CLI or another WPRUI in the middle. Or better yet just use WPR CLI for all your tracing needs. Of course, you can also solve this by setting another instance name. WPR CLI has an option (-instancename) to set the instance name. WPRUI also can take the same option through command line.  With detailed explanation and examples, I will explain more about the instance name in the next post.

Closing

Learning a new tool is never an easy job. ETW tools are one of the worst if you are not familiar with Event Tracing for Window (ETW) concepts. We will eventually get to ETW technology and more but the goal of this blog is to help the engineers to start using WPR, and help with issues around using WPR. In this first post, I have introduced list of acronyms that are used commonly, installation steps, the difference between WPR and WPRUI, and finally about the instance name and the error. With this WPR post series, I hope to lower the bar to the performance investigation.