instrument_xray - The Rust Unstable Book

## Keyboard shortcuts

Press `←` or `→` to navigate between chapters

Press `S` or `/` to search in the book

Press `?` to show this help

Press `Esc` to hide this help

# `instrument-xray`

The tracking issue for this feature is: #102921.

Enable generation of NOP sleds for XRay function tracing instrumentation. For more information on XRay, read LLVM documentation, and/or the XRay whitepaper.

Set the `-Z instrument-xray` compiler flag in order to enable XRay instrumentation.

- `-Z instrument-xray` – use the default settings
- `-Z instrument-xray=skip-exit` – configure a custom setting
- `-Z instrument-xray=ignore-loops,instruction-threshold=300` – multiple settings separated by commas

Supported options:

- `always` – force instrumentation of all functions
- `never` – do no instrument any functions
- `ignore-loops` – ignore presence of loops, instrument functions based only on instruction count
- `instruction-threshold=10` – set a different instruction threshold for instrumentation
- `skip-entry` – do no instrument function entry
- `skip-exit` – do no instrument function exit

The default settings are:

- instrument both entry & exit from functions
- instrument functions with at least 200 instructions, or containing a non-trivial loop

Note that `-Z instrument-xray` only enables generation of NOP sleds which on their own don’t do anything useful. In order to actually trace the functions, you will need to link a separate runtime library of your choice, such as Clang’s XRay Runtime Library.