swift-mirror/docs/WindowsProfilingCompiler.md

Profiling the Swift Compiler on Windows

This document describes Windows profiling tools from the angle of profiling the Swift compiler itself. The information is mostly general purpose, but specifics relevant to other applications aren't considered.

The recommended approach when you need detailed function and I/O operation-level profiling of the Swift compiler on Windows is to use Event Tracing for Windows (ETW). This includes using Windows Performance Recorder (WPR) to collect profiling data in ETL format and then Windows Performance Analyzer (WPA) to analyze it. For specific analyses not available in WPA, you will also be able to use xperf.exe to convert a binary ETL file to a text format for analysis by another program. We also discuss a couple of alternatives which may in certain cases be easier to use or provide specific data of interest: Visual Studio (the full IDE, not VS Code) and Intel VTune.

The document is organized as follows:

1. Recommended: Using Event Tracing for Windows (ETW) to profile Swift compiler runs
2. Alternative: Using Visual Studio to profile Swift compiler runs
3. Alternative: Using VTune to profile Swift compiler runs
4. Reference: Survey of Windows profiling tools
5. Reference: Building the Swift toolchain for Windows with debugging symbols

Recommended: Using Event Tracing for Windows (ETW) to profile Swift compiler runs

1. Make sure you have a build of the Swift toolchain with PDB format debug symbols. One approach is to follow Building the Swift toolchain for Windows with debugging symbols.
2. Use wpr (Windows Performance Recorder) or a wrapper script like utils/windows-profiling-tools/RunProfiler.ps1 to collect a .etl file (event trace log).
   1. If you are using a custom-built Swift toolchain, set environment variables as instructed in WindowsQuickStart.md.
   2. Example usage of RunProfiler.ps1: ...\RunProfiler.ps1 -TracePath C:\Temp\program.etl -Target swiftc program.swift. Here program.swift just serves as a workload for running the compiler. Different parts of the compiler will naturally be exercised more or less depending on the program.
   3. Instead of running swiftc directly, you can instead call a build system like swift build or cmake to build a larger program. Longer compilations will result in larger .etl files. Try a small program first, to see what the .etl file collection and analysis process is like (including the size of .etl files).
3. Run wpa.exe <path\to\trace.etl> to load the .etl file into WPA and analyze it.
   1. On the left, double click on the view you're interested in. Some useful ones include "Computation > CPU Usage (Sampled)," "System Activity > Processes," and "Storage > File I/O > Activity by Process, Thead, Type."
   2. Sort by Process name and select other related processes you may be interested in like swift.exe. Then right click on the selected processes and choose "Filter To Selection" to hide all other processes. Alternatively, right click on the table header, select "Edit Filters," and enter "Process Name" constraints.
   3. Go to Trace > Configure Symbol Paths. It will open a Configure Symbols dialog. Add S:\Program Files\Swift\Runtimes\0.0.0\usr\bin and S:\Program Files\Swift\Toolchains\0.0.0+Asserts\usr\bin the list in the Paths tab. This enables WPA to find PDB files for our EXEs and DLLs. You shouldn't have to reconfigure this every time you run WPA.
   4. Make sure Trace > Load Symbols is selected. If it's unselected, it will likely take some time to load symbols once you select it.
   5. The Stack column of the process list should now show function symbols as you drill down into execution times for various parts of the call stack. If you're in a view that doesn't include Stack or another column you want, right click on the table header and select "More Columns..." > the column view you want or right click the table header and select "Open View Editor..." for more detailed configuration.

Alternative: Using Visual Studio to profile Swift compiler runs

Visual Studio (the full IDE, not VS Code) has a built-in profiler that can profile arbitrary executables without requiring a Visual Studio solution or project. This includes the Swift compiler, provided it is built with PDB format debug symbols. By default, Visual Studio's profiler only records profiling data for the directly invoked process, not child processes. This makes it a less than ideal choice for top level Swift builds that invoke many child processes, but can still be useful if you have a specific swift-frontend.exe command you would like to profile.

Assuming you want to profile swiftc.exe's call to swift-frontend.exe run on an input source file S:\Temp\hello.swift:

1. On the command line, run swiftc.exe -v hello.swift (for example). This will give you a swift-frontend.exe command that swiftc.exe calls.
2. Open Visual Studio without any files/project.
3. Debug > Performance Profiler...
4. Change Target > Executable
   1. Path to executable: S:\Program Files\Swift\Toolchains\0.0.0+Asserts\usr\bin\swift-frontend.exe
   2. Command line options: (as output in step (1) above).
   3. Working directory: S:\Temp
   4. Environment Variables: see "Using the Toolchain" in WindowsQuickStart.md.
5. Click Ok, select "CPU Usage," click Start.
6. When the run is done, Visual Studio will present you with a GUI with lists of the functions that take the most time as well as hot traces, which you can explore further.

Alternative: Using VTune to profile Swift compiler runs

Intel VTune supports profiling using Intel processors' Performance Monitoring Unit (PMU), which provides hardware-level performance counters. It's available as an integrated GUI application as well as a standalone command line executable (vtune.exe) that can collect performance logs to be analyzed in the GUI. We'll discuss the GUI workflow here.

