Module tracing

This module provides tools for annotating functions such that calls are traced. That means that whenever the function is called and when it returns, an entry is written to the specified trace.

Usually, that trace will be a static variable with interior mutability. If in doubt, define it something like this in the library/application code:

In this example we use cfg and cfg_attr to ensure that the tracing only runs during testing. In many cases one might want to also restrict this to only trace if a certain feature is enabled. This can be done using the same mechanism.

#[cfg(test)]
static TRACE: LazyLock<MutexTrace<&'static str, Instant>> =
    LazyLock::new(|| MutexTrace::default());

The MutexTrace can be defined and used as a static variable without unsafe, but, depending on the setting, my introduce too much overhead. Any type that implements Trace works.

Then, annotate a function like this:

// trace this function into `TRACE` if we are running the tests
#[cfg_attr(test, trace_span("my_app_fun", TRACE))]
fn my_app_function() {
  // ... some long-running code ...
}

The macro is called trace_span because it traces a start and end, identified by a label. The type of the label can be chosen generically, here it is &'static str. There also are on-the-fly tracing facilities.

After the code in question ran, the trace can be inspected. Due to the use of interior mutability, there is no generic way to get a reference to the inner slice; therefore, it is easiest to just clone it. We expect that this already happens in test code, so we don’t add the #[cfg(test)] here.

// make sure the trait is in scope
use libcrux_test_utils::tracing::Trace as _;

println!("{:?}", TRACE.clone().report());

Structs

MutexTrace

An implementation of Trace using a Mutex for interior mutability.

RefCellTrace

An implementation of Trace using a RefCell for interior mutability. Note that it is unsafe to use RefCell in static variables.

SpanHandle

This type emits a EventType::SpanClose event on drop.

TraceEvent

A trace event.

Enums

EventType

The type of the event

Traits

TimeStamp

Describes types that can be used for timestamping. This allows using the tracing facilities in no_std environments, where std::time::Instant is not available.

Trace

This trait describes a trace that is behind some sort of interior mutability mechanism. It can log trace events and later make these available. This is usually an argument to the trace_span function attribute macro in `libcrux-macros``, but it can also be called manually.

Attribute Macros

trace_span

Emits span events (of types EventType::SpanOpen and EventType::SpanClose) with the provided label into the provided trace. Requires that the caller depends on the libcrux-test-utils crate.