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.5.13"
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
43INFO: 2017-11-09T02:12:24Z: main: starting up
44```
45
46### In tests
47
48Tests can use the `env_logger` crate to see log messages generated during that test:
49
50```toml
51[dependencies]
52log = "0.4.0"
53
54[dev-dependencies]
55env_logger = "0.5.13"
56```
57
58```rust
59#[macro_use]
60extern crate log;
61
62fn add_one(num: i32) -> i32 {
63 info!("add_one called with {}", num);
64 num + 1
65}
66
67#[cfg(test)]
68mod tests {
69 use super::*;
70 extern crate env_logger;
71
72 #[test]
73 fn it_adds_one() {
74 let _ = env_logger::try_init();
75 info!("can log from the test too");
76 assert_eq!(3, add_one(2));
77 }
78
79 #[test]
80 fn it_handles_negative_numbers() {
81 let _ = env_logger::try_init();
82 info!("logging from another test");
83 assert_eq!(-7, add_one(-8));
84 }
85}
86```
87
88Assuming the module under test is called `my_lib`, running the tests with the
89`RUST_LOG` filtering to info messages from this module looks like:
90
91```bash
92$ RUST_LOG=my_lib=info cargo test
93 Running target/debug/my_lib-...
94
95running 2 tests
96INFO: 2017-11-09T02:12:24Z: my_lib::tests: logging from another test
97INFO: 2017-11-09T02:12:24Z: my_lib: add_one called with -8
98test tests::it_handles_negative_numbers ... ok
99INFO: 2017-11-09T02:12:24Z: my_lib::tests: can log from the test too
100INFO: 2017-11-09T02:12:24Z: my_lib: add_one called with 2
101test tests::it_adds_one ... ok
102
103test result: ok. 2 passed; 0 failed; 0 ignored; 0 measured
104```
105
106Note that `env_logger::try_init()` needs to be called in each test in which you
107want to enable logging. Additionally, the default behavior of tests to
108run in parallel means that logging output may be interleaved with test output.
109Either run tests in a single thread by specifying `RUST_TEST_THREADS=1` or by
110running one test by specifying its name as an argument to the test binaries as
111directed by the `cargo test` help docs:
112
113```bash
114$ RUST_LOG=my_lib=info cargo test it_adds_one
115 Running target/debug/my_lib-...
116
117running 1 test
118INFO: 2017-11-09T02:12:24Z: my_lib::tests: can log from the test too
119INFO: 2017-11-09T02:12:24Z: my_lib: add_one called with 2
120test tests::it_adds_one ... ok
121
122test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured
123```
124
125## Configuring log target
126
127By default, `env_logger` logs to stderr. If you want to log to stdout instead,
128you can use the `Builder` to change the log target:
129
130```rust
131use std::env;
132use env_logger::{Builder, Target};
133
134let mut builder = Builder::new();
135builder.target(Target::Stdout);
136if env::var("RUST_LOG").is_ok() {
137 builder.parse(&env::var("RUST_LOG").unwrap());
138}
139builder.init();
140```
141
){kind=link}
){kind=link}
){kind=link}
){kind=link}