On this page you will also find

Introduction

This document describes changes required to extend WindowsPerf in order to add graphical user interface (GUI). WindowsPerf is a Windows On Arm (ARM64) command line application with similar text interface to Linux perf. Extending WindowsPerf design with aligned GUI will enable wider audience of users.

WindowsPerf users may vary from WOA application developers to WOA clusters' administrators.

Overview

WindowsPerf currently is composed with two components:

• Kernel-Mode Driver Framework (KMDF) driver – wperf-driver.

• Command line application – wperf.

WindowsPerf aims to support:

• Counting model, for obtaining aggregate counts of occurrences of special events, and

• Sampling model, for determining the frequencies of event occurrences produced by program locations at the function, basic block, and/or instruction levels. [Currently under development].

Current WindowsPerf Limitations [Feb 2023]

• WindowsPerf works on ARM64 WOA (Windows On Arm) host computers.

• wperf command line interface can interact with WOA OS hardware resources via wperf-driver custom driver. This requires driver deployment to each monitored host computer.

  • Additional steps are needed to install wperf-driver.

• No remote connection between wperf application and monitored host is possible

  • wperf application only communicated with host it runs on.

• One instance of wperf can interact with host machine via wperf-driver.

  • Currently there’s no failsafe to guard this limitation.

• No data visualisation is available.

Current architecture

• OS - Windows 10/11 ARM64.

Proposed architecture which would include GUI

Notes:

• Components marked with orange colour are new components. Blue component are existing components.

• Tag [FutureDev] is used for requirements, use cases or user stories that will be implemented in the future but may already have impact on the design. So they should be taken under consideration when designing planned features.

• Tag [Nice-to-have] is used for requirements, use cases and user stories that would ideally be included. But may be moved for later stages without big impact on the outcome.

High-level requirements

• GUI must work in native ARM64 environment and in x64 environment.

• GUI must work on native WOA OS browser Microsoft Edge.

  • If GUI is implemented as Web Script.

• [FutureDev] GUI must work in environment without access to the Internet.

  • GUI users may be working inside private, closed test / lab networks and may not have access to the Internet.

  • This implied no external import / loads of external source scripts or libraries.

• [FutureDev] GUI must be able to connect and interact with multiple wperf-relay instances to query, fetch, group and present counting and sampling data.

• [FutureDev] GUI users may want to write “plugins” to add e.g. new graphs or other visualisations.

• [FutureDev] GUI displays Flame Chart for profiled code.

• [FutureDev] GUI displays Timeline for counting model.

Components high-level overview

1. Additional wperf-relay component is introduced. Its sole responsibility is to hide wperf interface and abstract WindowsPerf service as a REST API. This component will be also responsible for invoking, error handling and controlling counting, sampling and metrics procedures.

2. New wperf-gui GUI interface is introduced. It’s data-driven interface which will contain small amount of business code and focus on correct triggering and visualizing features available with WindowsPerf.

3. wperf already support JSON output format which will be used be forwarded by the wperf-relay to REST API client(s). For example wperf-gui.

   1. wperf-relay will provide additional thin layer which will wrap e.g. error responses from wperf.

4. wperf-gui should be able to connect to wperf-relay from the same host as it should be able to connect from remote hosts.

   1. This remark discards issues such as firewall configuration of the host and focuses on making sure wperf-gui can operate from different environments. Both OS and host architecture.

5. New interfaces:

   1. New Relay REST API interface between wperf-relay and clients. This interface will transport wperf’s JSON responses.

Example GUI-WindowsPerf interaction diagram

This interaction showcase how user can trigger interaction between GUI and WindowsPerf. It demonstrates successful order of operations between both parties. Please note that user may interact with GUI in a way no WindowsPerf communication is needed.

Interaction steps:

1. User initiates feature with GUI widget.

2. wperf-gui with authenticated way connects and passes REST API query to wperf-relay.

   1. This abstracted query contains all information needed to drive wperf by wperf-relay.

   2. Please note wperf-gui will NOT send explicit command line options to wperf in this query via relay.

3. wperf-relay decodes Relay REST API query and translates it to wperf command line interface string.

   1. Additional -json command line option is added to force JSON output from wperf.

4. wperf-relay creates new subprocess of wperf and captures return code (%errorlevel%), STDOUT and STDERR content.

5. wperf instruments wperf-driver in order to e.g. count events.

6. wperf process end and return exit code and JSON response.

   1. In case of error, wperf-relay wraps error in REST API response and forwards it to wperf-gui client.

7. wperf-gui receives REST API response. Response bundle contains payload with raw wperf JSON output and additional query metadata.

8. wperf-gui process data for user.

Note: above diagram do not include User-GUI authentication for simplicity of the example.

Multi-host architecture proposal

[FutureDev] One wperf-gui instance should be able to connect to multiple wperf-relay instances. This architectural extension may be required in “clusters” of ARM64 systems, WOA testbeds / test labs. Users may want to gather “simultaneously” timeline, counding, sampling, metrics, analysis data from many (>1) WOA hosts. There’s a benefit to performance analysis on multiple systems at once. And we recognise this requirements.

Components

User stories

wperf

wperf-gui

wperf-relay