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.

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

• Note: Symbol decoding is performed on the Mac when the trace is captured, and cannot be done on Windows later

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.
• Download the Trace Export script to convert the captured trace into a compatible format for use with our plugin.
• Open a Terminal and go to your Download folder and run chmode +x trace-export.sh
• Run ./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-1.0.1.ptix"

• Copy captured and exported trace <tracefile.xml> from you Mac device to your Windows machine and open it with the WPA.

How to capture a Trace and Open in WPA:

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\instruments-trace.xml
    

  • 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 [email protected] 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.