Microsoft Performance Tools Apple

This repo contains Apple Analysis tools built with the Microsoft Performance Toolkit SDK.

Tools are built with open source .NET Core and can be run on the cmd-line or in the WPA GUI. All the logs that are supported are open source.

New in 1.4.0: WPA can now open Instruments .trace files natively. You no longer need to export the trace to XML with xctrace / trace-export.sh before opening it — just copy the .trace from your Mac to Windows and open it in WPA. See Opening a trace in WPA.

Tracing supported:

There are two options for capturing a trace on MacOS. The first is a UI-based trace viewer and capture tool called Instruments, while the second is a command-line tool called xctrace.

Instruments (formerly Xray)

Instruments is a standalone application that comes with Xcode, and can be used independently or in conjunction with Xcode. Instruments shows a time line displaying any event occurring in the application, such as CPU activity variation, memory allocation, and network and file activity, together with graphs and statistics.

Install Instruments:

• Install Xcode on your Mac device
• Open the Instruments application from the menu bar at Xcode -> Open Developer Tool -> Instruments

Capture a Trace with Instruments:

• To start capturing a trace: Open Instruments -> File -> New
• Choose your profile and the select Choose.

Configure Symbol Path in Instruments:

If it is necessary to load additional symbols, please refer to this section.

• To enable symbols from 3rd party applications, Open Instruments -> Settings...
• Choose Symbols and add the relevant paths to your local symbol files

• Instruments can save symbol information with the trace. The direct .trace loader resolves bundled symbols on Windows and demangles C++ linkage names when no display name is stored. Missing names can be supplied through matching external symbols.

Direct Trace Symbol Resolution

The loader uses the trace's recorded image mappings and bundled symbol archives. Matching external dSYMs, Mach-O files, and symbol stores can be supplied through INSTRUMENTS_SYMBOL_PATH (semicolon-separated) or the SymbolStore directory next to the plugin.

To diagnose symbol resolution:

dotnet run --project DiagTrace/DiagTrace.csproj -c Release -- <trace-path> [symbol-path]

xctrace

xctrace is used to record, import, export, and symbolicate Instruments' .trace files via the command line.

To use xctrace open a Terminal Window: 'xctrace help [command]'

To capture a trace with a Time Profile template:

xctrace record --all-processes --template 'Time Profiler' --time-limit 5s

For more info about xctrace please visit: xctrace documentation

Capture Trace on MacOs:

• Use Instruments or xctrace to capture the trace. Note that we support some of tables as shown above.
• Copy the .trace to Windows and open it directly in WPA (see Opening a trace in WPA). Starting with 1.4.0, no XML export step is required.

Opening a trace in WPA:

Starting with version 1.4.0, the plugin reads Instruments .trace files natively. Any of the following work:

• Zipped .trace file – a ZIP archive of the trace bundle whose file name ends in .trace. Open it from WPA's File -> Open dialog, or with wpa.exe -i C:\PATH\TO\MyTrace.trace.
• .trace folder – on Windows an unzipped .trace bundle appears as a folder. In WPA's File -> Open dialog, navigate into the .trace folder and select open.creq.
• .trace folder from the command line – wpa.exe -i C:\PATH\TO\MyTrace.trace, where the path is the .trace folder.

Legacy XML export (optional)

Exporting the trace to XML is no longer required, but XML import is still supported (and is the only option for plugin versions earlier than 1.4.0). To export, run the Trace Export script on your Mac:

./trace-export.sh --input <tracefile.trace>

Install Microsoft Performance Toolkit Apple:

• Download the latest WPA UI. You can download it from Windows Performance Analyzer (Preview).

• Download the latest Microsoft Performance Toolkit Apple Releases

• Extract the Microsoft-Performance-Tools-Apple.zip

• Open WPA UI and click Install Plugin

• Browse to "%ExtractedFolder\Microsoft-Performance-Tools-Apple\Microsoft-Performance-Tools-Apple\MicrosoftPerfToolkitAddins\PTIX\Microsoft.Performance.Toolkit.Plugins.InstrumentsProcessor-<version>.ptix"

