Crate measureme

source ·
Expand description

This crate provides a library for high-performance event tracing which is used by the Rust compiler’s unstable -Z self-profile feature.

The output of a tracing session will be an .mm_profdata file containing a stream of events and a string table that allows to decode the StringIds in the event stream.

Writing event trace files

The main entry point for writing event trace files is the Profiler struct.

To create a Profiler, call the Profiler::new() function and provide a Path with the directory and file name for the trace files. Alternatively, call the Profiler::with_counter() function, to choose the Counter the profiler will use for events (whereas Profiler::new() defaults to wall-time).

For more information on available counters, see the counters module documentation.

To record an event, call the Profiler::record_instant_event() method, passing a few arguments:

  • event_kind: a StringId which assigns an arbitrary category to the event
  • event_id: a StringId which specifies the name of the event
  • thread_id: a u32 id of the thread which is recording this event

Alternatively, events can also be recorded via the Profiler::start_recording_interval_event() method. This method records a “start” event and returns a TimingGuard object that will automatically record the corresponding “end” event when it is dropped.

To create a StringId, call one of the string allocation methods:

Re-exports

Modules

  • Profiling counters and their implementation.
  • All binary files generated by measureme have a simple file header that consists of a 4 byte file magic string and a 4 byte little-endian version number.
  • This module contains functionality specific to to the measureme integration with rustc
  • A string table implementation with a tree-like encoding.

Structs

  • An address within a data stream. Each data stream has its own address space, i.e. the first piece of data written to the events stream will have Addr(0) and the first piece of data written to the string data stream will also have Addr(0).
  • Created by Profiler::start_recording_interval_event_detached. Must be passed to finish_recording_interval_event to record an “end” event.
  • RawEvent is how events are stored on-disk. If you change this struct, make sure that you increment file_header::CURRENT_FILE_FORMAT_VERSION.
  • When dropped, this TimingGuard will record an “end” event in the Profiler it was created by.

Enums

Constants

  • The max value we can represent with the 48 bits available. The highest two values are reserved for the INSTANT_MARKER and INTEGER_MARKER.
  • The max value we can represent with the 48 bits available.

Functions

  • This function reconstructs the individual data streams from their paged version.