Dev Week -- Getting more detailed bug reports -- bdmurray -- Thu, Jan 28


   1 [18:00]  * ogasawara hands off to bdmurray 
   2 [18:00]  * bdmurray takes the mic
   3 [18:01] <bdmurray> Hi, my name is Brian Murray and I'm a member of the Ubuntu QA team.
   4 [18:01] <bdmurray> I'm here today to talk about how you can get higher quality bug reports about packages that you care about.
   5 [18:02] <bdmurray> One way you can do this is by writing an apport hook for your particular package.
   6 [18:02] <bdmurray> Let's start off by talking about what apport is.
   7 [18:02] <bdmurray>  Apport is a system which intercepts crashes right when they happen, in development releases of Ubuntu, and gathers useful information about the crash and the operating system environment.
   8 [18:02] <bdmurray> Additionally, it is used as a mechanism to file non-crash bug reports about software.
   9 [18:03] <bdmurray> This allows us to define what software we want to receive bug reports about and what information will be included in those bug reports.
  10 [18:03] <bdmurray> Let's look at a sample apport bug report -
  11 [18:03] <bdmurray> The bzr package does not have an apport hook but some useful information is still collected.
  12 [18:04] <bdmurray> We have the architecture, the release being used, the package version and the source package name.
  13 [18:04] <bdmurray> Additionally, in the Dependencies.txt attachment we have information about the versions of packages upon which bzr depends.
  14 [18:04] <bdmurray> Are there any questions so far?
  15 [18:06] <bdmurray> Okay, so while all of that can be helpful an apport hook for a package allows us to gather specific information for a package.
  16 [18:06] <bdmurray> For example, consider a bug report about usplash.  usplash has a dedicated configuration file, located at "/etc/usplash.conf", and this would be something quite helpful in debugging a usplash bug report but not very useful in other package bug reports.
  17 [18:06] <bdmurray> Apport looks for package hooks in "/usr/share/apport/package-hooks/" on the local system for ones named after the package for which they will be used.
  18 [18:07] <bdmurray> Looking in "/usr/share/apport/package-hooks/" lets take a look at the usplash hook - with the filename  I've also pastebin'ed the hook to
  19 [18:07] <bdmurray> The package hooks are written in python.
  20 [18:07] <bdmurray> We can see that the hook imports the apport.hookutils module - "from apport.hookutils import *".
  21 [18:08] <bdmurray> hookutils is a collection of readymade and safe functions for many commonly used things.  There are functions for attaching a file's contents, getting a command's output, grabbing hardware information and much more.
  22 [18:08] <bdmurray> This package hook is using 'attach_file_if_exists' and 'attach_hardware'.  'attach_file_if_exists' is pretty self explanatory but what does attach_hardware include?
  23 [18:09] <bdmurray> Let's look at the hookutils module to find out.  You can use "python -c 'import apport.hookutils; help(apport.hookutils)'" or you can view it using codebrowse -
  24 [18:09] <bdmurray> The 'attach_hardware' function starts at line 72.
  25 [18:10] <bdmurray> As we can see it adds a wide variety of hardware information to a bug report which can be quite useful for some packages like the kernel and usplash!
  26 [18:11] <bdmurray> Having the apport package hooks has reduced the amount of bug "ping pong" necessary to get information out of a bug reporter and having these convenience functions reduces the amount of work it takes to write a package hook.
  27 [18:12] <bdmurray> In addition to 'attach_hardware' and 'attach_file_if_exists' other functions include: 'attach_conffiles', 'attach_dmesg', 'attach_alsa', 'command_output', 'recent_syslog', 'pci_devices' and 'attach_related_packages'.
  28 [18:13] <bdmurray> In the event that you have a group of packages that would benefit from a shared convenience function, please file a bug about apport and include the function you'd like added.
  29 [18:13] <bdmurray> Are there any questions so far?
  30 [18:15] <bdmurray> So, back to the usplash hook, we can see that the usplash configuartion file is added like so "attach_file_if_exists(report, '/etc/usplash.conf', 'UsplashConf')".
  31 [18:15] <bdmurray> This means that a bug reported about usplash using apport should have an attachment named 'UsplashConf' and it will contain the reporter's usplash.conf file.
  32 [18:16] <bdmurray> Looking at we can see this actually isn't the case.
  33 [18:16] <bdmurray> Because usplash.conf is only 4 lines it ends up getting put into the bug description.  However, most items end up getting added as attachments in Launchpad.
  34 [18:17] <bdmurray> For example, lspci-vnvn.log or BootDmesg.txt
  35 [18:17] <bdmurray> Let's take a look at another package hook for apport.
  36 [18:18] <bdmurray> The totem hook is particularly interesting as it is utilizes interactive questions - which is a new feature in apport.
  37 [18:18] <bdmurray> You can see how this works by executing "ubuntu-bug totem", but please don't actually report the bug! ;-)
  38 [18:19] <bdmurray> More detailed information regarding how to use the hook user interface can be found in the python help for the available functions: "python -c 'import apport.ui; help(apport.ui.HookUI)'".
  39 [18:20] <bdmurray> The totem hook asks questions and runs tests to determine if the bug report is related to alsa, pulseaudio or codecs in gstreamer.
  40 [18:20] <bdmurray> It then sets the affected package appropriately.
  41 [18:21] <bdmurray> The interactive hook greatly reduces the amount of triaging work required (as questions are asked before the bug is reported instead of after) and helps make the initial bug report much more complete.
  42 [18:22] <bdmurray> Oh, here's a link to the totem hook -
  43 [18:23] <bdmurray> Are there any questions regarding the material I've covered so far?
  44 [18:25] <bdmurray> Now that we know a lot of what hooks can do, lets talk about how to write one.
  45 [18:26] <bdmurray> After the Karmic Ubuntu Developer Summit I compiled a list of packages that had recently received a fair number of bug reports and subsequently might benefit from an apport package hook.
  46 [18:26] <bdmurray> That list can be found at
  47 [18:27] <bdmurray> < yltsrc> QUESTION: where i can find hooks for all default ubuntu
  48 [18:27] <bdmurray>                 applications?
  49 [18:28] <bdmurray> yltsrc: they will be installed on your system in "/usr/share/apport/package-hooks".  Each hook is distributed with the package it is used for instead of being distributed with apport.
  50 [18:28] <bdmurray> This allows developers to add hooks to their own package and not having modify 2 packages.
  51 [18:29] <bdmurray> < qense> QUESTION: Is there a nice table showing what packages have and
  52 [18:29] <bdmurray>                what haven't got Apport hooks?
  53 [18:30] <bdmurray> qense: there is a likely incomplete list at
  54 [18:30] <bdmurray> I'll update it soon though
  55 [18:31] <bdmurray> Back to writing an apport hook - Let's take rhythmbox from that list and write a simple apport hook for it.
  56 [18:31] <bdmurray> The easiest way of writing and testing a package hook is to put one in "/usr/share/apport/package-hooks" named after the appropriate package.
  57 [18:32] <bdmurray> I'll create one called "".
  58 [18:34] <bdmurray> We'll import hookutils from apport and os, then in the add_info function we'll add the rhythmdb.xml file, if it exists, and gconf settings for rhythmbox.
  59 [18:34] <bdmurray> The hook as written looks like
  60 [18:35] <bdmurray> Its really only 2 lines of code but now we'll have some potentially useful information in every rhythmbox crash or bug report,
  61 [18:36] <bdmurray> After I've put this file in "/usr/share/apport/package-hooks" I can test it using "ubuntu-bug".
  62 [18:37] <bdmurray> After running "ubuntu-bug rhythmbox", apport presents the user with a dialog asking them if they want to send the problem report.
  63 [18:38] <bdmurray> In this dialog box we can see the complete contents of the report and if our collected information was attached.
  64 [18:39] <bdmurray> I see a key named rhythmdb.xml which contains the same information as the one on my system and a key named GconfRhythbox which contains my gconf settings for rhythmbox.
  65 [18:39] <bdmurray> That's really all there is to writing and testing an apport hook!
  66 [18:40] <bdmurray> In the event that you write a hook for a package that you can not upload or need help getting sponsored, please report a bug about the package missing a hook.
  67 [18:40] <bdmurray> Then add the hook as a patch (or a merge proposal) and subscribe me, brian-murray, and the appropriate sponsor's team to the bug report.
  68 [18:41] <bdmurray> I'll work to ensure that it gets uploaded.
  69 [18:41] <bdmurray> Another thing to consider is that a hook isn't just useful for bug reports going forward,
  70 [18:42] <bdmurray> it could actually help you out with your existing bug reports!
  71 [18:43] <bdmurray> For example, if you write a hook for your package right now and get it included in Lucid you could then have bug reporters execute 'apport-collect' and the number of the bug they've reported.
  72 [18:43] <bdmurray> This will then use the package hook to include the information you want in the already reported bug.
  73 [18:44] <bdmurray> Are there any more questions about writing apport package hooks?
  74 [18:47] <bdmurray> Another way to get more detailed bug reports is by setting the bug filing guidelines for packages in Launchpad.
  75 [18:48] <bdmurray> These are presented when someone files a bug via the web interface at Launchpad.
  76 [18:48] <bdmurray> For example if you were to file a bug about ffmpeg at ... you would be presented with the package's bug filing guidelines -
  77 [18:49] <bdmurray> This particular package's bug guidelines asks for specific information that would be rather challenging to gather with an apport hook.
  78 [18:50] <bdmurray> The bug reporting guidelines for ffmpeg can be set at  The url will be similar for any other package
  79 === z is now known as Guest44291
  80 [18:50] <bdmurray> In the event that you don't have the ability to set the guidelines for a package you care about for some reason, please let me know and I'll be happy to get them set for you.
  81 [18:51] <bdmurray> I see there are some questions!
  82 [18:51] <bdmurray> < barcc> QUESTION: can i use apport hook for a project not included in ubuntu but hostet on launchpad?
  83 [18:52] <bdmurray> barcc: possibly.  you might look at the ubuntuone-client hook as an example.
  84 [18:52] <bdmurray> In particular the following lines
  85 [18:52] <bdmurray>     if not apport.packaging.is_distro_package(report['Package'].split()[0]):
  86 [18:52] <bdmurray>         report['ThirdParty'] = 'True'
  87 [18:52] <bdmurray>         report['CrashDB'] = 'ubuntuone'
  88 [18:53] <bdmurray>  < vocx> QUESTION: are debug symbols required to be installed before calling apport? what are debug symbols used for?
  89 [18:54] <bdmurray> No they are not required, an incomplete (w/o debugging symbols) is uploaded to Launchpad and the the retracer takes care of installing the debug symbols and retracing the bug for you
  90 [18:54] <bdmurray> You could install the debugging symbols your self if you wanted to manually run gdb and get some detailed output about a crash
  91 [18:55] <bdmurray> < barcc> QUESTION: is it possible to test apport hooks against lauchpad staging?
  92 [18:57] <bdmurray> barcc: I believe so. If you look at /etc/apport/crashdb.conf there might be a line like #'staging': True
  93 [18:57] <bdmurray> You could comment that out and then report a bug.
  94 [18:58] <bdmurray> However, I've found the dialog that apport presents before filing a bug to be sufficient
  95 [18:58] <bdmurray> Are there any more questions?
  96 [18:58] <bdmurray> If you need any further help the apport code is very well documented and there are a few wiki pages about it - and  Additionally, you can find me in the ubuntu-bugs channel.  Thanks!
  97 [19:00] <bdmurray> Okay, thanks everyone and have a great day!


  • To use an apport hook for a project not included in Ubuntu but hosted on Launchpad, you need to modify's hook as you explained at 18:52, but you also need to install a configuration file in /etc/apport/crashdb.conf.d/ . You can find instructions at Apport Developer How To.

  • To test ubuntu-bug on Launchpad's staging environment, the environment variable APPORT_STAGING needs to be set to "1". There is no staging configuration line in /etc/apport/crashdb.conf (mentioned at 18:57).

MeetingLogs/devweek1001/DetailingBugs (last edited 2010-02-09 22:44:06 by 131)