Module heph::trace[−][src]

Expand description

Tracing utilities.

Using the tracing facilities of Heph is a three step process.

  1. Enabling tracing.
  2. Creating trace events.
  3. Interpreting the trace output.

Enabling Tracing

Tracing is enabled by calling Setup::enable_tracing when setting up the runtime.

Creating Trace Events

The runtime already add its own trace events, e.g. when running actors, but users can also log events. Actors can log trace event using the Trace implementation for their context, i.e. actor::Context or SyncContext.

Calling start_trace will start timing an event by returning EventTiming. Next the actor should execute the action(s) it wants to trace, e.g. receiving a message.

After the actions have finished finish_trace should be called with the timing returned by start_trace. In addition to the timing it should also include a human readable description and optional attributes. The attributes are a slice of key-value pairs, where the key is a string and the value is of the type AttributeValue. AttributeValue supports most primitives types, compound types are not supported and should be split into multiple key-value pairs.

Nested trace events are supported, simply call start_trace (and finish_trace) twice. In the interpreting of the trace log events are parsed in such a way that parent-child relations become clear if trace events are created by the same actor.

Notes

You might notice that the start_trace doesn’t actually return EventTiming, but Option<EventTiming>, and finish_trace accepts Option<EventTiming>. This is to support the case when tracing is disabled. This makes it easier to leave the code in-place and don’t have to deal with #[cfg(is_tracing_enabled)] attributes etc. When tracing is disabled start_trace will return None and if None is passed to finish_trace it’s effectively a no-op.

Interpreting the trace output

Once a trace log is created its now time to interpret it. The Trace Format design document describes the layout of the trace, found in the doc directory of the repository.

However as it’s a binary format it can be hard to read. So tools are provided to convert into Chrome’s Trace Event Format, which can be viewed using Catapult. Example 8 “Runtime Tracing” shows a complete example of this.

Structs

EventTiming

Timing an event.

Traits

AttributeValue

The AttributeValue trait defines what kind of types are supported as attribute values in tracing.

Trace

Trace events.