README.md
1env_logger [](https://travis-ci.org/sebasmagri/env_logger) [](https://github.com/sebasmagri/env_logger) [](https://crates.io/crates/env_logger) [](https://docs.rs/env_logger)
2==========
3
4Implements a logger that can be configured via environment variables.
5
6## Usage
7
8### In libraries
9
10`env_logger` makes sense when used in executables (binary projects). Libraries should use the [`log`](https://doc.rust-lang.org/log) crate instead.
11
12### In executables
13
14It must be added along with `log` to the project dependencies:
15
16```toml
17[dependencies]
18log = "0.4.0"
19env_logger = "0.6.2"
20```
21
22`env_logger` must be initialized as early as possible in the project. After it's initialized, you can use the `log` macros to do actual logging.
23
24```rust
25#[macro_use]
26extern crate log;
27extern crate env_logger;
28
29fn main() {
30 env_logger::init();
31
32 info!("starting up");
33
34 // ...
35}
36```
37
38Then when running the executable, specify a value for the `RUST_LOG`
39environment variable that corresponds with the log messages you want to show.
40
41```bash
42$ RUST_LOG=info ./main
43[2018-11-03T06:09:06Z INFO default] starting up
44```
45
46`env_logger` can be configured in other ways besides an environment variable. See [the examples](https://github.com/sebasmagri/env_logger/tree/master/examples) for more approaches.
47
48### In tests
49
50Tests can use the `env_logger` crate to see log messages generated during that test:
51
52```toml
53[dependencies]
54log = "0.4.0"
55
56[dev-dependencies]
57env_logger = "0.6.2"
58```
59
60```rust
61#[macro_use]
62extern crate log;
63
64fn add_one(num: i32) -> i32 {
65 info!("add_one called with {}", num);
66 num + 1
67}
68
69#[cfg(test)]
70mod tests {
71 use super::*;
72 extern crate env_logger;
73
74 fn init() {
75 let _ = env_logger::builder().is_test(true).try_init();
76 }
77
78 #[test]
79 fn it_adds_one() {
80 init();
81
82 info!("can log from the test too");
83 assert_eq!(3, add_one(2));
84 }
85
86 #[test]
87 fn it_handles_negative_numbers() {
88 init();
89
90 info!("logging from another test");
91 assert_eq!(-7, add_one(-8));
92 }
93}
94```
95
96Assuming the module under test is called `my_lib`, running the tests with the
97`RUST_LOG` filtering to info messages from this module looks like:
98
99```bash
100$ RUST_LOG=my_lib=info cargo test
101 Running target/debug/my_lib-...
102
103running 2 tests
104[INFO my_lib::tests] logging from another test
105[INFO my_lib] add_one called with -8
106test tests::it_handles_negative_numbers ... ok
107[INFO my_lib::tests] can log from the test too
108[INFO my_lib] add_one called with 2
109test tests::it_adds_one ... ok
110
111test result: ok. 2 passed; 0 failed; 0 ignored; 0 measured
112```
113
114Note that `env_logger::try_init()` needs to be called in each test in which you
115want to enable logging. Additionally, the default behavior of tests to
116run in parallel means that logging output may be interleaved with test output.
117Either run tests in a single thread by specifying `RUST_TEST_THREADS=1` or by
118running one test by specifying its name as an argument to the test binaries as
119directed by the `cargo test` help docs:
120
121```bash
122$ RUST_LOG=my_lib=info cargo test it_adds_one
123 Running target/debug/my_lib-...
124
125running 1 test
126[INFO my_lib::tests] can log from the test too
127[INFO my_lib] add_one called with 2
128test tests::it_adds_one ... ok
129
130test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured
131```
132
133## Configuring log target
134
135By default, `env_logger` logs to stderr. If you want to log to stdout instead,
136you can use the `Builder` to change the log target:
137
138```rust
139use std::env;
140use env_logger::{Builder, Target};
141
142let mut builder = Builder::from_default_env();
143builder.target(Target::Stdout);
144
145builder.init();
146```
147
148## Stability of the default format
149
150The default format won't optimise for long-term stability, and explicitly makes no guarantees about the stability of its output across major, minor or patch version bumps during `0.x`.
151
152If you want to capture or interpret the output of `env_logger` programmatically then you should use a custom format.
153
){kind=link}
){kind=link}
){kind=link}
){kind=link}