Struct LogRingFile

pub struct LogRingFile {
    pub file_path: Box<Path>,
    pub level: Level,
    pub format: LogFormat,
    pub buf_size: i32,
}

Available on crate feature ringfile only.

The LogRingFile sink is a tool for debugging deadlock or race condition, when the problem cannot be reproduce with ordinary log (because disk I/O will slow down the execution and prevent the bug to occur).

Usage

Enable feature ringfile in your Cargo.toml.

Replace the log setup with the following in your test case:

(Set the level to Info or higher, to turn of other debugging logs.)

use captains_log::*;
recipe::ring_file("/tmp/ring.log", 512*1024*1024, Level::Info,
    signal_consts::SIGHUP).test().build().expect("log setup");

Then add some high-level log to critical path in the code, try to reproduce the problem, and reduce the amount of log if the bug not occur.

On start-up, it will create a limited-size ring-buffer-like memory. The log content will be hold within memory but not written to disk, old logs will be overwritten by new ones. Until specified signal arrives, the last part of log message will be dumped to file, in time order.

Once your program hangs up completely , find your process pid and send a signal to it.

kill -SIGHUP <pid>

There will be messages print to stdout:

RingFile: start dumping
RingFile: dump complete

Then you can inspect your log content on disk (for this example /tmp/ring.log).

The backend is provided by RingFile crate. To ensure low latency, the buffer is protected by a spinlock instead of a mutex. After the program hangs, because no more message will be written to the buffer, log content can be safely copied from the buffer area to disk.

Be aware that it did not use mlock to prevent memory being swapping. (Swapping might make the code slow to prevent bug reproduction). When your memory is not enough, use a smaller buf_size and turn off the swap with swapoff -a.

A real-life debugging story can be found on https://github.com/frostyplanet/crossfire-rs/issues/24.

Fields

file_path: Box<Path>

level: Level

format: LogFormat

buf_size: i32

0 < buf_size < i32::MAX

Implementations

impl LogRingFile

pub fn new<P: Into<PathBuf>>( file_path: P, buf_size: i32, max_level: Level, format: LogFormat, ) -> Self

Trait Implementations

impl Hash for LogRingFile

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl SinkConfigTrait for LogRingFile

fn get_level(&self) -> Level

get max log level of the sink

fn get_file_path(&self) -> Option<Box<Path>>

Only file sink has path

fn write_hash(&self, hasher: &mut Box<dyn Hasher>)

Calculate hash for config comparison