# Module std::backtrace

1.65.0 · source ·
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.

### 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, any bug reports 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 std 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 to `0` then `Backtrace::capture` will never capture a backtrace. Any other value set will enable `Backtrace::capture`.

- `RUST_BACKTRACE` - if `RUST_LIB_BACKTRACE` is not set, then this variable is consulted with the same rules of `RUST_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

- BacktraceFrame Experimental
  A single frame of a backtrace.
- Backtrace
  A captured OS thread stack backtrace.

## Enums

- BacktraceStatus
  The current status of a backtrace, indicating whether it was captured or whether it is empty for some other reason.