Filing good X bug reports

For Ubuntu, a *lot* of time and effort goes into triaging X bugs. Mostly, this work consists of helping bug reporters get enough data to actually begin troubleshooting the problem. Sadly, a lot of bugs go uninvestigated due to lack of enough info.

I have noticed lately though, that a number of reporters are starting to include the info needed, which is great! Developers can then focus their time in actually solving their problem rather than requesting files and trying to think about what to ask for that might give clues.

If nothing else, the #1 most important thing to always include when reporting an X bug is your /var/log/Xorg.0.log. This file is chock full of useful data... versions of modules, configs, resolutions identified, warnings, error messages, and sometimes even partial backtraces. If you remember nothing else, please remember this one thing: "When reporting an X bug, ALWAYS include your Xorg.0.log".

Sometimes Xorg.0.log isn't necessary, but it seems like 80-90% of the time I need some bit of data which is there, so unless you're *certain* it's not needed, make every attempt to include it. If you can include it directly with your report at the time you submit it, you can save triagers time and decrease the time before someone takes a stab at troubleshooting your problem.

The #2 most important thing to include depends a bit on what type of X bug you've encountered. I'd group X bugs like this:

Screen Corruption. A photograph of the screen helps a lot, since it's often hard to describe in words, but can be obvious when you see it.

X Crashes/Lockups/Freezes. Many people report these kinds of X breakages; certainly they are troubling, and unfortunately not as rare as we'd like to make them. The important thing to include is a full backtrace with debug symbols installed (see the directions). Indeed, there really is *nothing* anyone can do to troubleshoot this class of bug without a backtrace, and we'll usually close these bug reports if no backtrace is posted in a reasonable amount of time.

If you're not familiar with what a backtrace is, it's basically a list of the function calls that were made immediately leading up to the crash. A 'full' backtrace also includes the values of the function's parameters and local variables, which is useful for spotting NULL pointers, invalid strings or indexes, etc.

I can't emphasize the importance of full backtraces enough. I've noticed that somewhere around 20-30% of the time where a full backtrace is posted, we're able to identify the bug and propose a patch directly. Often the bugs are simple null pointer dereferences or other obvious coding issues, we can patch immediately and post upstream. Without a backtrace there would be no way to identify these fixes.

"But it worked in Gutsy...?". X changes a lot. New functionality is continually being added and we want to make the new stuff available as we put out new Ubuntu's. Unfortunately, sometimes new code means new bugs. I see a lot of irritation when people find that something that worked fine in the previous stable release suddenly stops working in the development release.

These kind of bugs have a surprisingly effective brute force way to isolate the problem: Just start checking some of the intermediary versions between the stable and development releases. (Usually this involves building from upstream's git repository, perhaps using 'git bisect'. Stay tuned, I have ideas on how to make this easier for folks.)

Everything Else. Of course, there are many other kinds of failures... configuration errors, wrong DPI's, performance problems, and on and on. Use your judgment in what to include in addition to Xorg.0.log. Sometimes experimenting with alternate xorg.conf Options is worth doing. Sometimes checking with a different monitor, or with Compiz turned on or off can produce useful info. More tips are on the Reporting X Bugs page.

Posted in Submitted by bryce on Mon, 2008-04-21 22:30.
bryce's blog | login or register to post comments