Failure Signal Handler¶

Stacktrace as Default Failure Handler¶

The library provides a convenient signal handler that will dump useful information when the program crashes on certain signals such as SIGSEGV. The signal handler can be installed by nglog::InstallFailureSignalHandler().

The example intentionally aborts, so a nonzero exit status is expected. The time, addresses, process identifiers, thread identifiers, and source lines vary between runs.

*** Aborted at 1785404553 (unix time) try "date -d @1785404553" if you are using GNU date ***
*** SIGABRT (@0x3e800000003) received by PID 3 (TID 0x7f206db1c700 LWP 3 thread "color_stacktrac") from PID 3; stack trace: ***
PC: @     0x7f206d49a01c (unknown)
    @     0x7f206dc47a4b src/signalhandler.cc:790 nglog::(anonymous namespace)::FailureSignalHandler(int, siginfo_t*, void*)
    @     0x7f206d43e6f0 (unknown)
    @     0x7f206d49a01c (unknown)
    @     0x7f206d43e5d0 gsignal
    @     0x7f206d425685 abort
    @     0x7f206dc0a045 src/logging.cc:2182 nglog::LogMessage::Fail()
    @     0x7f206dc0dc06 src/logging.cc:2846 nglog::LogMessageFatal::~LogMessageFatal()
    @     0x5568e96c13cf examples/color_stacktrace.cc:54 (anonymous namespace)::CrashThroughFewFrames(int)
    @     0x5568e96c132d examples/color_stacktrace.cc:42 (anonymous namespace)::CrashThroughFewFramesIndirectly(int)
    @     0x5568e96c135d examples/color_stacktrace.cc:47 (anonymous namespace)::CrashThroughFewFrames(int)
    @     0x5568e96c132d examples/color_stacktrace.cc:42 (anonymous namespace)::CrashThroughFewFramesIndirectly(int)
    @     0x5568e96c135d examples/color_stacktrace.cc:47 (anonymous namespace)::CrashThroughFewFrames(int)
    @     0x5568e96c132d examples/color_stacktrace.cc:42 (anonymous namespace)::CrashThroughFewFramesIndirectly(int)
    @     0x5568e96c135d examples/color_stacktrace.cc:47 (anonymous namespace)::CrashThroughFewFrames(int)
    @     0x5568e96c17f2 examples/color_stacktrace.cc:107 main
    @     0x7f206d427781 (unknown)
    @     0x7f206d4278b9 __libc_start_main
    @     0x5568e96c11f5 _start

When writing to a terminal, this output is colorized: the address, file:line, and function name of each frame are colored separately, and file:line references become clickable hyperlinks back to the source.

Customizing Handler Output¶

By default, the signal handler writes the failure dump to the standard error. However, it is possible to customize the destination by installing a callback using the nglog::InstallFailureWriter() function. The function expects a pointer to a function with the following signature:

void YourFailureWriter(const char* message/* (1)! */, std::size_t length/* (2)! */);

1. The pointer references the start of the failure message.

   Danger

   The string is not null-terminated.

2. The message length in characters.

User-defined Failure Function¶

FATAL severity level messages or unsatisfied CHECK condition terminate your program. You can change the behavior of the termination by nglog::InstallFailureFunction.

void YourFailureFunction() {
  // Reports something...
  exit(EXIT_FAILURE);
}

int main(int argc, char* argv[]) {
  nglog::InstallFailureFunction(&YourFailureFunction);
}

By default, ng-log tries to dump the stacktrace and calls std::abort. The stacktrace is generated only when running the application on a system supported¹ by ng-log.

Resolving File Names and Line Numbers¶

When built with WITH_LINE_INFO set to auto (the default), addr2line, or libbacktrace, ng-log resolves the source file and line number of each stack frame, in addition to the symbol name. This applies to both the failure signal handler and LOG(FATAL)/unsatisfied CHECK traces. WITH_LINE_INFO=none disables the feature.

Two backends provide this:

• addr2line invokes the addr2line command-line tool as an external process with a bounded timeout, so a missing or unresponsive addr2line only suppresses the file and line information rather than affecting the rest of the crash report.
• libbacktrace resolves the symbol name and the file and line number in-process, directly from the DWARF debug information, without spawning a subprocess per frame. It requires the libbacktrace library to be available at build time.

auto prefers libbacktrace when it is available and falls back to addr2line otherwise. Forcing one backend with WITH_LINE_INFO means the other is never even probed.

When built with MinGW, addr2line or libbacktrace also replace dbghelp as the symbol resolver entirely rather than supplementing it, since dbghelp cannot read the DWARF debug information a MinGW build emits by default. MSVC builds always use dbghelp, since neither backend understands MSVC's mangled names or debug information.

Resolution can be disabled at runtime without recompiling by setting FLAGS_symbolize_line_info to false, or --symbolize_line_info=false on the command line. The FLAGS_addr2line_timeout_ms flag controls how long, in milliseconds, ng-log waits for addr2line to resolve a single address before giving up on it. It has no effect when libbacktrace is the active backend.