Struct FileSink 

pub struct FileSink<F: Format> { /* private fields */ }

Available on crate feature std only.

Writes records to a file through a write buffer.

Durability

Records are buffered in memory (8 KiB by default) and reach the operating system when the buffer fills or the sink is flushed. A flush happens:

• after every record at or above the logger’s flush level (by default Level::Error, see LoggerBuilder::flush_on);
• on crate::Logger::flush and crate::Logger::shutdown;
• when a crate::FlushGuard is dropped;
• when the last clone of the crate::Logger is dropped.

Anything still buffered is lost if the process ends without one of those happening: std::process::abort, panic = "abort" without crate::global::install_panic_hook, a fatal signal, std::process::exit (which skips destructors), or simply returning from main while the logger lives in a static (statics are never dropped). Keep the crate::FlushGuard returned by crate::init alive in main, call crate::Logger::shutdown before process::exit, or build the sink with FileSinkBuilder::buffer_capacity(0) to write every record through immediately.

Flushing hands data to the OS, which survives a crash of this process but not a power loss or kernel crash. Enable FileSinkBuilder::sync_on_flush to also fsync (sync_data) on every flush.

Examples

use log_io::format::JsonFormat;
use log_io::sink::FileSink;
use log_io::{Level, Logger};

let sink = FileSink::builder("app.jsonl", JsonFormat::new())
    .append(true)
    .sync_on_flush(true)
    .open()?;
let logger = Logger::builder().level(Level::Info).with_sink(sink).build();
log_io::error!(logger, "disk almost full"); // flushed and synced before returning

Implementations

impl<F: Format> FileSink<F>

pub fn append<P: AsRef<Path>>(path: P, format: F) -> Result<Self>

Open path for appending (creating it if needed) with default options.

Errors

Returns Error::Io if the file cannot be opened or created.

pub fn create<P: AsRef<Path>>(path: P, format: F) -> Result<Self>

Open path for writing, truncating any existing content.

The file is truncated only after the checks described under FileSinkBuilder::follow_symlinks pass, so a symbolic link at path never truncates the file it points to.

Errors

Returns Error::Io if the file cannot be opened or created, or if path is a symbolic link or not a regular file.

pub fn builder<P: AsRef<Path>>(path: P, format: F) -> FileSinkBuilder<F>

Start configuring a file sink. Defaults: append, 8 KiB buffer, no fsync, mode 0o600 for a new file (Unix), symbolic links refused.

Trait Implementations

impl<F: Format + Debug> Debug for FileSink<F>

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

Formats the value using the given formatter.

impl<F: Format> Sink for FileSink<F>

fn write_record(&self, record: &Record<'_>) -> Result<()>

Serialize and deliver one record.

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

Push any buffered bytes to the destination (for files, to the operating system; see the sink’s own docs for fsync).

fn request_flush(&self) -> Result<()>

Flush triggered by a record at or above the logger’s flush level (see crate::LoggerBuilder::flush_on).

fn shutdown(&self) -> Result<()>

Flush and release background resources. Called by crate::Logger::shutdown, by a crate::FlushGuard on drop, and when the last clone of a crate::Logger is dropped.