Crate measureme

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:

• Profiler::alloc_string(): allocates a string and returns the StringId that refers to it

Re-exports

pub use crate::event_id::EventId;

pub use crate::event_id::EventIdBuilder;

pub use crate::stringtable::SerializableString;

pub use crate::stringtable::StringComponent;

pub use crate::stringtable::StringId;

pub use crate::stringtable::StringTableBuilder;

Modules

counters

Profiling counters and their implementation.

event_id

file_header

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.

rustc

This module contains functionality specific to to the measureme integration with rustc

stringtable

A string table implementation with a tree-like encoding.

Structs

Addr

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

DetachedTiming

Created by Profiler::start_recording_interval_event_detached. Must be passed to finish_recording_interval_event to record an “end” event.

Profiler

RawEvent

RawEvent is how events are stored on-disk. If you change this struct, make sure that you increment file_header::CURRENT_FILE_FORMAT_VERSION.

SerializationSink

SerializationSinkBuilder

TimingGuard

When dropped, this TimingGuard will record an “end” event in the Profiler it was created by.

Enums

PageTag

Constants

MAX_INTERVAL_VALUE

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

MAX_SINGLE_VALUE

The max value we can represent with the 48 bits available.

Functions

split_streams

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