]>
Commit | Line | Data |
---|---|---|
476ff2be SL |
1 | log |
2 | === | |
3 | ||
4 | A Rust library providing a lightweight logging *facade*. | |
5 | ||
6 | [![Build Status](https://travis-ci.org/rust-lang-nursery/log.svg?branch=master)](https://travis-ci.org/rust-lang-nursery/log) | |
7 | [![Build status](https://ci.appveyor.com/api/projects/status/nopdjmmjt45xcrki?svg=true)](https://ci.appveyor.com/project/alexcrichton/log) | |
b7449926 XL |
8 | [![Latest version](https://img.shields.io/crates/v/log.svg)](https://crates.io/crates/log) |
9 | [![Documentation](https://docs.rs/log/badge.svg)](https://docs.rs/log) | |
10 | ![License](https://img.shields.io/crates/l/log.svg) | |
476ff2be | 11 | |
ff7c6d11 | 12 | * [`log` documentation](https://docs.rs/log) |
476ff2be SL |
13 | |
14 | A logging facade provides a single logging API that abstracts over the actual | |
15 | logging implementation. Libraries can use the logging API provided by this | |
16 | crate, and the consumer of those libraries can choose the logging | |
17 | implementation that is most suitable for its use case. | |
18 | ||
19 | ## Usage | |
20 | ||
21 | ## In libraries | |
22 | ||
23 | Libraries should link only to the `log` crate, and use the provided macros to | |
24 | log whatever information will be useful to downstream consumers: | |
25 | ||
26 | ```toml | |
27 | [dependencies] | |
ff7c6d11 | 28 | log = "0.4" |
476ff2be SL |
29 | ``` |
30 | ||
31 | ```rust | |
32 | #[macro_use] | |
33 | extern crate log; | |
34 | ||
8faf50e0 | 35 | pub fn shave_the_yak(yak: &mut Yak) { |
476ff2be SL |
36 | trace!("Commencing yak shaving"); |
37 | ||
38 | loop { | |
39 | match find_a_razor() { | |
40 | Ok(razor) => { | |
41 | info!("Razor located: {}", razor); | |
42 | yak.shave(razor); | |
43 | break; | |
44 | } | |
45 | Err(err) => { | |
46 | warn!("Unable to locate a razor: {}, retrying", err); | |
47 | } | |
48 | } | |
49 | } | |
50 | } | |
51 | ``` | |
52 | ||
53 | ## In executables | |
54 | ||
ff7c6d11 XL |
55 | In order to produce log output executables have to use a logger implementation compatible with the facade. |
56 | There are many available implementations to chose from, here are some of the most popular ones: | |
57 | ||
58 | * Simple minimal loggers: | |
59 | * [`env_logger`](https://docs.rs/env_logger/*/env_logger/) | |
60 | * [`simple_logger`](https://github.com/borntyping/rust-simple_logger) | |
61 | * [`simplelog`](https://github.com/drakulix/simplelog.rs) | |
62 | * [`pretty_env_logger`](https://docs.rs/pretty_env_logger/*/pretty_env_logger/) | |
63 | * [`stderrlog`](https://docs.rs/stderrlog/*/stderrlog/) | |
64 | * [`flexi_logger`](https://docs.rs/flexi_logger/*/flexi_logger/) | |
65 | * Complex configurable frameworks: | |
66 | * [`log4rs`](https://docs.rs/log4rs/*/log4rs/) | |
67 | * [`fern`](https://docs.rs/fern/*/fern/) | |
68 | * Adaptors for other facilities: | |
69 | * [`syslog`](https://docs.rs/syslog/*/syslog/) | |
70 | * [`slog-stdlog`](https://docs.rs/slog-stdlog/*/slog_stdlog/) | |
8faf50e0 | 71 | * [`android_log`](https://docs.rs/android_log/*/android_log/) |
ff7c6d11 | 72 | |
476ff2be SL |
73 | Executables should choose a logger implementation and initialize it early in the |
74 | runtime of the program. Logger implementations will typically include a | |
75 | function to do this. Any log messages generated before the logger is | |
76 | initialized will be ignored. | |
77 | ||
78 | The executable itself may use the `log` crate to log as well. |