diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 39 |
1 files changed, 35 insertions, 4 deletions
@@ -24,7 +24,7 @@ This version is explicitly tested in CI and may be bumped in any release as need ## Usage
-## In libraries
+### In libraries
Libraries should link only to the `log` crate, and use the provided macros to
log whatever information will be useful to downstream consumers:
@@ -55,15 +55,15 @@ pub fn shave_the_yak(yak: &mut Yak) { }
```
-## In executables
+### In executables
In order to produce log output, executables have to use a logger implementation compatible with the facade.
There are many available implementations to choose from, here are some of the most popular ones:
* Simple minimal loggers:
* [`env_logger`](https://docs.rs/env_logger/*/env_logger/)
- * [`simple_logger`](https://github.com/borntyping/rust-simple_logger)
- * [`simplelog`](https://github.com/drakulix/simplelog.rs)
+ * [`simple_logger`](https://docs.rs/simple_logger/*/simple_logger/)
+ * [`simplelog`](https://docs.rs/simplelog/*/simplelog/)
* [`pretty_env_logger`](https://docs.rs/pretty_env_logger/*/pretty_env_logger/)
* [`stderrlog`](https://docs.rs/stderrlog/*/stderrlog/)
* [`flexi_logger`](https://docs.rs/flexi_logger/*/flexi_logger/)
@@ -72,11 +72,17 @@ There are many available implementations to choose from, here are some of the mo * [`fern`](https://docs.rs/fern/*/fern/)
* Adaptors for other facilities:
* [`syslog`](https://docs.rs/syslog/*/syslog/)
+ * [`systemd-journal-logger`](https://docs.rs/systemd-journal-logger/*/systemd_journal_logger/)
* [`slog-stdlog`](https://docs.rs/slog-stdlog/*/slog_stdlog/)
* [`android_log`](https://docs.rs/android_log/*/android_log/)
* [`win_dbg_logger`](https://docs.rs/win_dbg_logger/*/win_dbg_logger/)
+ * [`db_logger`](https://docs.rs/db_logger/*/db_logger/)
* For WebAssembly binaries:
* [`console_log`](https://docs.rs/console_log/*/console_log/)
+* For dynamic libraries:
+ * You may need to construct [an FFI-safe wrapper over `log`](https://github.com/rust-lang/log/issues/421) to initialize in your libraries.
+* Utilities:
+ * [`log_err`](https://docs.rs/log_err/*/log_err/)
Executables should choose a logger implementation and initialize it early in the
runtime of the program. Logger implementations will typically include a
@@ -84,3 +90,28 @@ function to do this. Any log messages generated before the logger is initialized will be ignored.
The executable itself may use the `log` crate to log as well.
+
+## Structured logging
+
+If you enable the `kv_unstable` feature, you can associate structured data with your log records:
+
+```rust
+use log::{info, trace, warn, as_serde, as_error};
+
+pub fn shave_the_yak(yak: &mut Yak) {
+ trace!(target = "yak_events", yak = as_serde!(yak); "Commencing yak shaving");
+
+ loop {
+ match find_a_razor() {
+ Ok(razor) => {
+ info!(razor = razor; "Razor located");
+ yak.shave(razor);
+ break;
+ }
+ Err(err) => {
+ warn!(err = as_error!(err); "Unable to locate a razor, retrying");
+ }
+ }
+ }
+}
+```
|