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. XXX link to example bug

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

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?