How to Use Apport in your Programs

By default, apport provides the following functionality for all programs in Ubuntu:

• When a program segfaults, apport stores a persistent crash report in /var/crash which can be later analyzed even if the bug cannot be reproduced by a developer

• Relevant information about the state of the system and installed software is automatically included in the report
• Apport can semi-automatically attach the crash report to a bug report in Launchpad

• For C and C++ programs, the [:../Retracer:retracer] will automatically decode the stack trace in the crash report and attach the decoded stack trace to the bug report. See [https://bugs.launchpad.net/ubuntu/+source/gvfs/+bug/252046 bug #252046] as an example how this looks like.

Package Hooks

In addition to the generic information apport collects, arbitrary package-specific data can be included in the report by adding package hooks. For example:

• Relevant log files
• Configuration files
• Current system state

Hooks can also cause a crash to be ignored, or the report suppressed with an explanation.

To create a hook, have your package install a file /usr/share/apport/<binarypackagename>.py or /usr/share/apport/source_<sourcepackagename>.py. The hook will be used whenever apport logs a report for the specified package. Here's a simple example of a hook:

import os.path

def add_info(report):
    if os.path.exists('/var/log/foo.log'):
        report['FooLog'] = open('/var/log/foo.log').read()

'report' is a Python dictionary which can be used to store arbitrary data using a string key.

For complete instructions, see /usr/share/doc/apport/package-hooks.txt

General Hooks

These are the same as package hooks, but apply to all packages. They can be used, for example, to implement a 'taint check' which reports on whether certain problematic software is installed, regardless of which program is misbehaving. They are installed in /usr/share/apport/general-hooks/*.py.

For complete instructions, see /usr/share/doc/apport/package-hooks.txt

Bug patterns

Apport can suppress reports for bugs which have already been reported. Sometimes a bug affects so many people that we get hundreds of duplicates in a matter of days, which both creates a lot of needless reporting, triaging, and retracing work. In those cases, and when the bug can be uniquely identified with regular expressions on the apport report keys, a "bug pattern" should be created which will prevent Apport from reporting the bug in the first place, and instead guide the user to the already existing bug page.

To avoid inventing a new file format and to be able to extend the functionality in the future (e. g. other operators than just regexp matching) the bug patterns are stored as XML files, named after the binary package.

The general syntax is:

• {{{ root element := <patterns> patterns := <pattern url="http://bug.url"> * pattern := <re key="report_key">regular expression*</re>

}}}

For example:

• {{{ <?xml version="1.0"?> <patterns>

  • <pattern url="https://launchpad.net/bugs/1">

    • <re key="Foo">ba.*r</re>

    </pattern> <pattern url="https://launchpad.net/bugs/2">

    • <re key="Foo">write_(hello|goodbye)</re> <re key="Package">^\S* 1-2$</re> <!-- test for a particular version -->

    </pattern>

  </patterns>

}}}

The bug patterns are publicly accessible at http://people.ubuntu.com/~pitti/bugpatterns/, where Apport (when running on the client side) will check for them. They are maintained in a [https://code.launchpad.net/~ubuntu-bugcontrol/apport/ubuntu-bugpatterns bzr branch] accessible to the [https://launchpad.net/~ubuntu-bugcontrol/ Ubuntu bug control] team, and copied to people.ubuntu.com every 15 minutes.

Custom Invocation

For still greater flexibility, apport can be invoked explicitly to trap and report on custom events, even if no signal-driven crash (such as a segfault) has occurred. For example, GCC can trap internal compiler errors, and the kernel can trap system crash dumps.

XXX examples

TODO

• Apport in external projects?

• Describe UnreportableReason