flexi_logger/
lib.rs

1// only enables the `doc_cfg` feature when the `docsrs` configuration attribute is defined
2#![cfg_attr(docsrs, feature(doc_cfg))]
3#![deny(missing_docs)]
4#![deny(clippy::all)]
5#![deny(clippy::pedantic)]
6#![forbid(unsafe_code)]
7//! A flexible and easy-to-use logger that writes logs to stderr and/or to files
8//! or other output streams.
9//!
10//! To read the log specification from an environment variable and get the log written to `stderr`,
11//! start `flexi_logger` e.g. like this:
12//! ```rust
13//! flexi_logger::Logger::try_with_env().unwrap().start().unwrap();
14//! ```
15//!
16//! See
17//!
18//! * The builder [`Logger`] for a full description of all configuration options,
19//! * module [`code_examples`] for various concrete examples of `flexi_logger` initialization
20//! * the module [`writers`] for the usage of additional log writers,
21//! * and [the README](https://crates.io/crates/flexi_logger) for how to get started.
22//!
23//! There are configuration options to e.g.
24//!
25//! * decide whether you want to write your logs to stderr or to a file,
26//! * configure the path and the filenames of the log files,
27//! * use file rotation,
28//! * specify the line format for the log lines,
29//! * apply a stateful filter before log lines are really written,
30//! * define additional log output streams, e.g for alert or security messages,
31//! * support changing the log specification while the program is running,
32//!
33//! `flexi_logger` uses a similar syntax as [`env_logger`](http://crates.io/crates/env_logger/)
34//! for specifying which logs should really be written (but is more graceful with the syntax,
35//! and can provide error information).
36//!
37//! By default, i.e. if feature `colors` is not switched off, the log lines that appear on your
38//! terminal are coloured. In case the chosen colors don't fit to your terminal's color theme,
39//! you can adapt the colors to improve readability.
40//! See the documentation of method [`Logger::set_palette`]
41//! for a description how this can be done.
42
43mod deferred_now;
44mod flexi_error;
45mod flexi_logger;
46mod formats;
47mod log_specification;
48mod logger;
49mod logger_handle;
50mod parameters;
51mod primary_writer;
52mod threads;
53#[cfg(feature = "trc")]
54#[cfg_attr(docsrs, doc(cfg(feature = "trc")))]
55pub mod trc;
56mod write_mode;
57
58pub mod code_examples;
59pub mod filter;
60mod util;
61pub mod writers;
62
63pub mod error_info;
64
65pub(crate) use crate::write_mode::EffectiveWriteMode;
66#[cfg(feature = "async")]
67pub use crate::write_mode::{DEFAULT_MESSAGE_CAPA, DEFAULT_POOL_CAPA};
68pub use crate::{
69    deferred_now::DeferredNow,
70    flexi_error::FlexiLoggerError,
71    formats::*,
72    log_specification::{LogSpecBuilder, LogSpecification, ModuleFilter},
73    logger::{Duplicate, ErrorChannel, Logger},
74    logger_handle::{LogfileSelector, LoggerHandle},
75    parameters::{Age, Cleanup, Criterion, FileSpec, Naming},
76    write_mode::{WriteMode, DEFAULT_BUFFER_CAPACITY, DEFAULT_FLUSH_INTERVAL},
77};
78
79/// Re-exports from log crate
80pub use log::{Level, LevelFilter, Record};
81
82pub(crate) const ZERO_DURATION: std::time::Duration = std::time::Duration::from_secs(0);
83
84/// Shortest form to get started.
85///
86/// `flexi_logger::init();`.
87///
88/// Equivalent to
89/// ```rust
90/// # use flexi_logger::{Logger,LogSpecification};
91///     Logger::try_with_env_or_str("info")
92///        .unwrap_or_else(|_e| Logger::with(LogSpecification::info()))
93///        .log_to_stderr()
94///        .start()
95///        .ok();
96/// ```
97/// that means,
98///
99/// - you configure the log specification via the environment variable `RUST_LOG`,
100///   or use the default log specification (`'info'`)
101/// - logs are directly written to `stderr`, without any buffering, so implicitly dropping the
102///   `LogHandle` (which is returned from `Logger::start()`) is ok.
103pub fn init() {
104    Logger::try_with_env_or_str("info")
105        .unwrap_or_else(|_e| Logger::with(LogSpecification::info()))
106        .log_to_stderr()
107        .start()
108        .ok();
109}
flexi_logger/lib.rs

flexi_logger/
lib.rs
