Module std::backtrace

source · [−]
🔬 This is a nightly-only experimental API. (backtrace #53487)
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 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 might not actually change how backtraces are captured.

Structs

BacktraceExperimental

A captured OS thread stack backtrace.

BacktraceFrameExperimental

A single frame of a backtrace.

Enums

BacktraceStatusExperimental

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