Struct Trace 

#[non_exhaustive]
pub struct Trace {
    pub incidents: Vec<Incident>,
    pub dropped_incidents: u64,
    pub schema_version: u32,
    pub progress: Option<Snapshot>,
    pub metadata: Vec<(String, String)>,
    pub spans: Vec<SpanRecord>,
    pub dropped_spans: u64,
    pub active_spans: usize,
    pub cancelled_at: Option<Duration>,
    pub observed_at: Option<Duration>,
    pub returned_at: Option<Duration>,
}

A finished run’s spans, optionally with its progress tree attached.

Fields (Non-exhaustive)

Non-exhaustive structs could have additional fields added in future. Therefore, non-exhaustive structs cannot be constructed in external crates using the traditional Struct { .. } syntax; cannot be matched against without a wildcard ..; and struct update syntax will not work.

incidents: Vec<Incident>

Bounded reporting-protocol incidents, independent from work outcomes.

dropped_incidents: u64

Incidents omitted because their separate retention budget was exhausted.

schema_version: u32

Version of the JSON format.

progress: Option<Snapshot>

The progress tree, attached with with_progress.

metadata: Vec<(String, String)>

Key/value pairs from Profiler::metadata.

spans: Vec<SpanRecord>

Retained finished spans, in the order they finished.

dropped_spans: u64

Finished spans beyond the profiler’s capacity.

active_spans: usize

Spans still running when the trace was taken.

cancelled_at: Option<Duration>

When cancellation was requested, if recorded.

observed_at: Option<Duration>

When an instrumented check first returned a stop error.

returned_at: Option<Duration>

When the operation returned, if recorded.

Implementations

impl Trace

pub fn diagnose(&self, options: &Options) -> Vec<Finding>

Analyze the retained spans and the attached progress tree, if any.

Rates are per span’s wall time, not exact intervals at one line. Report gaps need Profiler::set_report_timing on while recording. Callback findings need callback spans, which Profiler::measure_callback records around each callback.

impl Trace

pub fn with_progress(self, progress: Snapshot) -> Self

Attach the progress tree, usually a final snapshot taken after every worker joined.

pub fn overlap(&self, ids: &[SpanId]) -> Option<Overlap>

Measure how the given work spans overlapped.

Returns None for an empty, missing or repeated ID, a span that is not Work, a span with clock regressions, or a span together with one of its ancestors (which would count time twice).

pub fn cancellation_observation_latency(&self) -> Option<Duration>

Time from the cancellation request to the first check that saw it.

pub fn cancellation_return_latency(&self) -> Option<Duration>

Time from the cancellation request to the operation’s return, including stragglers, joins, and cleanup.

pub fn write_json(&self, out: &mut impl Write) -> Result

Write the trace as JSON.

Times are nanoseconds since the clock’s epoch, written as decimal strings so 64-bit values survive JavaScript. Labels are escaped. Later versions may add keys; readers should ignore keys they do not know.

Trait Implementations

impl Clone for Trace

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Trace

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Display for Trace

fn fmt(&self, out: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.