# Module std::backtrace[−][src]

🔬 This is a nightly-only experimental API. (`backtrace` #53487)

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 may 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 may 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 this is set to 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 may not actually change how backtraces are captured.

## Structs

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

## Enums

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