[][src]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 three files:

  1. A .events file which contains all of the traced events.
  2. A .string_data file which contains all the strings referenced by events.
  3. A .string_index file which maps StringId values to offsets into the .string_data file.

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.

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

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

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

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_INSTANT_TIMESTAMP

The max instant timestamp we can represent with the 48 bits available.

MAX_INTERVAL_TIMESTAMP

The max interval timestamp we can represent with the 48 bits available. The highest value is reserved for the INSTANT_TIMESTAMP_MARKER.

Functions

split_streams

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