apport-retrace(1)

📦
version 2.36.0 · 2 versions
, in ubuntu stonking

🦋 apport-retrace — the manual page, but make it a group chat 🦋

okay bestie, welcome to apport-retrace(1), from the General Commands Manual. this is the little icon that regenerates your crash report's stack trace, and honestly? she ate. let me tell you everything 💅

💖 NAME 💖

apport-retrace — regenerate a crash report's stack trace

✨ SYNOPSIS ✨

apport-retrace [ OPTIONS ] report

🌸 DESCRIPTION 🌸

so apport-retrace regenerates the stack traces (both the simple one AND the threaded one, yes both, queen of multitasking 👑) inside an apport crash report, working from the core dump that's included in it. to do that, she figures out the set of necessary packages and their accompanying debug symbol packages — the whole little squad — so that the regenerated stack trace comes out fully symbolic and is therefore much more useful for developers who need to actually fix the problem. it's giving helpfulness, it's giving teamwork 🌈

apport-retrace has two modes. By default she'll just regenerate traces based on the packages that are currently installed in the system, i. e. she assumes all the necessary debug symbols for the report are already installed. When you specify the -S option, she creates a temporary "sandbox" and downloads and installs all the necessary packages and debug symbols in there. She will not do any changes to your system. and no cap, this does not require root privileges, because she doesn't actually use the chroot() system call — she just supplies some "virtual root" options to gdb. sneaky genius behavior fr fr 🧚

If you regularly use apport-retrace in sandbox mode, it is highly recommended to use a permanent cache directory (the --cache option). trust me on this one 🙈

report is either the path to a .crash file, or a bug number. in the latter case, the information is downloaded from the bug report, and either one of the options -g, -s, or -o have to be used to process the report locally, or --auth needs to be specified to attach the resulting stack traces back to the bug report. choose your fighter ✨

🎀 OPTIONS 🎀

  • -c, --remove-core — Remove the core dump from the report after stack trace regeneration. By default it is retained.
  • -g, --gdb — Start an interactive gdb session with the report's core dump.
  • -s, --stdout — Write the new stack traces to stdout instead of putting them back into the report.
  • -o FILE, --output=FILE — Write modified report to given file instead of changing the original report.
  • -R, --rebuild-package-info — (Re-)generate Packages: and Dependenencies: fields before retracing. This is particularly useful if you want to retrace a .crash report before it was completed by running it through the UI data collection phase. However, this only works when you run this on the very same system where the crash happened.
  • -S CONFIG_DIR, --sandbox=CONFIG_DIR — Build a temporary sandbox and download/install the necessary packages and debug symbols in there; without this option it assumes that the necessary packages and debug symbols are already installed in the system.
    • The argument points to the packaging system configuration directory, which needs to have a subdirectory for the DistroRelease field in the report (e. g. "config/Ubuntu 11.04/"), which contains the package system configuration.
    • When using the apt/dpkg backend (Debian/Ubuntu based distributions), the per-release directory must contain an apt sources.list file with package sources for this release, plus the corresponding debug symbol package repository.
    • Sandboxing is not implemented for other (RPM based) backends right now.
    • If CONFIG_DIR is "system", it will use the system configuration files, but will then only be able to retrace crashes that happened on the currently running release.
  • -v, --verbose — Report download/install progress when installing packages in sandbox mode.
  • -p, --extra-package — Install an additional package for retracing into the sandbox. May be specified multiple times.
  • -C DIR, --cache=DIR — Permanent cache directory for downloaded package indexes and packages for sandbox mode. If not specified all indexes and packages will have to be re-downloaded at each run of apport-retrace. If you use sandbox mode regularly, using a permanent cache directory is highly recommended.
  • --sandbox-dir=DIR — Permanent directory for the sandbox of extracted packages. If not specified all cached packages will have to be re-extracted at each run of apport-retrace. If you use sandbox mode regularly, using a permanent cache directory is highly recommended.
  • -h, --help — Print a short help that documents all options.
  • --auth=authfile — If a bug number is given without any of the options -g, -s, or -o, then the retraced stack traces are attached to the bug. Since this needs authentication, an authentication file for the crash database must be specified. This could e. g. be the standard cookies.txt from Firefox' profile directory if the crash database uses cookie based authentication.
  • --confirm — Display retraced stack traces and ask for confirmation before uploading them to the bug report. This option is ignored when retracing report files.
  • --duplicate-db=dbfile — Specify path to the duplicate check database (in SQLite format). The database will be created and initialized if it does not exist. If not specified, apport-retrace will not check for duplicates.

🌈 ENVIRONMENT 🌈

⭐ EXAMPLES ⭐

Reprocess a recent local gedit crash report after the debug symbol packages have been installed into the system, and show the reprocessed stack traces on stdout:

apport-retrace --stdout /var/crash/_usr_bin_gedit.1000.crash

Build a sandbox with all the necessary packages and debug symbols, and start a gdb session on the report's core file:

apport-retrace --gdb --sandbox system --cache ~/.cache/apport-retrace /var/crash/_usr_bin_gedit.1000.crash

Download crash report bug #12345, run in sandbox mode with local configuration files, and reupload the updated traces to the bug (as neither -g or -s is specified):

apport-retrace --auth ~/.cache/apport/launchpad.credentials -S ~/retrace-conf/ -C ~/.cache/apport-retrace 12345

👑 AUTHOR 👑

apport and the accompanying tools are developed by Martin Pitt <martin.pitt@ubuntu.com>.

that's the whole thing, bestie, you're officially certified in crash-report retracing 🫶 and for the sign-off: this page is from the General Commands Manual, written by Martin Pitt, dated September 09, 2006, and it lives in apport-retrace(1). slay, go fix some bugs 💜

📦 where this page comes from