When I plugged my Mac into an external monitor yesterday, my nightly build of Firefox “beachballed” and became non-responsive. I was experiencing a browser hang.
I wanted to do what I could to help our engineers understand what caused the problem, and my colleague Jeff Muizelaar showed me what to do. I figured that I’d share that knowledge with you, gentle reader, in case you were also interested in doing what you could to help the Mozilla project with the development of the Firefox browser.
Requirements:
- a Mac running OS X (I’ll write another post later on how to do this on Windows, too)
- a nightly Mac build of Firefox (don’t worry – they’re stable; I use it as my day-to-day browser)
- XCode installed on your computer (this is also included on your OS X DVD)
When Firefox “beachballs”:
When you see a colourful spinning disc (also known as a “beachball”) instead of a mouse cursor while hovering over a Firefox window, you’re experiencing a hang. If this lasts a long time, you’ll want to file a bug so that our engineers can investigate the source of the problem. To help them do this, you can collect two sources of information:
Profiling Firefox with Shark:
In the “Developer” folder installed by XCode there’s a folder called “Applications”, and inside that there’s a folder called “Performance Tools” and inside that there’s a program called “Shark.app”. You should also be able to find it with Spotlight.
- Launch Shark.app
- Select “Time Profile”, “Process”, “firefox-bin” and set the time limit to 30s

- Press Start
- Stop it anytime after 10 seconds if you’re not patient enough to wait the full 30s
Once it’s done collecting samples, Shark will analyse them and produce a chart indicating where Firefox was spending it’s time. Congratulations! That’s the first piece of information which will help the engineering team.
Getting a stack trace with gdb:
The next thing you can collect is a stack trace. Here’s how:
- Open a terminal window and type “ps aux | grep firefox-bin | grep -v grep” – this returns a list of running processes that match the name “firefox-bin”
- Make a note of the process number – it’s the first number in the line of text, usually three or four digits – let’s pretend it was 6115 like in the screenshot below.
- Type “gdb” to launch the debugger that was installed with XCode
- Type “attach 6115″ where “6115″ is the process number you got from step 1

- Wait a few seconds for the debugger to attach to your Firefox process
- Type “bt”
- Type “detach” to detach from the Firefox process
- Type “quit” to quit the debugger
Congratulations! Now you have a window with a stack trace! You can now force-quit Firefox and restart it, since you’ll need it to file the bug.
Now you’re ready to file a bug:
Bugzilla isn’t a very friendly tool at times, but it’s powerful and what we use. Don’t worry if your bug is a duplicate, people check for those and duplicate bugs end up being very helpful, so please don’t hesitate to file them. When dealing with a hang, it’s probably best to file the bug in the Firefox::General component and start the summary with the word “hang”. Try to write a summary that represents what you were doing when Firefox hung, like “hang when I plug in an external monitor” or “hang when I click on a link from Tweetie”.
- Go to bugzilla.mozilla.org and log in (you may need to create an account)
- Click on File a Bug
- Select Firefox as the product and General as the component unless you suspect it’s associated with something in particular based on the Shark analysis or stack trace
- Write a summary that starts with the word “hang” and expresses what you were doing when Firefox hung
- Type a few sentences at the top of the report that describes what you were doing, and what version of Firefox you’re using (you can copy the “build identifier” from the page that appears when you type “about:” into the location bar and hit enter)
- Expand all the twisties in the Shark analysis window, select all the rows, then copy them and paste them into the bug report
- Scroll back the Terminal window and copy the stack trace into the bug report
- Submit the bug report
I filed a bug on the hang I was experiencing using these steps, and that information may save our users from experiencing the same hang in the future. This is an important part of the open source process, and using these steps, hopefully you’ll also be able to take part in the development of Firefox.