pub struct Recorder<W: Write = BufWriter<File>> { /* private fields */ }Expand description
Records stack samples for one or more Linux processes.
Call finish to drain perf rings, flush sorted events, and
report write errors. Dropping a recorder only disables sampling on a
best-effort basis; queued samples may be lost and flush errors cannot be
reported from Drop.
Implementations§
Source§impl Recorder
impl Recorder
Sourcepub fn attach<P: AsRef<Path>>(
pid: Pid,
output: P,
attach_mode: AttachMode,
options: RecorderOptions,
) -> Result<Self>
pub fn attach<P: AsRef<Path>>( pid: Pid, output: P, attach_mode: AttachMode, options: RecorderOptions, ) -> Result<Self>
Attach to pid and start writing samples to output.
Use AttachMode::StopWhileAttaching for a process that is already
running. Use AttachMode::OnExec with
process::SuspendedLaunchedProcess when launching a new process.
§Errors
Returns an error when the options are invalid, perf cannot attach, the process cannot be inspected, or the spool file cannot be created.
Sourcepub fn tail(&mut self) -> Result<Tail>
pub fn tail(&mut self) -> Result<Tail>
Flush the spool and create an incremental reader that shares exact module images still held by this recorder’s bounded image cache.
A recorder can create one live tail. Continue polling and flushing the
recorder, then call crate::Tail::poll to consume newly visible
batches. Build the symbolizer through crate::Tail::symbolizer and
update it before resolving each batch.
§Errors
Returns an invalid-input error after a tail has already been created. Returns an I/O error when the spool cannot be flushed, cloned, or read.
Source§impl<W: Write> Recorder<W>
impl<W: Write> Recorder<W>
Sourcepub fn attach_with_writer(
pid: Pid,
output: W,
attach_mode: AttachMode,
options: RecorderOptions,
) -> Result<Self>
pub fn attach_with_writer( pid: Pid, output: W, attach_mode: AttachMode, options: RecorderOptions, ) -> Result<Self>
Attach to pid and write the spool to a caller-owned writer.
The writer is used through static dispatch. Passing &mut W lets the
caller recover the completed bytes after Self::finish consumes the
recorder.
§Errors
Returns an error when the options are invalid, perf cannot attach, the process cannot be inspected, or the writer rejects the spool header.
Sourcepub fn poll(&mut self, timeout: Duration) -> Result<PollSummary>
pub fn poll(&mut self, timeout: Duration) -> Result<PollSummary>
Wait for data for at most timeout, then drain every ready event.
§Errors
Returns an error when polling perf, decoding events, unwinding a stack, or writing a spool record fails.
Sourcepub fn attach_process(
&mut self,
pid: Pid,
attach_mode: AttachMode,
) -> Result<AttachOutcome>
pub fn attach_process( &mut self, pid: Pid, attach_mode: AttachMode, ) -> Result<AttachOutcome>
Add another process to this recording.
§Errors
Returns an error when perf cannot attach, process metadata cannot be read, or the spool cannot record the new mappings.
Sourcepub fn refresh_threads(&mut self, pid: Pid) -> Result<RefreshOutcome>
pub fn refresh_threads(&mut self, pid: Pid) -> Result<RefreshOutcome>
Discover newly-created threads for pid when needed.
§Errors
Returns ErrorKind::InvalidInput when
pid is not attached, or an I/O error when thread discovery fails.
Sourcepub fn enable(&mut self) -> Result<()>
pub fn enable(&mut self) -> Result<()>
Enable sampling for all attached processes.
§Errors
Returns the first perf-event enable or process-resume failure. When both fail, the enable failure remains primary and the resume failure is included as cleanup context.
Sourcepub fn flush(&mut self) -> Result<()>
pub fn flush(&mut self) -> Result<()>
Drain all collected events, force loss bookkeeping and recovery, then flush the spool writer. Sampling and lifecycle discovery remain active.
When loss has made lifecycle state uncertain, this call can perform an
expensive reconciliation pass over tracked processes and /proc,
discover descendants, rebuild module state, and open missing perf
events before it flushes the writer.
§Errors
Returns an event-processing or writer error.
Sourcepub fn has_pending_events(&self) -> bool
pub fn has_pending_events(&self) -> bool
Return whether userspace has queued events or Self::poll observed a
readable perf buffer.
Sourcepub fn summary(&self) -> RecordingSummary
pub fn summary(&self) -> RecordingSummary
Return a snapshot of the current counters.
Sourcepub fn process_is_active(&mut self, pid: Pid) -> Result<bool>
pub fn process_is_active(&mut self, pid: Pid) -> Result<bool>
Return whether pid is still believed to be alive.
§Errors
Returns an I/O error when process state cannot be checked.
Sourcepub fn has_active_processes_except(&mut self, pid: Pid) -> Result<bool>
pub fn has_active_processes_except(&mut self, pid: Pid) -> Result<bool>
Return whether any active process other than pid remains.
§Errors
Returns an error when process state cannot be inspected. Inspection failures are never treated as an alive or dead result.
Sourcepub fn active_process_count(&mut self) -> Result<usize>
pub fn active_process_count(&mut self) -> Result<usize>
Return the number of processes still believed to be alive.
§Errors
Returns an error when any tracked process cannot be inspected.
Sourcepub fn finish(self) -> Result<RecordingSummary>
pub fn finish(self) -> Result<RecordingSummary>
Flush the spool file and return the final counters.
§Errors
Returns the first disable, drain, or flush error. Later failures are retained as cleanup context, and flushing is attempted in every case.