Running a performance diagnostic can help developers identify the causes of high CPU usage, slowdowns, or excessive memory consumption in Thunderbird. Before you begin, check whether the issue disappears when Thunderbird is started in Troubleshoot Mode. It may also be helpful to review the performance checklist.

Some types of diagnostics require using a development version of Thunderbird, available from the Thunderbird download page.

Performance diagnostics use a tool called the performance profiler. Thunderbird uses the Firefox profiler, so some dialog windows may refer to Firefox. The Firefox profiler documentation is excellent, but usually not required unless you encounter difficulties or need to perform special tasks such as startup profiling. In the documentation, every instance of the word “Firefox” should be understood as “Thunderbird”.

Preparing the Performance Profiler

The performance profiler is part of the Developer Tools.

Opening Developer Tools

In Thunderbird’s main window, open the developer tools:

1. Use the keyboard shortcut Ctrl + Shift + Icommand + option + I, or click the menu button in Thunderbird and choose Tools.
2. From the menu, select Developer Tools. An incoming connection prompt will appear.
   
   

   Important! To allow the developer tools to connect to Thunderbird, you must approve the connection in the prompt.
   The prompt window may be hidden behind other Thunderbird windows.

3. Click OK. The Developer Tools window will open. In current versions of Thunderbird, the Performance tab is visible, and clicking it shows the Start Recording button.
   If the tab is not visible:

   • Press F1 or click the button in the upper-right corner of the window and choose Settings. The developer tools settings window will open.
   • Make sure the Default Developer Tools section has the [✓] Performance option enabled. If it is not enabled:

   • enable it, then click the Performance tab that appears at the top of the developer tools window.

Configuring profiler settings

To configure the profiler settings:

1. At the bottom of the Performance tab, click Edit Settings…. A Thunderbird window will open with the profiler settings tab active.
2. In the Profiler Settings section, enable the Thunderbird radio button (in nightly/trunk versions, the Daily button). After changing other options, this button will automatically deactivate and the Custom button will become active.
3. In the Features section, enable the All File IO checkbox.
4. To protect privacy or reduce memory usage, scroll down and disable the Screenshots checkbox.
5. Adjust other settings if needed. For example:
   • Change the Native Allocations option available in Thunderbird Daily if you are diagnosing high memory usage.
   • Increase the buffer size from 1 GB to 2 GB and extend the sampling interval beyond the default 1 ms if reproducing the issue requires more than one minute of recording or if additional data collections are enabled.
6. Close the profiler settings window using the window controls – there is no OK or Save button.

Recording a performance diagnostic

When the profiler and test scenario are ready, you can begin recording and saving the performance diagnostic.

1. In the Performance tab of the developer tools window, click Start Recording button.

   Note. A warning icon may appear on the toolbar. Clicking it opens a console at the bottom of the window with the message “Failed to get the active browserId while starting the profiler” – this can be ignored.

2. After recording starts, quickly return to Thunderbird’s main window and perform the actions from your test scenario.
3. When finished, immediately return to the developer tools window and click Capture recording to stop data collection. A brief Capturing profile message will appear, followed by the Firefox profiler window displaying the recorded data.

Saving and sharing performance diagnostic results

To save and share the performance diagnostic results:

1. Click the Upload Local Profile button in the upper-right corner of the profiler window.

   

2. In the “Share Performance Profile” panel, select the checkboxes for any private information you want to include. By default, no private information is included in the performance profile.

   

3. Click the button to save a JSON file locally. You can then email it or attach it to a bug report.
4. Click the button to upload the profile to the Firefox profiler repository and generate a direct link (permalink). The link becomes available after clicking the Permalink button in the profiler window. You can copy and share it with developers or others who can help diagnose the issue, or attach it to a new or existing bug report in Bugzilla (BMO).

   

5. Close the performance profiler window.
6. Close the developer tools window.

Diagnosing Thunderbird startup and shutdown

Startup or shutdown diagnostics require following special but very simple instructions. As before, every instance of the word “Firefox” should be understood as “Thunderbird”.