From d05c18bb9d818d45ed2e229590d279eaa096b0ca Mon Sep 17 00:00:00 2001 From: estk Date: Tue, 10 Mar 2020 18:12:50 -0700 Subject: [PATCH] Release prep (#145) * Update changelog, simplify docs * More docs cleanup * Update CHANGELOG.md --- CHANGELOG.md | 19 ++++++++ .../policy/compound/roll/fixed_window.rs | 13 +++--- src/lib.rs | 45 ++++++++++--------- 3 files changed, 50 insertions(+), 27 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 964e1670..747642e7 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,6 +8,25 @@ ### Fixed +## [0.11.0] + +A performance issue was discovered with gzip and rolling logs, the `background_rotation` feature was +added to mitigate this by spawning a background thread to perform the rotation in. Shout out to @yakov-bakhmatov +for the PR! + +### New + +* `background_rotation` feature which rotates and compresses log archives in a background thread. + +### Changed + +* Deprecate xml feature in preparation for removal. +* Simplify and increase visibility of docs. +* Swap some synchronization primitives to use `parking_lot` implementations. + +### Fixed + + ## [0.10.0] This is a big release as we're moving to rust 2018 edition! diff --git a/src/append/rolling_file/policy/compound/roll/fixed_window.rs b/src/append/rolling_file/policy/compound/roll/fixed_window.rs index ddf9c021..72f5ec85 100644 --- a/src/append/rolling_file/policy/compound/roll/fixed_window.rs +++ b/src/append/rolling_file/policy/compound/roll/fixed_window.rs @@ -250,13 +250,13 @@ impl FixedWindowRollerBuilder { /// Constructs a new `FixedWindowRoller`. /// - /// `pattern` must contain at least one instance of `{}`, all of which will - /// be replaced with an archived log file's index. - /// - /// Note that the pattern is the full path to roll archived logs to. + /// `pattern` is either an absolute path or lacking a leading `/`, relative + /// to the `cwd` of your application. The pattern must contain at least one + /// instance of `{}`, all of which will be replaced with an archived log file's index. /// /// If the file extension of the pattern is `.gz` and the `gzip` Cargo /// feature is enabled, the archive files will be gzip-compressed. + /// If the extension is `.gz` and the `gzip` feature is *not* enabled, an error will be returned. pub fn build( self, pattern: &str, @@ -294,8 +294,9 @@ impl FixedWindowRollerBuilder { /// ```yaml /// kind: fixed_window /// -/// # The filename pattern for archived logs. Must contain at least one `{}`. -/// # Note that the pattern is the full path to roll archived logs to. +/// # The filename pattern for archived logs. This is either an absolute path or if lacking a leading `/`, +/// # relative to the `cwd` of your application. The pattern must contain at least one +/// # instance of `{}`, all of which will be replaced with an archived log file's index. /// # If the file extension of the pattern is `.gz` and the `gzip` Cargo feature /// # is enabled, the archive files will be gzip-compressed. /// # Required. diff --git a/src/lib.rs b/src/lib.rs index 89d3ef1b..8c107607 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -11,17 +11,35 @@ //! An appender takes a log record and logs it somewhere, for example, to a //! file, the console, or the syslog. //! +//! Implementations: +//! - [console](append/console/struct.ConsoleAppenderDeserializer.html#configuration): requires the `console_appender` feature. +//! - [file](append/file/struct.FileAppenderDeserializer.html#configuration): requires the `file_appender` feature. +//! - [rolling_file](append/rolling_file/struct.RollingFileAppenderDeserializer.html#configuration): requires the `rolling_file_appender` feature and can be configured with the `compound_policy`. +//! - [compound](append/rolling_file/policy/compound/struct.CompoundPolicyDeserializer.html#configuration): requires the `compound_policy` feature +//! - Rollers +//! - [delete](append/rolling_file/policy/compound/roll/delete/struct.DeleteRollerDeserializer.html#configuration): requires the `delete_roller` feature +//! - [fixed_window](append/rolling_file/policy/compound/roll/fixed_window/struct.FixedWindowRollerDeserializer.html#configuration): requires the `fixed_window_roller` feature +//! - Triggers +//! - [size](append/rolling_file/policy/compound/trigger/size/struct.SizeTriggerDeserializer.html#configuration): requires the `size_trigger` feature +//! //! ## Encoders //! //! An encoder is responsible for taking a log record, transforming it into the //! appropriate output format, and writing it out. An appender will normally //! use an encoder internally. //! +//! Implementations: +//! - [pattern](encode/pattern/struct.PatternEncoderDeserializer.html#configuration): requires the `pattern_encoder` feature +//! - [json](encode/json/struct.JsonEncoderDeserializer.html#configuration): requires the `json_encoder` feature +//! //! ## Filters //! //! Filters are associated with appenders and, like the name would suggest, //! filter log events coming into that appender. //! +//! Implementations: +//! - [threshold](filter/threshold/struct.ThresholdFilterDeserializer.html#configuration): requires the `threshold_filter` feature +//! //! ## Loggers //! //! A log event is targeted at a specific logger, which are identified by @@ -75,7 +93,7 @@ //! //! # Examples //! -//! Configuration via a YAML file: +//! ## Configuration via a YAML file //! //! ```yaml //! # Scan this file for changes every 30 seconds @@ -113,6 +131,8 @@ //! additive: false //! ``` //! +//! Add the following in your application initialization. +//! //! ```no_run //! # #[cfg(feature = "file")] //! # fn f() { @@ -120,7 +140,7 @@ //! # } //! ``` //! -//! Programmatically constructing a configuration: +//! ## Programmatically constructing a configuration: //! //! ```no_run //! # #[cfg(all(feature = "console_appender", @@ -160,27 +180,10 @@ //! # fn main() {} //! ``` //! -//! # Additional Configuration +//! For more examples see the (examples)[https://github.com/estk/log4rs/tree/master/examples] in the source. //! -//! - Appenders -//! - [console](append/console/struct.ConsoleAppenderDeserializer.html#configuration): requires the `console_appender` feature -//! - [file](append/file/struct.FileAppenderDeserializer.html#configuration): requires the `file_appender` feature -//! - [rolling_file](append/rolling_file/struct.RollingFileAppenderDeserializer.html#configuration): requires the `rolling_file_appender` feature -//! - Encoders -//! - [pattern](encode/pattern/struct.PatternEncoderDeserializer.html#configuration): requires the `pattern_encoder` feature -//! - [json](encode/json/struct.JsonEncoderDeserializer.html#configuration): requires the `json_encoder` feature -//! - Filters -//! - [threshold](filter/threshold/struct.ThresholdFilterDeserializer.html#configuration): requires the `threshold_filter` feature -//! - Policies -//! - [compound](append/rolling_file/policy/compound/struct.CompoundPolicyDeserializer.html#configuration): requires the `compound_policy` feature -//! - Rollers -//! - [delete](append/rolling_file/policy/compound/roll/delete/struct.DeleteRollerDeserializer.html#configuration): requires the `delete_roller` feature -//! - [fixed_window](append/rolling_file/policy/compound/roll/fixed_window/struct.FixedWindowRollerDeserializer.html#configuration): requires the `fixed_window_roller` feature -//! - Triggers -//! - [size](append/rolling_file/policy/compound/trigger/size/struct.SizeTriggerDeserializer.html#configuration): requires the `size_trigger` feature -#![doc(html_root_url = "https://docs.rs/log4rs/0.8")] -#![warn(missing_docs)] +#![warn(missing_docs)] use arc_swap::ArcSwap; use fnv::FnvHasher; use log::{Level, LevelFilter, Metadata, Record, SetLoggerError};