Struct FileSetBuilder

pub struct FileSetBuilder { /* private fields */ }

A builder for a FileSet.

Use set or set_with_writer to begin a FileSetBuilder.

The FileSetBuilder has configuration options for managing the number and size of log files.

Once configured, call FileSetBuilder::spawn to complete the builder, passing the resulting FileSet to emit::Setup::emit_to.

Implementations

impl FileSetBuilder

pub fn new(file_set: impl Into<PathBuf>) -> Self

Create a new FileSetBuilder using the default newline-delimited JSON format.

The builder will use file_set as its template for naming log files. See the crate root documentation for details on how this argument is interpreted.

It will use the other following defaults:

• Roll by hour.
• 32 max files.
• 1GiB max file size.

pub fn new_with_writer( file_set: impl Into<PathBuf>, writer: impl Fn(&mut FileBuf, &Event<'_, &dyn ErasedProps>) -> Result<()> + Send + Sync + 'static, separator: &'static [u8], ) -> Self

Create a builder for a FileSet.

The builder will use file_set as its template for naming log files. See the crate root documentation for details on how this argument is interpreted.

The writer is used to format incoming emit::Events into their on-disk format. If formatting fails then the event will be discarded.

The writer may finish each event with the separator. If it doesn’t, then it will be added automatically.

It will use the other following defaults:

• Roll by hour.
• 32 max files.
• 1GiB max file size.

pub fn roll_by_day(self) -> Self

Create rolling log files based on the calendar day of when they’re written to.

pub fn roll_by_hour(self) -> Self

Create rolling log files based on the calendar day and hour of when they’re written to.

pub fn roll_by_minute(self) -> Self

Create rolling log files based on the calendar day, hour, and minute of when they’re written to.

pub fn max_files(self, max_files: usize) -> Self

The maximum number of log files to keep.

Files are deleted from oldest first whenever a new file is created. Older files are determined based on the time period they belong to.

pub fn max_file_size_bytes(self, max_file_size_bytes: usize) -> Self

The maximum size of a file before new writes will roll over to a new one.

The same time period can contain multiple log files. More recently created log files will sort ahead of older ones.

pub fn reuse_files(self, reuse_files: bool) -> Self

Whether to re-use log files when first attempting to write to them.

This method can be used for applications that are started a lot and may result in lots of active log files.

Before writing new events to the log file, it will have the configured separator defensively written to it. This ensures any previous partial write doesn’t corrupt any new writes.

pub fn writer( self, writer: impl Fn(&mut FileBuf, &Event<'_, &dyn ErasedProps>) -> Result<()> + Send + Sync + 'static, separator: &'static [u8], ) -> Self

Specify a writer for incoming emit::Events.

The writer is used to format incoming emit::Events into their on-disk format. If formatting fails then the event will be discarded.

The writer may finish each event with the separator. If it doesn’t, then it will be added automatically.

pub fn spawn(self) -> FileSet

Complete the builder, returning a FileSet to pass to emit::Setup::emit_to.

If the file set configuration is invalid this method won’t fail or panic, it will discard any events emitted to it. In these cases it will log to emit::runtime::internal and increment the configuration_failed metric on FileSet::metric_source. See the Troubleshooting section of the crate root docs for more details.