• Copy the captured .trace from your Mac to Windows and open it with WPA — no XML export needed (see Opening a trace in WPA).

How to capture a Trace and Open in WPA:

Examples:

Capture a trace with 1 million instruction samples and attach Cycle Delta to that event. Also, add Time Profile to sample the running thread on the CPU every 1 ms. This profile can be used to calculate frequency, as well as instruction and cycle-level analysis.

First, open Instruments and create a new session, then choose Blank.

From the open window, select +Instruments (see step 2) and find CPU Counters and Time Profile from the opened menu (see step 3).

For CPU Counters, use Event-Based Sampling to collect a sample every 1 million instructions (see step 2) and attach Cycle (see step 3) to that. Then, in Record Settings, choose Deferred (see step 4).

Capture the trace and save it. Then copy the .trace to Windows and open it directly in WPA (see Opening a trace in WPA).

You can find the template here: TraceTemplate\CPUCounterWithTimeProfile.tracetemplate

Developer Prerequisites

Runtime prereqs

• .NET Core Runtime 3.1.x

Dev prereqs

• .NET Core SDK 3.1.x
• Visual Studio, VSCode, or your favorite editor!

Download

• For plugins Download see Releases

• NuGet Pkgs see PerformanceToolkitPlugins

• (Windows Only GUI - Install) Using the WPA GUI to load these tools as plugins

  • Download the latest Store Windows Performance Analyzer (Preview)

How to run the tools

The tools can be run in several modes:

• Cross-platform with .NET Core (Any OS that .NET Core supports)
  • Used as a library to process traces / logs programatically in a .NET Core language like C#
• (Windows Only - Run) Using the WPA GUI to load these tools as plugins
  • WPA needs to be told where to find these additional plugins.
  • In Command Prompt with -addsearchdir and -i trace file:

      wpa.exe -addsearchdir %USERPROFILE%\Downloads\Microsoft-Performance-Tools-Apple\Microsoft-Performance-Tools-Apple\MicrosoftPerfToolkitAddins\ -i c:\PATH\TO\MyTrace.trace
    

  • OR with Env Variable to pick file from UI

     SET WPA_ADDITIONAL_SEARCH_DIRECTORIES=%USERPROFILE%\Downloads\Microsoft-Performance-Tools-Apple\Microsoft-Performance-Tools-Apple\MicrosoftPerfToolkitAddins\
     wpa.exe
    

  • Optional Troubleshooting - Verify that this WPA version supports plugins
    • In Command Prompt - Example:

      wpa.exe /?
      "C:\Program Files\WindowsApps\Microsoft.WindowsPerformanceAnalyzerPreview_10.0.22504.0_x64__8wekyb3d8bbwe\10\Windows Performance Toolkit\wpa.exe" /?
      

    • Verify that these 2 command line WPA options are supported:
      • OPTIONS: -addsearchdir PATH. Adds a directory path to the plugin search path. ....
      • ENVIRONMENT VARIABLES: WPA_ADDITIONAL_SEARCH_DIRECTORIES - A semicolon (;) delimited list of additional directories to search for plugins. Equivalent to the -addsearchdir option.
• (Windows) Command-line dumping to a text format based on the WPA UI (say CSV) (wpaexporter.exe)

  "C:\Program Files\WindowsApps\Microsoft.WindowsPerformanceAnalyzerPreview_10.0.22504.0_x64__8wekyb3d8bbwe\10\Windows Performance Toolkit\wpaexporter.exe" -addsearchdir PLUGIN_FOLDER -i traceFile
  

How do I use WPA in general?

If you want to learn how to use the GUI UI in general see WPA MSDN Docs

Contributing

This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.opensource.microsoft.com.

When you submit a pull request, a CLA bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.

Trademarks

This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft trademarks or logos is subject to and must follow Microsoft's Trademark & Brand Guidelines. Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship. Any use of third-party trademarks or logos are subject to those third-party's policies.