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.

There are two main parts to this library:

• Writing event trace files
• Reading event trace files

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_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 u64 id of the thread which is recording this event
• timestamp_kind: a TimestampKind which specifies how this event should be treated by measureme tooling

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
• Profiler::alloc_string_with_reserved_id(): allocates a string using the specified StringId. It is up to the caller to make sure the specified StringId hasn't already been used.

Reading event trace files

The main entry point for reading trace files is the ProfilingData struct.

To create a ProfilingData, call the ProfilingData::new() function and provide a Path with the directory and file name for the trace files.

To retrieve an Iterator of all of the events in the file, call the ProfilingData::iter() method.

To retrieve an Iterator of only matching start/stop events, call the ProfilingData::iter_matching_events() method.

Modules

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

Structs

Addr
Event
FileSerializationSink
MmapSerializationSink
Profiler
ProfilerFiles
ProfilingData
RawEvent
StringId	A StringId is used to identify a string in the StringTable.
StringRef
StringTable	Read-only version of the string table
StringTableBuilder	Write-only version of the string table
Timestamp
TimingGuard	When dropped, this TimingGuard will record an "end" event in the Profiler it was created by.

Enums

MatchingEvent
TimestampKind

Traits

SerializableString	Anything that implements SerializableString can be written to a StringTable.
SerializationSink