Expand description
Support for capturing a stack backtrace of an OS thread
This module contains the support necessary to capture a stack backtrace of a
running OS thread from the OS thread itself. The Backtrace
type supports
capturing a stack trace via the Backtrace::capture
and
Backtrace::force_capture
functions.
A backtrace is typically quite handy to attach to errors (e.g. types
implementing std::error::Error
) to get a causal chain of where an error
was generated.
Note: this module is unstable and is designed in RFC 2504, and you can learn more about its status in the tracking issue.
Accuracy
Backtraces are attempted to be as accurate as possible, but no guarantees are provided about the exact accuracy of a backtrace. Instruction pointers, symbol names, filenames, line numbers, etc, may all be incorrect when reported. Accuracy is attempted on a best-effort basis, however, and bugs are always welcome to indicate areas of improvement!
For most platforms a backtrace with a filename/line number requires that programs be compiled with debug information. Without debug information filenames/line numbers will not be reported.
Platform support
Not all platforms that libstd compiles for support capturing backtraces.
Some platforms simply do nothing when capturing a backtrace. To check
whether the platform supports capturing backtraces you can consult the
BacktraceStatus
enum as a result of Backtrace::status
.
Like above with accuracy platform support is done on a best effort basis. Sometimes libraries might not be available at runtime or something may go wrong which would cause a backtrace to not be captured. Please feel free to report issues with platforms where a backtrace cannot be captured though!
Environment Variables
The Backtrace::capture
function might not actually capture a backtrace by
default. Its behavior is governed by two environment variables:
-
RUST_LIB_BACKTRACE
- if this is set to0
thenBacktrace::capture
will never capture a backtrace. Any other value this is set to will enableBacktrace::capture
. -
RUST_BACKTRACE
- ifRUST_LIB_BACKTRACE
is not set, then this variable is consulted with the same rules ofRUST_LIB_BACKTRACE
. -
If neither of the above env vars are set, then
Backtrace::capture
will be disabled.
Capturing a backtrace can be a quite expensive runtime operation, so the environment variables allow either forcibly disabling this runtime performance hit or allow selectively enabling it in some programs.
Note that the Backtrace::force_capture
function can be used to ignore
these environment variables. Also note that the state of environment
variables is cached once the first backtrace is created, so altering
RUST_LIB_BACKTRACE
or RUST_BACKTRACE
at runtime might not actually change
how backtraces are captured.
Structs
A captured OS thread stack backtrace.
A single frame of a backtrace.
Enums
The current status of a backtrace, indicating whether it was captured or whether it is empty for some other reason.