Struct TraceSession 

pub struct TraceSession { /* private fields */ }

Streaming trace session writing TensorFlow-Profiler-style span JSONL.

Implementations

impl TraceSession

pub fn open(path: impl AsRef<Path>, run: ProfileRun) -> Result<Self>

Open a trace and own its single root span until Self::finish.

pub fn begin_span( &self, name: impl Into<String>, kind: SpanKind, ) -> SpanGuard<'_>

Begin a nested span; parent is the top of the session span stack (TF Profiler call tree).

pub fn begin_measurement(&self, name: impl Into<String>) -> SpanGuard<'_>

Begin the single caller-controlled region used for total-time comparisons.

pub fn begin_step_span( &self, name: impl Into<String>, step: ExecutionStep, kind: SpanKind, ) -> SpanGuard<'_>

Begin a span tagged with a PyTorch-style training step (forward / backward / optimizer).

pub fn record_completed_host_span( &self, name: impl Into<String>, kind: SpanKind, start_ns: u64, duration_ns: u64, ) -> Result<SpanId>

Record already-completed host work without changing the live span stack.

start_ns is a monotonic offset from this session’s start and duration_ns must be positive. The interval must have completed before this call. The closed span is attached directly to the session root, so it may overlap live nested spans without implying a synchronous parent/child call relationship.

pub fn elapsed_ns(&self) -> u64

pub fn host_timestamp_ns(&self, instant: Instant) -> Result<u64>

Convert an Instant from this process into this trace session’s monotonic nanosecond clock without an independently sampled anchor.

pub fn record_op(&self, span_id: SpanId, op: OpRecord<'_>) -> Result<()>

Record a timed op observation attached to span_id.

pub fn record_tensor( &self, span_id: SpanId, tensor: TensorRecord<'_>, ) -> Result<()>

Record tensor metadata. Logical allocation lifetimes require explicit memory events.

pub fn record_scalar( &self, span_id: SpanId, label: &str, value: f64, ) -> Result<()>

Record one application-computed scalar observation (loss term, gate value, clip fraction, cosine, …) already available on the host.

No device reductions or readbacks are triggered; the value is stored as a single-element labeled statistic on the tensor-stats plane, so series and comparison tooling treat it like any other labeled mechanism observation. The evidence is observational; it never claims causal attribution.

pub fn record_tensor_stats( &self, span_id: SpanId, label: &str, tensor: &Tensor, ) -> Result<()>

Record device-reduced numerical statistics for a caller-labeled Candle tensor.

pub fn record_memory_alloc( &self, span_id: SpanId, mem: MemoryRecord<'_>, ) -> Result<()>

Record an explicit tensor allocation (TensorFlow memory timeline).

pub fn record_memory_free( &self, span_id: SpanId, mem: MemoryRecord<'_>, ) -> Result<()>

Record an explicit tensor deallocation.

pub fn record_device_memory(&self, sample: DeviceMemoryRecord<'_>) -> Result<()>

Record a device-level memory checkpoint (cudaMemGetInfo-style).

pub fn record_device_interval( &self, span_id: SpanId, interval: DeviceIntervalRecord<'_>, ) -> Result<()>

pub fn record_call_edge( &self, from: SpanId, to: SpanId, duration_ns: u64, ) -> Result<()>

pub fn record_data_edge(&self, from_tensor: &str, to_tensor: &str) -> Result<()>

pub fn record_gradient( &self, root: impl Into<String>, key: impl Into<String>, state: GradientState, norm: Option<f64>, ) -> Result<()>

Record one parameter gradient fact from a probe run.

Present requires a finite positive norm, Zero requires positive zero, and Missing or NonFinite require None. Exact-contract captures emit one event per (root, key).

pub fn flush(&self) -> Result<()>

pub fn finish(self) -> Result<PathBuf>

Close the owned root span, flush, and return the trace path.

pub fn finish_failed(self, reason: impl Into<String>) -> Result<PathBuf>

Finalize a diagnosable partial trace without presenting it as complete evidence.