Description
Proposal
Add support for XRay instrumentation, enabled by the -Z instrument-xray option, later to be stabilized subject to bikeshedding.
Motivation
XRay tracing is an alternative to existing -Z instrument-mcount instrumentation. It is superior in capabilities and flexibility, while keeping minimal performance impact when inactive.
Design
See a post on internals for an infodump, here is a summary.
Command line option
Introduce a flag with options:
-Z instrument-xray– enable implicit defaults-Z instrument-xray={on|off|yes|no}– explicit enable/disable-Z instrument-xray=<option>– enable with an optional setting-Z instrument-xray=<option1>,<option2>...– enable with multiple comma-separated settings
where supported options are:
always– force instrumentation of all functionsnever– do no instrument any functionsignore-loops– ignore presence of loops, instrument functions based only on instruction countinstruction-threshold=10– set a different instruction threshold for instrumentationskip-entry– do no instrument function entryskip-exit– do no instrument function exit
Codegen support
If -Z instrument-xray is enabled, codegen annotates emitted functions with attributes as appropriate:
"xray-instruction-threshold"="100""function-instrument"="xray-always"- etc.
LLVM does the rest, scheduling the appropriate pass which inserts instrumentation into emitted machine code, notes down instrumented locations in xray_instr_map section, etc.
Instrumented binaries are expected to link with an suitable runtime library of their choice which will make use of the instrumentation.
Language changes
Aside from the codegen option, introduce a new attribute #[instrument::xray(...)] allowing to fine-tune instrumented functions, at individual crate/module/impl/function/etc. level.
The attribute would mirror options available on the command line, for example:
#[instrument::xray(ignore_loops)]
mod my_loops {
fn do_things() {
loop {
// ...
}
}
#[instrument::xray(never)]
fn performance_critical() {
// ...
}
}Detailed design and interaction with language items to be hashed out separately, via the RFC process, I guess.
Prior art
See options provided by Clang for XRay control:
-fxray-instrument– enable instrumentation-fno-xray-function-index– inhibit thexray_instr_mapsection-fxray-attr-list– pass a file with attribute overrides-fxray-function-groups– instrument a random sample of functions-fxray-ignore-loops– control which functions to instrument-fxray-instruction-threshold=N-fxray-instrumentation-bundle={all|none|function-entry|function-exit|function|custom}
Some of those might turn out to be useful, so I'd like to reserve -Z instrument-xray-... namespace for future extensions.
Alternatives
-
Instead of a unified multi-option:
-Z insturment-xray=<option>...provide separate ones, like Clang does:-Z instrument-xray,-Z instrument-xray-ignore-loops.We have a benefit of not having to maintain compatibility with previously existing flags, thus the new option can be conveniently namespaced.
-Z instrument-xraycan be passed several times, enabling settings one by one.
Mentors or Reviewers
no idea, please send help
Process
The main points of the Major Change Process are as follows:
- File an issue describing the proposal.
- A compiler team member or contributor who is knowledgeable in the area can second by writing
@rustbot second.- Finding a "second" suffices for internal changes. If however, you are proposing a new public-facing feature, such as a
-C flag, then full team check-off is required. - Compiler team members can initiate a check-off via
@rfcbot fcp mergeon either the MCP or the PR.
- Finding a "second" suffices for internal changes. If however, you are proposing a new public-facing feature, such as a
- Once an MCP is seconded, the Final Comment Period begins. If no objections are raised after 10 days, the MCP is considered approved.
You can read more about Major Change Proposals on forge.
Comments
This issue is not meant to be used for technical discussion. There is a Zulip stream for that. Use this issue to leave procedural comments, such as volunteering to review, indicating that you second the proposal (or third, etc), or raising a concern that you would like to be addressed.