1 Introduction
2 Interface
3 History
4 Legal
Version: 1:0

gdbdump: GDB-based Native Thread Backtrace Dumps for Racket

Neil Van Dyke

 (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.
(gdbdump)  void?
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

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.