cli_log/
lib.rs

1//! The boilerplate to have some file logging with a level given by an environment variable,
2//! and a facility to log execution durations according to the relevant log level.
3//!
4//! It's especially convenient for terminal applications
5//! because you don't want to mix log with stdout or stderr.
6//!
7//! The use of an env variable makes it possible to distribute
8//! the application and have users generate some logs without
9//! recompilation or configuration.
10//!
11//! The names of the log file and the env variable are
12//! computed from the name of the application.
13//!
14//! So log initialization is just
15//!
16//! ```
17//! use cli_log::*; // also import logging macros
18//! init_cli_log!();
19//! ```
20//!
21//! If you prefer not having to declare cli_log import for
22//! all the log and cli-log logging macros, you may use the
23//! old `#[macro_use]` import in your main.rs file:
24//!
25//! ```
26//! #[macro_use] extern crate cli_log;
27//! init_cli_log!();
28//! ```
29//!
30//! With the `"mem"` feature (enabled by default), when the OS is compatible
31//! (unix like), you may dump the current and peak memory usage with
32//! the `log_mem` function.
33//!
34//!
35//! Here's a complete application using cli-log (it can be found in examples):
36//!
37//! ```
38//! use cli_log::*;
39//!
40//! #[derive(Debug)]
41//! struct AppData {
42//!     count: usize,
43//! }
44//! impl AppData {
45//!     fn compute(&mut self) {
46//!         self.count += 7;
47//!     }
48//! }
49//!
50//! fn main() {
51//!     init_cli_log!();
52//!     let mut app_data = AppData { count: 35 };
53//!     time!(Debug, app_data.compute());
54//!     info!("count is {}", app_data.count);
55//!     debug!("data: {:#?}", &app_data);
56//!     warn!("this application does nothing");
57//!     log_mem(Level::Info);
58//!     info!("bye");
59//! }
60//! ```
61//!
62//! If you don't set any `SMALL_APP_LOG` env variable, there won't be any log.
63//!
64//! A convenient way to set the env variable is to launch the app as
65//!
66//! ```cli
67//! SMALL_APP_LOG=debug small_app
68//! ```
69//!
70//! or, during development,
71//!
72//! ```cli
73//! SMALL_APP_LOG=debug cargo run
74//! ```
75//!
76//! This creates a `small_app.log` file containing information like the level,
77//! app version, and of course the log operations you did with time precise to
78//! the ms and the logging module (target):
79//!
80//! ```log
81//! 21:03:24.081 [INFO] cli_log::init: Starting small-app v1.0.1 with log level DEBUG
82//! 21:03:24.081 [DEBUG] small_app: app_data.compute() took 312ns
83//! 21:03:24.081 [INFO] small_app: count is 42
84//! 21:03:24.081 [DEBUG] small_app: data: AppData {
85//!     count: 42,
86//! }
87//! 21:03:24.081 [WARN] small_app: this application does nothing
88//! 21:03:24.081 [INFO] cli_log::mem: Physical mem usage: current=938K, peak=3.3M
89//! 21:03:24.082 [INFO] small_app: bye
90//! ```
91
92mod file_logger;
93mod init;
94mod time;
95
96pub use {
97    init::*,
98    log::*,
99};
100
101#[cfg(feature = "mem")]
102mod mem;
103#[cfg(feature = "mem")]
104pub use mem::log_mem;
cli_log/lib.rs

cli_log/
lib.rs
