Skip to content

Commit 16e26da

Browse files
jasonrandrewsjasonrandrews
authored
Merge pull request #1358 from jasonrandrews/review
Review the WPA plugin install guide
2 parents fc84d71 + 7be8574 commit 16e26da

File tree

1 file changed

+73
-57
lines changed

1 file changed

+73
-57
lines changed

‎content/install-guides/windows-perf-wpa-plugin.md‎

Lines changed: 73 additions & 57 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,8 @@
11
---
22
### Title the install tools article with the name of the tool to be installed
33
### Include vendor name where appropriate
4-
title: WindowsPerf Ecosystem - the Windows Performance Analyzer (WPA) Plugin
5-
minutes_to_complete: 5
4+
title: Windows Performance Analyzer (WPA) Plugin
5+
minutes_to_complete: 15
66

77
official_docs: https://github.com/arm-developer-tools/windowsperf-wpa-plugin
88

@@ -16,10 +16,9 @@ additional_search_terms:
1616
- windows
1717
- woa
1818
- windows on arm
19-
- open source windows on arm
2019
- windows performance analyzer
2120
- wpa
22-
- windowsperf
21+
2322
### FIXED, DO NOT MODIFY
2423
weight: 1 # Defines page ordering. Must be 1 for first (or only) page.
2524
tool_install: true # Set to true to be listed in main selection page, else false
@@ -28,94 +27,111 @@ multitool_install_part: false # Set to true if a sub-page of a multi-page articl
2827
layout: installtoolsall # DO NOT MODIFY. Always true for tool install articles
2928
---
3029

31-
## Introduction
30+
## What is the Windows Performance Analyzer plugin?
3231

