Module trace 

Trace capture for performance analysis.

Provides a simple start/stop API for capturing tracing-based spans emitted by HAL crates into Chrome JSON trace files viewable at https://ui.perfetto.dev/.

Design

The HAL library crates (edgefirst-decoder, edgefirst-image) emit tracing::trace_span! spans on hot paths. These have near-zero overhead when no subscriber is active (a single relaxed atomic load per span site).

This module installs a process-wide subscriber consisting of a Chrome trace layer writing spans to a JSON file for Perfetto. Existing log::* output (via env_logger) continues independently to stderr.

The subscriber is installed once on the first call to start_tracing. Only one trace capture session is supported per process lifetime (this is a limitation of Rust’s global subscriber model and is acceptable for profiling workflows where a single trace per run is the norm).

Usage from Rust

use edgefirst_hal::trace::{start_tracing, stop_tracing};

start_tracing("/tmp/trace.json").expect("start tracing");
// ... run inference pipeline ...
stop_tracing(); // flushes and closes the trace file

Usage from Python

import edgefirst_hal as hal

with hal.Tracing("/tmp/trace.json"):
    # ... run inference ...
    pass
# trace file is flushed on __exit__

Usage from C

#include "edgefirst_hal.h"
hal_start_tracing("/tmp/trace.json");
// ... run inference ...
hal_stop_tracing(); // flushes trace file

Enums

TracingError

Errors from tracing operations.

Functions

is_tracing_active

Returns true if a trace capture session is currently active.

start_tracing

Start trace capture, writing Chrome JSON to path.

stop_tracing

Stop trace capture, flushing all buffered spans to the output file.