Version: 1:0
gdbdump: GDB-based Native Thread Backtrace Dumps for Racket
| (require (planet neil/gdbdump:1:0)) |
1 Introduction
The gdbdump package is a possible aid in debugging potential system problems
in a Racket-based production application. It is designed to be used by the
application program itself, perhaps when an error condition is detected, or
when invoked by a system administrator from a management console user
interface.
Specifically, invoking the gdbdump procedure attempts to use the GNU Debugger (GDB) to attach temporarily to the process, and dump full native
code backtraces of all native threads to a file. This file can then be given
to programmers for debugging. This might be helpful, for example, if problems
with low-level system calls or native code libraries invoked via the FFI.
The gdbdump package is currently only for GNU/Linux and similar Unix-like
systems, with GDB installed.
2 Interface
The main interface is the gdbdump procedure. Options are set via parameters, rather than as
arguments to gdbdump, so that they can be type-checked during normal operation of the
program, since gdbdump might be applied only rarely and in already exceptional
circumstances.
(current-gdbdump-gdb-program) → string? (current-gdbdump-gdb-program filename) → void? filename : string?
String for the complete path to the GDB executable. The default is to try (find-executable-path "gdb"), as evaluated at time the gdbdump package is loaded, and to falls back to "/usr/bin/gdb". So, if installing GDB for use by gdbdump in a process that is already running, you will want to have it
accessible as "/usr/bin/gdb", via symbolic link if not by file.
(current-gdbdump-file) → complete-path? (current-gdbdump-file path) → void? path : complete-path?
Complete path to the file to which the dump should be written. By default, it is (build-path (find-system-path 'temp-dir) "gdbdump"), for example, "/var/tmp/gdbdump".
(current-gdbdump-local-sleep) → (>=/c 0) (current-gdbdump-local-sleep seconds) → void? seconds : (>=/c 0)
Number of seconds to sleep between spawning the subprocess that will invoke GDB, and
checking the results or killing the process. The default is 10.
Attempts to use GDB to get native backtraces of all native threads of the native process hosting the current Racket evaluation, writing them to the file specified by current-gdbdump-file.
The GDB executable from current-gdbdump-gdb-program is used. GDB is invoked under a "/bin/sh" process, after a brief sleep in the "sh" process, to possibly give the Racket thread applying gdbdump a chance to sleep. All three basic stdio ports of the "sh" and GDB processes should be files, and not pass through the
Racket process. (Note: It is conceivable that GDB will run before the Racket
thread sleeps, such as if a long GC cycle is triggered immediately after
creating the subprocess.)
If the GDB process is still running after current-gdbdump-local-sleep seconds have elapsed, it is killed.
After attempting to use GDB, an event is logged to the current logger via log-info or log-error.
3 History
- PLaneT 1:0 —
2012-06-25 Initial release. Tested lightly.
4 Legal
Copyright 2012 Neil Van Dyke. This program is Free Software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but without any warranty; without even the implied warranty of merchantability or fitness for a particular purpose. See http://www.gnu.org/licenses/ for details. For other licenses and consulting, please contact the author.