Crate usdt[−][src]

Expose USDT probe points from Rust programs.

This crate provides methods for compiling definitions of DTrace probes into Rust code, allowing rich, low-overhead instrumentation of Rust programs.

Users define a provider, with one or more probe functions, in the D language. For example:

provider test {
    probe start(uint8_t);
    probe stop(char*, uint8_t);
};

Assuming the above is in a file called "test.d", this may be compiled into Rust code with:

usdt::dtrace_provider!("test.d");

This procedural macro will return a Rust macro for each probe defined in the provider. For example, one may then call the start probe via:

let x: u8 = 0;
test_start!(|| x);

Note that the probe macro is called with a closure which returns the actual arguments. There are two reasons for this. First, it makes clear that the probe may not be evaluated if it is not enabled; the arguments should not include function calls which are relied upon for their side-effects, for example. Secondly, it is more efficient. As the lambda is only called if the probe is actually enabled, this allows passing arguments to the probe that are potentially expensive to construct. However, this cost will only be incurred if the probe is actually enabled.

These probes must be registered with the DTrace kernel module, which is done with the usdt::register_probes() function. At this point, the probes should be visible from the dtrace(1) command-line tool, and can be enabled or acted upon like any other probe.

See the probe_test_macro and probe_test_build crates for detailed working examples showing how the probes may be defined, included, and used.

Notes

Because the probes are defined as macros, they should be included at the crate root, before any modules with use them are declared. Additionally, the register_probes() function, which must be called for the probes to work, should be placed as soon as possible in a program’s lifetime, ideally at the top of main().

Crate usdt[−][src]

Notes

Macros

Structs

Enums

Functions