Troubleshooting Performance Issues

This document provides instructions on how to capture performance analysis logs for the C++ extension so that we can help you troubleshoot your performance issues.

After following the instructions below for collecting logs, create a GitHub issue on the C++ extension GitHub repository and attach the generated files and screenshots.

The recommended profiling tool varies by platform. You'll find instructions below for installing and using the profiling tools for each platform.

Platform	Recommended profiling tool
Linux	Perf
macOS	Instruments
Windows	PerfView.exe and Visual Studio Performance Profiler

Linux

Install Perf profiling tool

First, verify if the perf tool is already installed by running "perf --version";. If it's not installed, install the following packages below.

1. Install linux-tools-common package.

   Example: $sudo apt-get install linux-tools-common

2. Install the package linux-tool-<kernelversion>. To get <kernelversion> of your Linux OS, run "uname -r".

   Example: $sudo apt-get install linux-tools-5.4.0-42-generic

3. Run "perf --version" to verify the tool is installed.

Prepare repro project and determine which extension process to profile

Ensure you can reproduce the issue and know which processes to profile.

1. Open the project and file which has the performance issue in Visual Studio Code.
2. Perform the steps that cause the issue.
3. Determine which extension process is using a lot of CPU cycles by running a system monitor process tool such as htop. The extension processes to look for are either cpptools or cpptools-srv. There will always be one cpptools process running per one instance of VS Code. There will be one cpptools-srv process running per source file that is active (or opened) in VS Code.
4. Get the PID of cpptools or cpptools-srv. To get the PID of cpptools, use htop. To get the PID of the cpptools-srv process for an active source file, run the " C/C++: Log Diagnostics" command in VS Code, then look for the PID ("Process ID") in the output log.

Profile the extension process while reproducing the issue

1. With the processes still running, go back to the terminal and start the perf tool by running the command "sudo perf record -a -g -d -p <PID>", where <PID> is the process ID of cpptools or cpptools-srv that will reproduce the issue.

   Example: $sudo perf record -a -g -d -p 8645

   Note: If you restarted Visual Studio Code after reproducing the issue, repeat the steps in the first section to get the PIDs of the new processes before starting the perf tool.

2. Go back to your VS Code repro project and perform the steps that cause the performance issue.

3. Let the process run for a few seconds and stop the perf tool by going back to the terminal and entering "Ctrl+c".

4. The perf tool will save the performance logs in a file called perf.data in the current working directory.

Viewing the performance report log and sending screenshot samples of the log

1. Open the perf.data file by running the command "sudo perf report -g graph"

   Example: $sudo perf report -g graph

2. The resulting logs should look like the one below:

   

3. Lines with "+" on the far left indicate that the item can be expanded. To expand an item, select it using the up or down arrow keys and press enter. Press enter again to toggle collapse and expand.

4. Take a screenshot of the samples that show highest percentage calls, or samples (see leftmost column in screenshot). Expand the items to show the call tree and attach the screenshots to a Github issue.

macOS

Install Xcode which includes the Instruments profiling tool

1. The Instruments profiling tool is included in the Xcode command-line tools. Verify if Xcode command-line tools is installed by opening a Terminal and running "xcode-select -p". If this does not print the current developer directory of Xcode, an error message will output.
2. Install Xcode command-line tools by running "xcode-select --install".

Prepare repro project and determine which extension process to profile

1. Open the project and file which has the performance issue in Visual Studio Code.

2. Perform the steps that cause the issue.

3. Determine which extension process is using a lot of CPU cycles by opening the Activity Monitor app and filtering out processes that has "cpptools" in the name. There will always be one cpptools process running per one instance of VS Code. There will be one cpptools-srv process running per source file that is active (or opened) in VS Code.

   

4. Get the PID of cpptools or cpptools-srv. To get the PID of cpptools, use the Activity Monitor app. To get the PID of a cpptools-srv process of an active source file, run the " C/C++: Log Diagnostics" command in VS Code, then look for the PID ("Process ID") in the output log.

Profile the extension process while reproducing the issue

1. Open a command line and run the following Instruments command to profile the cpptools or cpptools-srv process that has a high CPU usage: "instruments -l 30000 -t Time\ Profile -p <PID>", where PID is the process ID of the process you want to profile (see step #3 from previous section to get the PID of the process you want to profile). The value 30000 is the length of time to profile the process in ms, so 30000 translates to 30 seconds. Change this value if you want to profile the process for a longer length of time.

   Example: $instruments -l 30000 -t Time\ Profile -p 1699

2. After Instruments is finished profiling, it will save a *.trace file and print out its full file path.

3. Open the *.trace file

4. From the "Heaviest Stack Trace" view, select the last item to expand the symbol call tree

   

5. Take screenshots of the high CPU usage stack and attach the screenshots to a Github issue.

Windows

Install PerfView profiling tool and Visual Studio

1. Download the latest version of PerfView.exe from https://github.com/microsoft/perfview/blob/master/documentation/Downloading.md
2. Install Visual Studio by following instructions from https://docs.microsoft.com/en-us/visualstudio/install/install-visual-studio?view=vs-2019

Prepare repro project and determine which extension process to profile

1. Open the project and file which has the performance issue in Visual Studio Code.

2. Perform the steps that cause the issue.

3. Determine which extension process is using a lot of CPU cycles by opening Task Manager and going to the Details tab. From the details tab, find the cpptools.exe or cpptools-srv.exe process that is using a lot of CPU cycles. There will always be one cpptools.exe process running per one instance of VS Code. There will be one cpptools-srv.exe process running per source file that is active (or opened) in VS Code.

   

4. Get the PID of cpptools.exe or cpptools-srv.exe. To get the PID of cpptools.exe, use Task Manager. To get the PID of a cpptools-srv.exe process of an active source file, run the " C/C++: Log Diagnostics" command in VS Code, then look for the PID ("Process ID") in the output log.

Profile the extension process while reproducing the issue

1. Open Visual Studio without any projects.

2. Launch the Performance Profiler by entering Alt+F2 on Visual Studio

3. Select "Choose Target" and then "Running Process…".

   

4. Select the extension process to profile and check "CPU Usage" tool. Select "Start" to begin profiling. See step #3 from the previous section to get the PID of the process you want to profile.

5. Run "PerfView.exe collect -zip:true -nogui -threadtime:true -AcceptEULA" from an elevated command prompt. This will launch a window which will being tracing.

6. Exercise the extension for about 10 seconds.

7. Stop profiling the CPU Usage Tool on Visual Studio.

8. Press "S" on the PerfView collection window that launched previously from the command prompt. It will take a few seconds for it to generate and zip the files.

9. This will generate two files: PerfViewData.etl.zip and PerfViewData.log.txt. These files will be saved under same folder as PerfView.exe. Attach these files to a Github issue.

10. Save the diagsession from Visual Studio to view its details and take screenshots to add to the Github issue.

View details of diagsession and take screenshots of the data

1. Open the diagsession file that you saved from profiling.

2. Under the "Hot Path" section, select a hot function to view its call tree details

   

3. Example of a hot function's call tree:

   

4. Take a screenshot of the call tree of each top function listed in the "Hot Path" and attach the screenshots to a Github issue.