README.md
1# env_logger
2
3[](https://github.com/env-logger-rs/env_logger)
4[](https://crates.io/crates/env_logger)
5[](https://docs.rs/env_logger)
6[](https://env-logger-rs.github.io/env_logger/env_logger/index.html)
7==========
8
9Implements a logger that can be configured via environment variables.
10
11## Usage
12
13### In libraries
14
15`env_logger` makes sense when used in executables (binary projects). Libraries should use the [`log`](https://doc.rust-lang.org/log) crate instead.
16
17### In executables
18
19It must be added along with `log` to the project dependencies:
20
21```toml
22[dependencies]
23log = "0.4.0"
24env_logger = "0.8.3"
25```
26
27`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.
28
29```rust
30#[macro_use]
31extern crate log;
32
33fn main() {
34 env_logger::init();
35
36 info!("starting up");
37
38 // ...
39}
40```
41
42Then when running the executable, specify a value for the **`RUST_LOG`**
43environment variable that corresponds with the log messages you want to show.
44
45```bash
46$ RUST_LOG=info ./main
47[2018-11-03T06:09:06Z INFO default] starting up
48```
49
50The letter case is not significant for the logging level names; e.g., `debug`,
51`DEBUG`, and `dEbuG` all represent the same logging level. Therefore, the
52previous example could also have been written this way, specifying the log
53level as `INFO` rather than as `info`:
54
55```bash
56$ RUST_LOG=INFO ./main
57[2018-11-03T06:09:06Z INFO default] starting up
58```
59
60So which form should you use? For consistency, our convention is to use lower
61case names. Where our docs do use other forms, they do so in the context of
62specific examples, so you won't be surprised if you see similar usage in the
63wild.
64
65The log levels that may be specified correspond to the [`log::Level`][level-enum]
66enum from the `log` crate. They are:
67
68 * `error`
69 * `warn`
70 * `info`
71 * `debug`
72 * `trace`
73
74[level-enum]: https://docs.rs/log/latest/log/enum.Level.html "log::Level (docs.rs)"
75
76There is also a pseudo logging level, `off`, which may be specified to disable
77all logging for a given module or for the entire application. As with the
78logging levels, the letter case is not significant.
79
80`env_logger` can be configured in other ways besides an environment variable. See [the examples](https://github.com/env-logger-rs/env_logger/tree/master/examples) for more approaches.
81
82### In tests
83
84Tests can use the `env_logger` crate to see log messages generated during that test:
85
86```toml
87[dependencies]
88log = "0.4.0"
89
90[dev-dependencies]
91env_logger = "0.8.3"
92```
93
94```rust
95#[macro_use]
96extern crate log;
97
98fn add_one(num: i32) -> i32 {
99 info!("add_one called with {}", num);
100 num + 1
101}
102
103#[cfg(test)]
104mod tests {
105 use super::*;
106
107 fn init() {
108 let _ = env_logger::builder().is_test(true).try_init();
109 }
110
111 #[test]
112 fn it_adds_one() {
113 init();
114
115 info!("can log from the test too");
116 assert_eq!(3, add_one(2));
117 }
118
119 #[test]
120 fn it_handles_negative_numbers() {
121 init();
122
123 info!("logging from another test");
124 assert_eq!(-7, add_one(-8));
125 }
126}
127```
128
129Assuming the module under test is called `my_lib`, running the tests with the
130`RUST_LOG` filtering to info messages from this module looks like:
131
132```bash
133$ RUST_LOG=my_lib=info cargo test
134 Running target/debug/my_lib-...
135
136running 2 tests
137[INFO my_lib::tests] logging from another test
138[INFO my_lib] add_one called with -8
139test tests::it_handles_negative_numbers ... ok
140[INFO my_lib::tests] can log from the test too
141[INFO my_lib] add_one called with 2
142test tests::it_adds_one ... ok
143
144test result: ok. 2 passed; 0 failed; 0 ignored; 0 measured
145```
146
147Note that `env_logger::try_init()` needs to be called in each test in which you
148want to enable logging. Additionally, the default behavior of tests to
149run in parallel means that logging output may be interleaved with test output.
150Either run tests in a single thread by specifying `RUST_TEST_THREADS=1` or by
151running one test by specifying its name as an argument to the test binaries as
152directed by the `cargo test` help docs:
153
154```bash
155$ RUST_LOG=my_lib=info cargo test it_adds_one
156 Running target/debug/my_lib-...
157
158running 1 test
159[INFO my_lib::tests] can log from the test too
160[INFO my_lib] add_one called with 2
161test tests::it_adds_one ... ok
162
163test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured
164```
165
166## Configuring log target
167
168By default, `env_logger` logs to stderr. If you want to log to stdout instead,
169you can use the `Builder` to change the log target:
170
171```rust
172use std::env;
173use env_logger::{Builder, Target};
174
175let mut builder = Builder::from_default_env();
176builder.target(Target::Stdout);
177
178builder.init();
179```
180
181## Stability of the default format
182
183The 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`.
184
185If you want to capture or interpret the output of `env_logger` programmatically then you should use a custom format.
186
){kind=link}
){kind=link}
){kind=link}
){kind=link}