docs/performance/reporting_a_performance_problem.md

   1 # Reporting a Performance Problem
   2
   3 This article will guide you in reporting a performance problem using the
   4 built-in Gecko Profiler tool.
   5
   6 ## Enabling the Profiler toolbar button
   7
   8 These steps only work in Firefox 75+.
   9
  10 1.  Visit [https://profiler.firefox.com/](https://profiler.firefox.com/)
  11 2.  Click on *Enable Profiler Menu Button*
  12 3.  The profiler toolbar button will show up in the top right of the URL
  13     bar as a small stopwatch icon.
  14
  15 ![image1](img/reportingperf1.png)
  16
  17 4.  You can right-click on the button and remove it from the toolbar
  18     when you're done with it.
  19
  20 ## Using the Profiler
  21
  22 When enabled, the profiler toolbar button is not recording by default.
  23 Recording can be done by clicking on the toolbar icon to open its panel.
  24 Make sure to choose an appropriate setting for the recording (if you're
  25 not sure, choose Firefox Platform), and then choosing **Start
  26 Recording**. The toolbar icon turns blue when it is recording.
  27
  28 The profiler uses a fixed size buffer to store sample data. When it runs
  29 out of space in its buffer, it discards old entries so you may want to
  30 increase the buffer size if you find you are unable to capture the
  31 profile quickly enough after you notice a performance problem. If you
  32 choose Custom Settings (and then clicking Edit Settings) for the
  33 profiler, you can adjust the size of the buffer (presently defaults to
  34 90 MB) and the time interval between data collection (presently defaults
  35 to 1 ms). Note that increasing the buffer size uses more memory and can
  36 make capturing a profile take longer.
  37
  38 ![image2](img/reportingperf2.png)
  39
  40 Using the keyboard shortcuts is often more convenient than using the
  41 mouse to interact with the UI:
  42
  43 * Ctrl+Shift+1 - Start/Stop the profiler
  44 * Ctrl+Shift+2 - Take a profile and launch the viewer to view it
  45
  46 ## Capturing and sharing a profile
  47
  48 1.  While the profiler is recording, reproduce the performance problem.
  49     If possible let the problem manifest itself for 5-10 seconds.
  50 2.  Press **Ctrl+Shift+2** or click on the profiler toolbar icon in the
  51     top right and select **Capture**. Try to do this within a few
  52     seconds from reproducing the performance problem as only the last
  53     few seconds are recorded. If the timeline has a large red block
  54     it's a good sign. ![Jank markers appearing in the Perf.html profile analysis tool.](img/PerfDotHTMLRedLines.png)
  55 3.  The data will open in a new tab. Wait until the \"Symbolicating call
  56     stacks\" notification disappears before sharing the profile.
  57 4.  There will be a button in the top right labeled **Upload Local Profile** which
  58     will allow you to upload this profile and once completed will write
  59     out a link. Before uploading, the Upload button asks you what data
  60     you'd like to publish to our servers.
  61 5.  Note that while it's possible to strip profiles of potentially
  62     privacy sensitive information, the less information a profile
  63     contains, *the harder it is to analyze and turn into actionable
  64     data.*
  65 6.  Once uploaded, copy permalink URL to your clipboard by right
  66     clicking and [add the profile URL to a bug](https://bugzilla.mozilla.org/enter_bug.cgi?product=Core&component=Performance)
  67     for your performance problem and/or send it to the appropriate
  68     person. Try to give some context about what you were doing when the
  69     performance problem arose such as the URL you were viewing and what
  70     actions were you doing (ex. scrolling on gmail.com).
  71
  72 ![image3](img/reportingperf3.png)
  73
  74 ## Viewing addon performance in GeckoView
  75
  76 Sometimes an addon or more are slowing down Firefox. These addons might
  77 be using the extension API in ways that were not meant to. You can see
  78 which of these addons are causing problems by adding the
  79 **moz-extension** filter.
  80
  81 ![moz-extension filter print screen](img/EJCrt4N.png)
  82
  83 Make sure you are selecting the process that is using up the CPU since
  84 all of the processes are shown. You might have a content process using
  85 up the CPU and not the main one.
  86
  87 Make sure you are doing whatever it is that slows down Firefox while
  88 recording the profile. For example you might have one addon that slows down page load
  89 and another one that slows down tab switch.
  90
  91 Your first reflex once you find what addon is slowing down the profile
  92 might be to disable it and search for alternatives. Before you do this,
  93 please share the performance profile with the addon authors through a
  94 bug report. Gecko profiler allows you to share a link with the profile.