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