-Z instrument-xray option

[ilammy]

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 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

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 the xray_instr_map section
• -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-xray can 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 merge on either the MCP or the PR.
• 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.

[rustbot]

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.

cc @rust-lang/compiler @rust-lang/compiler-contributors

[nnethercote]

Presumably the -Z instrument-count mentions in the description should be -Z instrument-xray?

[estebank]

@rustbot second

[apiraino]

@rustbot label -final-comment-period +major-change-accepted