Backtrace

Since 0.3, Safely supports logging all exceptions to a file when a Ruby program terminates abnormally. This is extremely useful when your program suddenly falls over and you have no idea why.

Dependencies

It uses the standard Ruby Logger library.

Configuration

You need to provide the backtrace class with an existing directory where it can dump backtrace files into:

  Safely::Backtrace.trace_directory = "/some/where/to/logs"

Usage

Once you have configured the backtrace class, you simply enable it:

  Safely::Backtrace.enable!

When your program exists, all exceptions found in the object space will be logged to a file in the trace_directory, named "backtrace-YYYYMMDDHHMMSS-PID.log", ensuring unique files for each crash.

But what about clean shutdowns?

I hear you, it isn't always necessary to log exceptions upon program termination. Lets say your program responds to the TERM signal, as an example. When you handle this signal and prepare for a clean shutdown you need to inform Safely of this:

  trap("TERM") do
    Safely::Backtrace.safe_shutdown!
    performing_shutdown_routines
  end

The call to safe_shutdown! lets Safely know to disable logging any backtraces.

Why so many exceptions?

Ruby's object space may contain plenty of exceptions that got raised during the lifetime of your application. The backtrace assumes the last exception thrown was the one that killed the program, however it logs all of them. Depending on how often the GC does it's work, you'll almost always see a varying number of logged exception objects.