Struct Tail 

pub struct Tail { /* private fields */ }

Incremental reader for an append-only StackPulse spool.

Each complete record is decoded once. A record cut off at the visible end of the file is retried after the writer appends the rest of it. Definitions are retained for the life of the reader, while sample storage is bounded and reused between polls.

Implementations

impl Tail

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

Open a growing spool and decode its current complete prefix.

The writer must flush the spool header before this call.

Errors

Returns a corrupt-spool error for malformed input, or an I/O category when the file cannot be opened or mapped.

pub fn symbolizer(&self) -> SymbolizerBuilder<'_>

Configure a symbolizer bound to this growing spool.

Call crate::Symbolizer::update with every batch before resolving that batch’s stacks.

pub fn poll(&mut self) -> Result<TailBatch<'_>>

Decode records appended since the previous poll.

The first poll returns samples that were already complete when the tail was opened. Later polls return only newly appended samples.

The returned batch borrows storage owned by this reader. A poll with no appended records performs no allocation once the reader is warm. Call TailBatch::has_more to determine whether another complete batch may already be visible. It does not indicate whether the writer is still active.

Errors

Returns a corrupt-spool error for malformed appended data. Shrinking the opened file is rejected because tailing supports append only.

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

Release filesystem blocks occupied by complete records already decoded.

This makes the spool disposable: it remains usable by this tail and its writer, but can no longer be reopened or replayed from the beginning. This is supported by tails created with crate::Recorder::tail; a tail opened with Tail::open holds a read-only file descriptor.

Errors

Returns an I/O error when the filesystem does not support hole punching or the tail does not hold a writable file descriptor.

pub fn start_timestamp_us(&self) -> Option<u64>

Return the profile timeline anchor in microseconds.

pub fn sample_interval_us(&self) -> Option<u64>

Return the optional sample interval metadata in microseconds.

Trait Implementations

impl Debug for Tail

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

Formats the value using the given formatter.