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, (1) file 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.

Before proceding try testing in against older releases of Firefox and against the up to date Nightly build.

This article will outline the tools and techniques you can use for debugging and performance. Each article is listed with a contact you can ask questions about this tool.

Built-in Profiler (BenWa)

General purpose profiler. 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.

For more information see:

System Profiler (BenWa)

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 the OpenGL call that records them before sending them to the OpenGL driver. We can use this to trace the opengl calls to trace file that we can later pull from the device and replay it in the computer. This tool will let you replay the trace, looking at each frame and analyze the current rendering and analyzing the OpenGL frame. This tool is very useful at finding OpenGL state bugs.

Paint Flashing (BenWa)

Paint flashing will show which area of the screen are being drawn. In general, but subject to a ton of exception, if something isn't changing we shouldn't be redrawing them. Use paint flashing to see which area of the screen are being redrawn internaly. On desktop open the devtools windows and click on the paint brush icon in the bottom left. On mobile flip the preference 'nglayout.debug.paint_flashing'. 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 to predraw outside the screen so paint flashing behavior is quite different there.

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. See layers.force-active as well


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, please 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.

Dump GL cmds on B2G

Quick way to check which GL cmds are called, but it is possible that some GL cmds are lost or disorder in logcat.

You can compare the output with MOZ_GL_DEBUG.

$ adb shell setprop debug.egl.trace 1

Layout Debugging

Dump Painting

Dump Render Frame

Dump Frame 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

Dump DisplayList on B2G

  • Add 'export B2G_DUMP_PAINTING=1' in .userconfig under B2G folder
  • Turn on the perference layout.display-list.dump

Build tricks

Rebuilding subdirectory with debugging (bjacob)

Disable code folding (bjacob)


Set commands breakpoint when debugging (bjacob)


Apps on B2G run in separated processes. To debug a particular app, set the MOZ_DEBUG_APP_PROCESS before executing For example to debug the Camera app:


Then after we try to start Camera, it will print the process id to adb logcat and we could run a second gdb to attach to the child process.

$ ./ attach <child pid>

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.


Document Tags and Contributors

 Contributors to this page: VincentLiu, borischiou, pchang, Sheppy, bgirard, kanru
 Last updated by: VincentLiu,