Crate micrometer

Micrometer

Profiling for fast, high frequency events in multithreaded applications with low overhead

Important

By default every measure is a no-op, to measure and consume measures, enable the enable feature. This is done to allow libs to instrument their code without runitme costs if no one is using the measures.

Definitions

• Measurement: a measurement is the timing data gathered for a single event.
• Record: a record is the retrieval format for measurements. Records may be 1-to-1 with respects to measurements, however, if perforation is enabled (default), as measurements increase in numbers, a single record may be the aggregate of multiple measurements.
• Location: a location is a region of interest of the program. All measurements start from a location. Each measure is associated with the name of the location it originated from.
• Thread location: as micrometer is intended for multithreaded environments, each location may be relevant for multiple threads, the location in the context of a specific thread is referred to as thread location
• Span: a span is a guard object that measures the time between when it was created and when it was dropped (unless it was disarmed). Each span will produce one measurement
• Track: a track is the struct responsible of handling all measurements originating from a thread location. It is used to create spans or manually record the duration of an event.
• TrackPoint: while a track maps to the concept of thread location (as a single track can only be owned by one thread), a track point maps to the concept of location. The track point struct is a lazily allocated, thread local handle to multiple tracks that are associated with the same name. Usually, track points are used as static variables, using the get_or_init method to get the track for the active thread.

Examples

Measuring the duration of a loop

for _ in 0..100 {
    // Define a `TrackPoint` named "loop_duration", get (or init) the `Track` for the
    // current thread, then create a span and assign it to a new local variable called
    // `loop_duration`
    micrometer::span!(loop_duration);

    std::hint::black_box("do something");
    // `loop_duration` is automatically dropped recording the measure
}
// Print a summary of the measurements
micrometer::summary();

Measuring the duration of a loop, threaded

std::thread::scope(|s| {
    for t in 1..=4 {
        s.spawn(move || {
            for _ in 0..(10 * t) {
                micrometer::span!(); // Name automatically assigned to source file and line
                std::hint::black_box("do something");
            }
        });
    }
});
// Print a summary of the measurements
micrometer::summary();
// Print a summary of the measurements, aggregating measures for the same location
micrometer::summary_grouped();

Measuring the duration of an expression

// This works like the `dbg!` macro, allowing you to transparently wrap an expression:
// a span is created, the expression is executed, then the span is closed and the result
// of the expression is passed along
let a = micrometer::span!(5 * 5, "fives_sq");
let b = micrometer::span!(a * a); // Name automatically assigned to source file and line
assert_eq!(a, 25);
assert_eq!(b, 25 * 25);

Measuring a code segment

let a = 5;
micrometer::span!(guard, "a_sq");
let b = a * a;
drop(guard); // Measurement stops here
let c = b * a;

Macros

• span

Structs

• Record
  Single unit of measurement
• Registry
  Measurement registry, used to register new track points and collect results.
• Span
• Stats
• Track
  Component used to create and save measures
• TrackPoint
  Lazy, thread local track. Should be used as a static variable for each point of the program that needs to be measured.

Constants

• BUFFER_INIT_BYTES
  Minimum size fo the buffer in which measurements are stored
• PERFORATION_STEP
  When using perforation (default) consequent measures will be combined if the number of measures for a track point exceeds PERFORATION_STEP

Functions

• append_csv
  Append all measurements to a csv file
• global
  Get a reference to the global micrometer register
• save_csv
  Save all measurements to a csv file
• save_csv_uniform
  Save all measurements to a csv file. Measures will be uniformed in count to the largest granularity that has been measured for each location.
• start
  Force initialization of start time. If not called it will be automatically initialized when the first measurement is recorded
• summary
  Print a summary for all track points. Report measures with the same name, but different thread separately
• summary_grouped
  Print a summary for all track points. Group all measurements with the same name.