1. Download VTune for Windows from Intel and install it on a Windows computer with an Intel processor. The first time you launch VTune, a helpful walkthrough tutorial is available. After that:
2. On the Welcome tab, click "Configure Analysis..." and configure it as follows:

   1. Where: Local Host (default)

   2. What: Launch Application (default)

   3. Application: for example, S:\Program Files\Swift\Toolchains\0.0.0+Asserts\usr\bin\swiftc.exe

   4. Application parameters: for example, hello.swift

   5. Uncheck "Use application directory as working directory"

   6. Working directory: for example, S:\Temp

   7. Advanced >

      1. User-defined environment variables: see "Using the Toolchain" in WindowsQuickStart.md.
      2. Make sure "Analyze child processes" is checked (it is by default)
      3. Duration time estimate: Under 1 minute
      4. Store result in (and create link file to) another directory: C:\Users\%USER%\Documents\VTune\Projects\swift_hello (note: manually fill in your %USER%)

   8. How: Select what you would like to profile. Hotspots will tell you where most of the time is spent in the code.

   9. Click the "Search Sources/Binaries" button (folder with a magnifying glass) and add the following search directories:

      • S:\Program Files\Swift\Runtimes\0.0.0\usr\bin
      • S:\Program Files\Swift\Toolchains\0.0.0+Asserts\usr\bin

   10. Click the "Start" button ("play" button style triangle above). If you would prefer to run vtune.exe from the command line, click the ">_" button seen above to get the command to run.

3. After profiling swiftc.exe hello.swift exits, you will be taken to an analysis tab to view the results, which include hot traces and time consuming functions.

Reference: Survey of Windows profiling tools

This section describes Windows profiling tools that can be used with the Swift compiler and the relationships between them.

• WPT = Windows Performance Toolkit is a collection of tools & infrastructure for profiling from Microsoft. Includes the WP* and XPerf* tools below.
• ETW = Event Tracing for Windows is the OS-level feature for collecting application and kernel performance event traces. Microsoft/Windows Profiler tools drive ETW to collect events.
• Performance event recorders:
  • WPR = Windows Performance Recorder lets you start and stop an ETW session by running wpr.exe. Collects profiling data for all running processes and saves it to a .etl file. See utils/windows-profiling-tools/RunProfiler.ps1 for a PowerShell script that runs WPR for the duration of a specified command invocation.
  • XPerf is an older, lower level equivalent of WPR. It supports a few obscure ETW settings not exposed by WPR, but WPR is recommended if meets your needs.
  • Visual Studio also supports profiling .exes that don’t have to be part of a Visual Studio solution/project, starting by opening VS without any files/project, then going to Debug > Performance Profiler... By default, it only profiles the initial process launched from the .exe, not child processes.
  • Intel VTune supports profiling using Intel processors’ Performance Monitoring Unit (PMU) rather than ETW. It’s available as an integrated GUI application as well as a standalone command line executable that can collect performance logs to be analyzed in the GUI.
• File formats:
  • .etl is the output binary event log file format produced by tools like WPR and XPerf. There are also a command line tools including xperf.exe and tracerpt.exe that can be used to convert an ETL file into multiple text-based formats.
  • .wprp is an XML configuration file format used to configure WPR’s operation. For example, utils/windows-profiling-tools/CpuAndWaitsWithLargeBuffers.wprp increases the in-memory buffer size that WPR configures ETW to use so as not to drop events during recording.
• Analysis GUIs:
  • WPA = Windows Performance Analyzer is a GUI that lets you analyze various aspects of the performance trace data found in .etl files. It can be invoked on the command line by running wpa.exe with the .etl file as an argument. See Using Event Tracing for Windows (ETW) to profile Swift compiler runs for how to view program profiles with symbols.
  • XPerfView is an older GUI for analyzing .etl files that has been replaced by WPA.
  • Visual Studio directly displays profile results after recording a profile data from a run of a program. By default, it only shows profiles for the directly invoked program, not for subprocesses.
  • Intel VTune can either directly display profile results after recording them or display profile results from a command line run of vtune.exe (possibly run on a different host).
• Analysis CLIs:
  • wpaexport.exe takes a profile built in the WPA GUI and exports data from a .etl file according to that profile. Note that profiles that include hierarchical lists in the GUI may only export the top levels of the hierarchy. In this case, you can reconfigure the WPA GUI view to make the list flat and then export a new profile.
  • xperf.exe can be used to operate on .etl files recorded with either wpr.exe or xperf.exe itself. Examples:
    • Dump all events from a .etl file in text format: xperf -i <INPUT>.etl -o <OUTPUT>.txt -symbols -target machine -a dumper -stacktimeshifting where <INPUT> and <OUTPUT> are files of your choice with _NT_SYMBOL_PATH set in the environment to point to directories containing PDB files, e.g. in PowerShell:
      • $env:_NT_SYMBOL_PATH="S:\b\5\bin\bin" (list all directories containing relevant PDB files, separated by semicolons)
    • List execution times per function from a .etl file, not including the time taken by calls to other functions: xperf -i <INPUT>.etl -o <OUTPUT>.txt -symbols -a profile -detail

Building the Swift toolchain for Windows with debugging symbols

To build the Swift compiler with PDB format debug symbols that are used by profile analysis tools like WPA or Visual Studio, follow the https://github.com/compnerd/swift-build/blob/main/docs/WindowsQuickStart.md instructions, using the following build.cmd command line (or a variant on it based on your exact needs):

S:\SourceCache\swift\utils\build.cmd -Windows -DebugInfo -SkipPackaging -WindowsSDKArchitectures x64 -CDebugFormat codeview -SwiftDebugFormat codeview

If you need to build a package that you can install on a separate Windows host, either remove -SkipPackaging in the above command, or if you've already run the above build, substitute -SkipBuild in place of -SkipPackaging.