diff --git a/Cargo.toml b/Cargo.toml index a061004..1414e0f 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -25,6 +25,11 @@ repository = "https://github.com/tisonkun/logforth" rust-version = "1.71.0" version = "0.7.2" +categories = [ + "development-tools::debugging", +] +keywords = ["logging", "log", "opentelemetry", "fastrace"] + [package.metadata.docs.rs] all-features = true rustdoc-args = ["--cfg", "docs"] diff --git a/src/append/rolling_file/non_blocking.rs b/src/append/rolling_file/non_blocking.rs index b826e9d..0508e39 100644 --- a/src/append/rolling_file/non_blocking.rs +++ b/src/append/rolling_file/non_blocking.rs @@ -25,6 +25,19 @@ use crossbeam_channel::Sender; use crate::append::rolling_file::worker::Worker; use crate::append::rolling_file::Message; +/// A guard that flushes log records associated to a [`NonBlocking`] on a drop. +/// +/// Writing to a [`NonBlocking`] writer will **not** immediately write the log record to the +/// underlying output. Instead, the log record will be written by a dedicated logging thread at +/// some later point. To increase throughput, the non-blocking writer will flush to the underlying +/// output on a periodic basis rather than every time a log record is written. This means that if +/// the program terminates abruptly (such as through an uncaught `panic` or a `std::process::exit`), +/// some log records may not be written. +/// +/// Since logs near a crash are often necessary for diagnosing the failure, `WorkerGuard` provides a +/// mechanism to ensure that _all_ buffered logs are flushed to their output. `WorkerGuard` should +/// be assigned in the `main` function or whatever the entrypoint of the program is. This will +/// ensure that the guard will be dropped during an unwinding or when `main` exits successfully. #[derive(Debug)] pub struct WorkerGuard { _guard: Option>, @@ -72,6 +85,7 @@ impl Drop for WorkerGuard { } } +/// A non-blocking, off-thread writer. #[derive(Clone, Debug)] pub struct NonBlocking { sender: Sender, @@ -110,6 +124,7 @@ impl NonBlocking { } } +/// A builder for [`NonBlocking`]. #[derive(Debug)] pub struct NonBlockingBuilder { thread_name: String, diff --git a/src/append/rolling_file/rolling.rs b/src/append/rolling_file/rolling.rs index e26af13..a8c2cd4 100644 --- a/src/append/rolling_file/rolling.rs +++ b/src/append/rolling_file/rolling.rs @@ -30,6 +30,7 @@ use time::Duration; use time::OffsetDateTime; use time::Time; +/// A file writer with the ability to rotate log files at a fixed schedule. #[derive(Debug)] pub struct RollingFileWriter { state: State, @@ -63,6 +64,7 @@ impl Write for RollingFileWriter { } } +/// A builder for [`RollingFileWriter`]. #[derive(Debug)] pub struct RollingFileWriterBuilder { rotation: Rotation, @@ -313,12 +315,18 @@ fn open_file(dir: &Path, filename: &str) -> anyhow::Result { .context("failed to create log file") } +/// Defines a fixed period for rolling of a log file. #[derive(Clone, Eq, PartialEq, Debug)] pub enum Rotation { + /// Minutely Rotation Minutely, + /// Hourly Rotation Hourly, + /// Daily Rotation Daily, + /// No Rotation Never, + // TODO(tisonkun): consider support rotating on file size exceeding a threshold. } impl Rotation {