Struct SegmentWriter 

pub struct SegmentWriter<Mode: BufferMode = Disk> { /* private fields */ }

A writer that rotates trace segments to bound resource usage and time. Generic over backend: use DiskBuffer (files) or MemoryBuffer.

Rotation triggers when either condition is met:

• max_file_size: the active segment exceeds this many bytes
• rotation_period: this much monotonic time has elapsed since the writer (or the previous rotation) started (default: 1 minute)

Prefer time-based rotation. Time-based rotation is coordinated with the flush loop: thread-local buffers are drained before the segment is sealed, so each segment contains events from a clean, non-overlapping time window. Size-based rotation fires immediately when the threshold is crossed and does not drain thread-local buffers, so segments may contain events that overlap in time. Set max_file_size large enough that time-based rotation fires first under normal conditions (e.g. 100 MB or more). Size-based rotation then acts as a safety valve for unexpected data bursts. When using DiskBuffer::builder without specifying max_file_size, it defaults to min(100 MiB, max_total_size / 4) on disk.

max_total_size is the retention budget across closed segments. The oldest segments are dropped once the total exceeds this budget.

The trace lives in a directory (dir); disk segments are named {dir}/{stem}.0.bin, {dir}/{stem}.1.bin, etc., each a self-contained trace with its own header. Rotating writers use the stem trace; single_file takes the stem from the given file name.

Implementations

impl SegmentWriter<Disk>

pub fn set_namespace(&mut self, boot_id: String, lock: File)

Set the namespace for this writer:

• boot_id: The boot id for the namespace.
• lock: The lock file for the namespace.

pub fn single_file(path: impl Into<PathBuf>) -> Result<Self>

Create a writer that writes to a single file with no rotation or eviction. The segment is written to {stem}.0.bin.active while active, then sealed to {stem}.0.bin on finalize. The background worker will symbolize and gzip it to {stem}.0.bin.gz.

Note: This API does not allow the ability to provide custom segment metadata. Time-based rotation is disabled.

pub fn builder<I1>() -> DiskBufferBuilder<I1>

where I1: Into<PathBuf>,

Create a DiskBufferBuilder for advanced configuration.

When max_file_size is omitted, it defaults to min(100 MiB, max_total_size / 4).

impl SegmentWriter<Memory>

pub fn new(max_total_size: u64) -> Result<Self>

Create an in-memory writer with a total byte budget. Segments live in process heap instead of files. Auto-picks a reasonable segment size, use builder for explicit control.

Same rotation semantics as the disk path. Errors when max_total_size == 0.

pub fn builder() -> MemoryBufferBuilder

Builder for in-memory writer configuration.

impl<M: BufferMode> SegmentWriter<M>

pub fn boot_id(&self) -> Option<&str>

Per-process boot identifier, if namespace isolation is active. This is the name of the trace_dir subdirectory.

pub fn trace_dir(&self) -> &Path

Directory this writer’s trace segments live in. When namespace isolation is active this is the per-process {configured_dir}/{boot_id}/ subdirectory; otherwise it is the configured directory directly. Use this to locate the segment files on disk.

pub fn trace_stem(&self) -> &str

Segment filename stem, e.g. trace for trace.0.bin.

pub fn current_active_path(&self) -> &Path

The path of the currently active (being-written) segment file.

impl<M: BufferMode> SegmentWriter<M>

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

Flush buffered data to the underlying storage.

pub fn update_segment_metadata( &mut self, entries: impl IntoIterator<Item = (String, String)>, )

Merge the segment metadata entries written into the next rotated segment.

Accepts any iterator so callers can drain a reused buffer (retaining its capacity) instead of handing over an owned Vec. A Vec still works.

pub fn finalize(&mut self) -> Result<()>

Finalize the writer: flush, seal the active segment, and prevent further writes. Terminal — the writer is inert afterward.

Trait Implementations

impl<M: BufferMode> Debug for SegmentWriter<M>

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

Formats the value using the given formatter.

impl<M: BufferMode> Drop for SegmentWriter<M>

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.