Tools for Debugging Gecko Core

The first steps to understanding a performance problem is finding the area responsible and collecting information. If you haven't yet filed a bug at this point you should do so now. At this point you may not know the component responsible for the performance problem so take your best guess and update it as your investigation progresses.

Try testing against older releases of Firefox and against an up to date Nightly build.

This article will outline the tools and techniques you can use for debugging performance. Some section headers indicates who you might contact if you have questions about a given tool. You can also try asking in the IRC channels #perf, #gfx, #flow or #developers.

The Gecko Profiler (mstange)

General purpose profiler and a good tool to start your investigation with. Useful if you experience: Periodic hangs, slow JS scripts, want to know where the CPU time is being spent, what events are blocking the main thread, target profiling of certain areas. See the Profiling with the Gecko Profiler document for more information.

System Profilers

Prefer a system specific profiler if you're interested in C++ and cache behavior. Particularly VTune (Windows, license required), Instrument (XCode, free), perf (Linux). See:

API Trace (gw280)

A shim OpenGL library that interposes OpenGL calls in order to record the calls to a file before sending them to the OpenGL driver. Recordings on a phone can be pulled from the phone and replayed on your desktop machine. This tool will let you replay the trace to view/analyze the rendering and OpenGL frame at a given point in time. This tool is very useful at finding OpenGL state bugs.

Paint Flashing

Paint flashing will show which areas of the screen are being redrawn. For example when scrolling you expect to only see the side of the page being brought into view being repainted (note on mobile we use a displayport that is larger than the screen to predraw outside the screen, so paint flashing behavior is quite different there). In general, parts of a page that are not changing should not be redrawn, but there are tons of exceptions. Execessive paint flashing can be caused by overpainting, which indicates a layout bug, particularly if every scroll or update causes the entire screen to flash, or if css transformed elements are being repainted as the transform is animated.

On desktop paint flashing can be turned on by opening the devtools windows and clicking on the paint brush icon in the bottom left. On mobile, manually flip the preference 'nglayout.debug.paint_flashing' to true.

Also see 'layers.force-active'.


If paint flashing shows that the page performance is suffering from execussive flashing perhaps it's because the layer tree is poorly choosen. If that's the case then you can test this by forcing all the elements on the page to become an active layer. Flip the preference 'layers.force-active'. This will use additional main and video memory but will improve the performance if the excessive painting is caused by poor layers building heuristics.

LayerScope (Vlad)

This tool can dump the layer tree and the corrsponding layer information (e.g. layer size, layer image) on the browser, so you can debug by the layer information.

For more information see

Layer Borders (Nical)

Player2D (Bas)

Allows to capture the drawing commands issues from layout either during a browsing session or to load a single page. Once capture the recording file can be used with player2d to replay and analyze the command stream. This is useful if there's a performance problem in moz2d, to debug rendering glitches caused by a bad commands stream or moz2d backend implement.


MOZ_GL_DEBUG (bjacob)

Useful if: You have some rendering glitches when using OpenGL.

Use this tool to:

  • Find if the code uses an OpenGL context which isn't current.
  • Have syncronization problems
  • Want to find the exact call
  • Want to dump a log of the OpenGL functions called.

Layout Debugging

Dump the Display List

Perference 'layout.display-list.dump' (dumps display lists for all paints in all processes) and 'layout.display-list.dump-content' (dumps display lists for all paints in content processes only).

Dump the Frame Tree via GDB

  • Define DEBUG_FRAME_DUMP in layout/generic/nsFrameList.h
  • Use GDB to break at nsLayoutUtils::PaintFrame
  • (gdb) p aFrame->DumpFrameTree()
  • Find frame tree in logcat

Build tricks

Rebuilding subdirectory with debugging (bjacob)

Disable code folding (bjacob)


Set commands breakpoint when debugging (bjacob)


Set MOZ_DEBUG_APP_PROCESS to a process name to get process(es) with that name to sleep for 30 seconds just after they start to give you time to attach gdb (on Windows the debugger will be invoked and attached automatically).

GDB Debugging with Mochitest on Fennec Build(VincentLiu)

First of all, following the setup steps to make sure you have Fennec build environment.
  • Open one console and run your mochitest by mach command
    • $./mach mochitest <path>/<to>/<mochitest>/*.html
  • When mochitest start running, open another Console and run gdb to attach.
    • $/Users/mozilla/.mozbuild/android-device/jimdb-arm/bin/gdb
    • Once run gdb, note that you should choose "1. Debug Fennec (default)" in Fennec GDB utilities
  • Some issues you might encounter after gdb start running.
    • If you encounter SIGILL and stop by ElfLoader::DebuggerHelper, try to delete the following folder as work around.
      • rm -r /Users/mozilla/.mozbuild/android-device/jimdb-arm/lib/emulator-*
    • If you encounter SIGABRT but not about to your issue in debug build, try to remove --enable-debug in your .mozconfig.