How to report bugs usefully

Systemtap operates close to the hardware - within the operating system kernel. As such, bugs can manifest themselves in ways that are unusually hard to debug. To give developers a fighting chance, they need a considerable amount of information. This page attempts to enumerate the kinds of useful information, and tells you how to submit it all. The stap-report script may help gather data.

All problems

We need to know which version of systemtap you're running, and on what script.

Translation-time problems

The systemtap tutorial contains some information on common errors detected during translation/compile time. Errors in this stage may be mystifying, but at least they are safe: the system won't have run anything privileged or dangerous yet.

If the translator (stap) crashes outright (SIGSEGV, assertion failure), the chances are good that the problem can be identified and fixed. Run it under a debugger, and report the stack traceback: gdb -args stap ...., then backtrace at the (gdb) prompt after the crash.

If the probe module loader (staprun) crashes, run it under gdb the same way. Since stap runs staprun via sudo, you may need to run gdb -args staprun .... as root.

GDB will produce better backtraces if your systemtap binary is compiled with debugging (-g). If you are running a prepackaged copy of systemtap, try installing its own -debuginfo package (if available for your distribution).

System crashes

The most unfortunate problems occur when systemtap compiles your probe script properly, but then the machine dies. It may be a problem with systemtap, or the kernel, or the compiler, or something totally different. The following information tends to help narrow down the possible list of suspects:

Submitting the problem report

To get started, it may help to read Eric Raymond's essay on asking questions the smart way. Imagine that the developers are robotic information eaters, and need to be talked in a crisp and information-dense way. It's nothing personal.

The bluntest way to get developers' attention is to file a report directly into our bug tracking system. Use the product "systemtap". Describe what you saw with as much detail as is reasonable. There is no need for multi-megabyte trace files, but numerous small attachments would be fine. Each new bugzilla entry sends an instant email to our mailing list, so the developers get notified right away. They may ask you further questions, to submit more specific information; or they may apologize, grovel, and swear that the bug will be fixed tomorrow. Or not (sorry).

If the bug tracking system seems too formal for you, you may just send the essentials to the mailing list directly. Or you can strike up a conversation on IRC, just in case one of the developers is taking a break from the whipping-induced coding frenzy (irc.freenode.net, #systemtap).

None: HowToReportBugs (last edited 2009-06-16 16:53:36 by FChE)