| 1 |
log |
| 2 |
=== |
| 3 |
|
| 4 |
A Rust library providing a lightweight logging *facade*. |
| 5 |
|
| 6 |
[](https://github.com/rust-lang/log/actions) |
| 7 |
[](https://crates.io/crates/log) |
| 8 |
[](https://docs.rs/log) |
| 9 |
 |
| 10 |
|
| 11 |
* [`log` documentation](https://docs.rs/log) |
| 12 |
|
| 13 |
A logging facade provides a single logging API that abstracts over the actual |
| 14 |
logging implementation. Libraries can use the logging API provided by this |
| 15 |
crate, and the consumer of those libraries can choose the logging |
| 16 |
implementation that is most suitable for its use case. |
| 17 |
|
| 18 |
|
| 19 |
## Minimum supported `rustc` |
| 20 |
|
| 21 |
`1.60.0+` |
| 22 |
|
| 23 |
This version is explicitly tested in CI and may be bumped in any release as needed. Maintaining compatibility with older compilers is a priority though, so the bar for bumping the minimum supported version is set very high. Any changes to the supported minimum version will be called out in the release notes. |
| 24 |
|
| 25 |
## Usage |
| 26 |
|
| 27 |
### In libraries |
| 28 |
|
| 29 |
Libraries should link only to the `log` crate, and use the provided macros to |
| 30 |
log whatever information will be useful to downstream consumers: |
| 31 |
|
| 32 |
```toml |
| 33 |
[dependencies] |
| 34 |
log = "0.4" |
| 35 |
``` |
| 36 |
|
| 37 |
```rust |
| 38 |
use log::{info, trace, warn}; |
| 39 |
|
| 40 |
pub fn shave_the_yak(yak: &mut Yak) { |
| 41 |
trace!("Commencing yak shaving"); |
| 42 |
|
| 43 |
loop { |
| 44 |
match find_a_razor() { |
| 45 |
Ok(razor) => { |
| 46 |
info!("Razor located: {razor}"); |
| 47 |
yak.shave(razor); |
| 48 |
break; |
| 49 |
} |
| 50 |
Err(err) => { |
| 51 |
warn!("Unable to locate a razor: {err}, retrying"); |
| 52 |
} |
| 53 |
} |
| 54 |
} |
| 55 |
} |
| 56 |
``` |
| 57 |
|
| 58 |
### In executables |
| 59 |
|
| 60 |
In order to produce log output, executables have to use a logger implementation compatible with the facade. |
| 61 |
There are many available implementations to choose from, here are some options: |
| 62 |
|
| 63 |
* Simple minimal loggers: |
| 64 |
* [`env_logger`](https://docs.rs/env_logger/*/env_logger/) |
| 65 |
* [`simple_logger`](https://docs.rs/simple_logger/*/simple_logger/) |
| 66 |
* [`simplelog`](https://docs.rs/simplelog/*/simplelog/) |
| 67 |
* [`pretty_env_logger`](https://docs.rs/pretty_env_logger/*/pretty_env_logger/) |
| 68 |
* [`stderrlog`](https://docs.rs/stderrlog/*/stderrlog/) |
| 69 |
* [`flexi_logger`](https://docs.rs/flexi_logger/*/flexi_logger/) |
| 70 |
* [`call_logger`](https://docs.rs/call_logger/*/call_logger/) |
| 71 |
* [`std-logger`](https://docs.rs/std-logger/*/std_logger/) |
| 72 |
* [`structured-logger`](https://docs.rs/structured-logger/latest/structured_logger/) |
| 73 |
* Complex configurable frameworks: |
| 74 |
* [`log4rs`](https://docs.rs/log4rs/*/log4rs/) |
| 75 |
* [`fern`](https://docs.rs/fern/*/fern/) |
| 76 |
* Adaptors for other facilities: |
| 77 |
* [`syslog`](https://docs.rs/syslog/*/syslog/) |
| 78 |
* [`systemd-journal-logger`](https://docs.rs/systemd-journal-logger/*/systemd_journal_logger/) |
| 79 |
* [`slog-stdlog`](https://docs.rs/slog-stdlog/*/slog_stdlog/) |
| 80 |
* [`android_log`](https://docs.rs/android_log/*/android_log/) |
| 81 |
* [`win_dbg_logger`](https://docs.rs/win_dbg_logger/*/win_dbg_logger/) |
| 82 |
* [`db_logger`](https://docs.rs/db_logger/*/db_logger/) |
| 83 |
* [`log-to-defmt`](https://docs.rs/log-to-defmt/*/log_to_defmt/) |
| 84 |
* [`logcontrol-log`](https://docs.rs/logcontrol-log/*/logcontrol_log/) |
| 85 |
* For WebAssembly binaries: |
| 86 |
* [`console_log`](https://docs.rs/console_log/*/console_log/) |
| 87 |
* For dynamic libraries: |
| 88 |
* You may need to construct [an FFI-safe wrapper over `log`](https://github.com/rust-lang/log/issues/421) to initialize in your libraries. |
| 89 |
* Utilities: |
| 90 |
* [`log_err`](https://docs.rs/log_err/*/log_err/) |
| 91 |
* [`log-reload`](https://docs.rs/log-reload/*/log_reload/) |
| 92 |
* [`alterable_logger`](https://docs.rs/alterable_logger/*/alterable_logger) |
| 93 |
|
| 94 |
Executables should choose a logger implementation and initialize it early in the |
| 95 |
runtime of the program. Logger implementations will typically include a |
| 96 |
function to do this. Any log messages generated before the logger is |
| 97 |
initialized will be ignored. |
| 98 |
|
| 99 |
The executable itself may use the `log` crate to log as well. |
| 100 |
|
| 101 |
## Structured logging |
| 102 |
|
| 103 |
If you enable the `kv` feature, you can associate structured data with your log records: |
| 104 |
|
| 105 |
```rust |
| 106 |
use log::{info, trace, warn}; |
| 107 |
|
| 108 |
pub fn shave_the_yak(yak: &mut Yak) { |
| 109 |
// `yak:serde` will capture `yak` using its `serde::Serialize` impl |
| 110 |
// |
| 111 |
// You could also use `:?` for `Debug`, or `:%` for `Display`. For a |
| 112 |
// full list, see the `log` crate documentation |
| 113 |
trace!(target = "yak_events", yak:serde; "Commencing yak shaving"); |
| 114 |
|
| 115 |
loop { |
| 116 |
match find_a_razor() { |
| 117 |
Ok(razor) => { |
| 118 |
info!(razor; "Razor located"); |
| 119 |
yak.shave(razor); |
| 120 |
break; |
| 121 |
} |
| 122 |
Err(e) => { |
| 123 |
// `e:err` will capture `e` using its `std::error::Error` impl |
| 124 |
warn!(e:err; "Unable to locate a razor, retrying"); |
| 125 |
} |
| 126 |
} |
| 127 |
} |
| 128 |
} |
| 129 |
``` |