33-
[**WindowsPerf**](https://github.com/arm-developer-tools/windowsperf) is a lightweight performance profiling tool inspired by Linux perf, specifically tailored for Windows on Arm.
34-
It leverages the Arm64 PMU (Performance Monitor Unit) and its hardware counters to offer precise profiling capabilities.
35-
The **WindowsPerf WPA plugin** bridges the gap between the detailed output of **WindowsPerf** and the powerful capabilities of **Windows Performance Analyzer**.
32+
The Windows Performance Analyzer plugin connects Windows Perf to the Windows Performance Analyzer (WPA).
3633

37-
The plugin is built on the [`microsoft-performance-toolkit-sdk`](https://github.com/microsoft/microsoft-performance-toolkit-sdk) and is shipped as a single `.dll` file.
34+
[WindowsPerf](https://github.com/arm-developer-tools/windowsperf) is a lightweight performance profiling tool inspired by Linux Perf and designed for Windows on Arm.
3835

36+
Windows Performance Analyzer (WPA) is a tool that creates graphs and data tables of Event Tracing for Windows (ETW) events that are recorded by Windows Performance Recorder (WPR), Xperf, or an assessment that is run in the Assessment Platform. WPA opens event trace log (ETL) files for analysis.
3937

40-
**Windows Performance Analyzer (WPA)** is a tool that creates graphs and data tables of Event Tracing for Windows (ETW) events that are recorded by Windows Performance Recorder (WPR), Xperf, or an assessment that is run in the Assessment Platform. WPA can open any event trace log (ETL) file for analysis.
38+
The WPA plugin is built using the [Microsoft Performance Toolkit SDK](https://github.com/microsoft/microsoft-performance-toolkit-sdk), a collection of tools to create and extend performance analysis applications. The plugin parses json output from WidowsPerf so that it can be visualized in WPA.
4139

42-
WPA's capabilities can be expanded upon using the `microsoft-performance-toolkit-sdk` by creating plugins which enables parsing any type of data (`.json` in this case).
40+
## What are some of the features of the WPA plugin?
4341

42+
The WindowsPerf GUI extension is composed of several key features, each designed to streamline the user experience:
4443

45-
## A Glimpse of the available features
44+
### What is the timeline view?
4645

47-
The WindowsPerf GUI extension is composed of several key features, each designed to streamline the user experience:
46+
The timeline view visualizes the `wperf stat` timeline data plotted by event group.
4847

49-
- **Timeline View**: Visualize a `wperf stat` timeline command output as a plotted graph grouped by event group.
50-
![Timeline By Core Table](_images/wpa-timeline-by-core.png)
48+
![Timeline By Core Table](/install-guides/_images/wpa-timeline-by-core.png)
5149

52-
- **Telemetry View**: Display telemetry events grouped by unit ready to be compared and diagnosed.
53-
![Telemetry Table](_images/wpa-telemetry-table.png)
50+
### What is the telemetry view?
5451

55-
## Getting Started
56-
### Installation
52+
The telemetry view displays telemetry events grouped by unit.
5753

58-
WPA is included in the Windows Assessment and Deployment Kit (Windows ADK) that can be downloaded [here](https://go.microsoft.com/fwlink/?linkid=2243390).
54+
![Telemetry Table](/install-guides/_images/wpa-telemetry-table.png)
5955

60-
> The wperf WPA plugin requires a WPA version of `11.0.7.2` or higher.
56+
## How do I install the WPA plugin?
6157

62-
Once downloaded, make sure that "Windows Performance Toolkit" checkbox is checked under "Select the features you want to install/change".
58+
Before using the WPA plugin, make sure you have installed WPA.
6359

64-
![WPA Installation](_images/wpa-installation.png)
60+
### Windows Performance Analyzer
6561

66-
The plugin can be downloaded from the [releases page](https://github.com/arm-developer-tools/windowsperf-wpa-plugin/releases).
62+
WPA is included in the Windows Assessment and Deployment Kit (Windows ADK) that can be downloaded from [Microsoft](https://go.microsoft.com/fwlink/?linkid=2243390).
6763

68-
To install the plugin you have the option between:
64+
{{% notice Note %}}
65+
The WPA plugin requires WPA version `11.0.7.2` or higher.
66+
{{% /notice %}}
6967

70-
- Moving the plugin dll to the **CustomDataSources** directory next to the WPA executable (defaults to `C:\\Program Files (x86)\Windows Kits\10\Windows Performance Toolkit\CustomDataSources`).
71-
- Setting up the `WPA_ADDITIONAL_SEARCH_DIRECTORIES` env variable and moving the dll to that directory
72-
- Calling `wpa` from the command line and passing the plugin directory to the `-addsearchdir` flag (example : `wpa -addsearchdir "%USERPROFILE%\plugins"`).
68+
Run the downloaded `adksetup.exe` program.
7369

74-
<img
75-
src="_images/about-wpa.png"
76-
alt="About WPA"
77-
style="display: block; margin: 0 auto"
78-
/>
70+
Specify the default installation location and accept the license agreement.
7971

80-
> To verify that the plugin is loaded successfully, launch WPA then the plugin should appear under Help > About Windows Performance Analyzer.
72+
Make sure that "Windows Performance Toolkit" is checked under "Select the features you want to install".
8173

74+
![WPA Installation](/install-guides/_images/wpa-installation.png)
8275

83-
### Running from the command line
76+
Finally, click Install.
8477

85-
After installing WPA, it should be added automatically to the path environnment variable.
86-
If it's not the case, add the WPA directory (defaults to `C:\\Program Files (x86)\Windows Kits\10\Windows Performance Toolkit`) to your environnment variable.
78+
### Windows Performance Analyzer plugin
8779

80+
The plugin is a single `.dll` file.
8881

89-
To open a json file directly from the command line, you can use the `-i` flag to specify the file path to open.
82+
Download a `.zip` file from the [GitHub releases page](https://github.com/arm-developer-tools/windowsperf-wpa-plugin/releases).
83+
84+
To download the latest version from the command prompt:
85+
86+
```console
87+
mkdir wpa-plugin
88+
cd wpa-plugin
89+
curl -L -O https://github.com/arm-developer-tools/windowsperf-wpa-plugin/releases/download/1.0.2/wpa-plugin-1.0.2.zip
90+
```
91+
92+
Extract the `.dll` file from the downloaded `.zip` file.
93+
94+
```console
95+
tar -xmf wpa-plugin-1.0.2.zip
96+
```
97+
98+
You now have the file `WPAPlugin.dll` in your `wpa-plugin` directory.
99+
100+
There are three ways you can install the `WPAPlugin.dll` file:
101+
102+
###### 1. Copy the plugin dll to the CustomDataSources directory next to the WPA executable.
90103

91-
Example: to open a `timeline_long.json` that sits in the Downloads directory, run the following command in the command line:
104+
The default location is:
105+
`C:\\Program Files (x86)\Windows Kits\10\Windows Performance Toolkit\CustomDataSources`
92106

93-
`wpa -i \"%USERPROFILE%\\Downloads\\timeline_long.json\"`
107+
###### 2. Set an environment variable
94108

95-
### Running in debug mode
109+
Set the `WPA_ADDITIONAL_SEARCH_DIRECTORIES` environment variable to the location of the DLL file.
96110

97-
To run the plugin in debug mode, clone the repository then edit `WPAPlugin/Properties/launchSettings.json` file.
111+
###### 3. Start WPA from the command line and pass the plugin directory location using a flag.
98112

99-
```json
100-
{
101-
"profiles": {
102-
"Debug": {
103-
"commandName": "Executable",
104-
"executablePath": "C:\\Program Files (x86)\\Windows Kits\\10\\Windows Performance Toolkit\\wpa.exe",
105-
"commandLineArgs": "-nodefault -addsearchdir \"%USERPROFILE%\\devProjects\\wpa-plugin\\WPAPlugin\\bin\\Debug\\netstandard2.0\""
106-
}
107-
}
108-
}
113+
Use the `-addsearchdir` flag for `wpa`:
109114

115+
```bash
116+
wpa -addsearchdir "%USERPROFILE%\plugins"
110117
```
118+
119+
## How can I verify the WPA plugin is installed?
111120

112-
- `executablePath`: Path to the `wpa` executable
113-
- `commandLineArgs`: Absolute path to `bin/Debug/netstandard2.0`
121+
To verify the plugin is loaded, launch WPA and the plugin should appear under `Help > About Windows Performance Analyzer`
114122

123+
![WPA installation confirmation](/install-guides/_images/about-wpa.png)
115124

116-
> Make sure that no other version of the plugin is in the same directory as WPA.
125+
## How can I run the WPA plugin from the command line?
117126

127+
To open a json file directly from the command line, you can use the `-i` flag to specify the file path to open.
128+
129+
For example: to open `timeline_long.json` in your downloads directory, run the command:
130+
131+
```console
132+
wpa -i "%USERPROFILE%\\Downloads\\timeline_long.json"
133+
```
134+
## How do I uninstall the WPA plugin?
118135

119-
### Uninstalling the plugin
136+
To uninstall the plugin simply delete the `WPAPlugin.dll` file.
120137

121-
To uninstall the plugin simply delete the `.dll` file.

0 commit comments

Comments
 (0)