1 // Copyright 2015 The Rust Project Developers. See the COPYRIGHT
2 // file at the top-level directory of this distribution and at
3 // http://rust-lang.org/COPYRIGHT.
4 //
5 // Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
6 // http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
7 // <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
8 // option. This file may not be copied, modified, or distributed
9 // except according to those terms.
10
11 //! A lightweight logging facade.
12 //!
13 //! The `log` crate provides a single logging API that abstracts over the
14 //! actual logging implementation. Libraries can use the logging API provided
15 //! by this crate, and the consumer of those libraries can choose the logging
16 //! implementation that is most suitable for its use case.
17 //!
18 //! If no logging implementation is selected, the facade falls back to a "noop"
19 //! implementation that ignores all log messages. The overhead in this case
20 //! is very small - just an integer load, comparison and jump.
21 //!
22 //! A log request consists of a _target_, a _level_, and a _body_. A target is a
23 //! string which defaults to the module path of the location of the log request,
24 //! though that default may be overridden. Logger implementations typically use
25 //! the target to filter requests based on some user configuration.
26 //!
27 //! # Use
28 //!
29 //! The basic use of the log crate is through the five logging macros: [`error!`],
30 //! [`warn!`], [`info!`], [`debug!`] and [`trace!`]
31 //! where `error!` represents the highest-priority log messages
32 //! and `trace!` the lowest. The log messages are filtered by configuring
33 //! the log level to exclude messages with a lower priority.
34 //! Each of these macros accept format strings similarly to [`println!`].
35 //!
36 //!
37 //! [`error!`]: ./macro.error.html
38 //! [`warn!`]: ./macro.warn.html
39 //! [`info!`]: ./macro.info.html
40 //! [`debug!`]: ./macro.debug.html
41 //! [`trace!`]: ./macro.trace.html
42 //! [`println!`]: https://doc.rust-lang.org/stable/std/macro.println.html
43 //!
44 //! ## In libraries
45 //!
46 //! Libraries should link only to the `log` crate, and use the provided
47 //! macros to log whatever information will be useful to downstream consumers.
48 //!
49 //! ### Examples
50 //!
51 //! ```edition2018
52 //! # #[derive(Debug)] pub struct Yak(String);
53 //! # impl Yak { fn shave(&mut self, _: u32) {} }
54 //! # fn find_a_razor() -> Result<u32, u32> { Ok(1) }
55 //! use log::{info, warn};
56 //!
57 //! pub fn shave_the_yak(yak: &mut Yak) {
58 //! info!(target: "yak_events", "Commencing yak shaving for {:?}", yak);
59 //!
60 //! loop {
61 //! match find_a_razor() {
62 //! Ok(razor) => {
63 //! info!("Razor located: {}", razor);
64 //! yak.shave(razor);
65 //! break;
66 //! }
67 //! Err(err) => {
68 //! warn!("Unable to locate a razor: {}, retrying", err);
69 //! }
70 //! }
71 //! }
72 //! }
73 //! # fn main() {}
74 //! ```
75 //!
76 //! ## In executables
77 //!
78 //! Executables should choose a logging implementation and initialize it early in the
79 //! runtime of the program. Logging implementations will typically include a
80 //! function to do this. Any log messages generated before
81 //! the implementation is initialized will be ignored.
82 //!
83 //! The executable itself may use the `log` crate to log as well.
84 //!
85 //! ### Warning
86 //!
87 //! The logging system may only be initialized once.
88 //!
89 //! # Available logging implementations
90 //!
91 //! In order to produce log output executables have to use
92 //! a logger implementation compatible with the facade.
93 //! There are many available implementations to choose from,
94 //! here are some of the most popular ones:
95 //!
96 //! * Simple minimal loggers:
97 //! * [env_logger]
98 //! * [simple_logger]
99 //! * [simplelog]
100 //! * [pretty_env_logger]
101 //! * [stderrlog]
102 //! * [flexi_logger]
103 //! * Complex configurable frameworks:
104 //! * [log4rs]
105 //! * [fern]
106 //! * Adaptors for other facilities:
107 //! * [syslog]
108 //! * [slog-stdlog]
109 //!
110 //! # Implementing a Logger
111 //!
112 //! Loggers implement the [`Log`] trait. Here's a very basic example that simply
113 //! logs all messages at the [`Error`][level_link], [`Warn`][level_link] or
114 //! [`Info`][level_link] levels to stdout:
115 //!
116 //! ```edition2018
117 //! use log::{Record, Level, Metadata};
118 //!
119 //! struct SimpleLogger;
120 //!
121 //! impl log::Log for SimpleLogger {
122 //! fn enabled(&self, metadata: &Metadata) -> bool {
123 //! metadata.level() <= Level::Info
124 //! }
125 //!
126 //! fn log(&self, record: &Record) {
127 //! if self.enabled(record.metadata()) {
128 //! println!("{} - {}", record.level(), record.args());
129 //! }
130 //! }
131 //!
132 //! fn flush(&self) {}
133 //! }
134 //!
135 //! # fn main() {}
136 //! ```
137 //!
138 //! Loggers are installed by calling the [`set_logger`] function. The maximum
139 //! log level also needs to be adjusted via the [`set_max_level`] function. The
140 //! logging facade uses this as an optimization to improve performance of log
141 //! messages at levels that are disabled. It's important to set it, as it
142 //! defaults to [`Off`][filter_link], so no log messages will ever be captured!
143 //! In the case of our example logger, we'll want to set the maximum log level
144 //! to [`Info`][filter_link], since we ignore any [`Debug`][level_link] or
145 //! [`Trace`][level_link] level log messages. A logging implementation should
146 //! provide a function that wraps a call to [`set_logger`] and
147 //! [`set_max_level`], handling initialization of the logger:
148 //!
149 //! ```edition2018
150 //! # use log::{Level, Metadata};
151 //! # struct SimpleLogger;
152 //! # impl log::Log for SimpleLogger {
153 //! # fn enabled(&self, _: &Metadata) -> bool { false }
154 //! # fn log(&self, _: &log::Record) {}
155 //! # fn flush(&self) {}
156 //! # }
157 //! # fn main() {}
158 //! use log::{SetLoggerError, LevelFilter};
159 //!
160 //! static LOGGER: SimpleLogger = SimpleLogger;
161 //!
162 //! pub fn init() -> Result<(), SetLoggerError> {
163 //! log::set_logger(&LOGGER)
164 //! .map(|()| log::set_max_level(LevelFilter::Info))
165 //! }
166 //! ```
167 //!
168 //! Implementations that adjust their configurations at runtime should take care
169 //! to adjust the maximum log level as well.
170 //!
171 //! # Use with `std`
172 //!
173 //! `set_logger` requires you to provide a `&'static Log`, which can be hard to
174 //! obtain if your logger depends on some runtime configuration. The
175 //! `set_boxed_logger` function is available with the `std` Cargo feature. It is
176 //! identical to `set_logger` except that it takes a `Box<Log>` rather than a
177 //! `&'static Log`:
178 //!
179 //! ```edition2018
180 //! # use log::{Level, LevelFilter, Log, SetLoggerError, Metadata};
181 //! # struct SimpleLogger;
182 //! # impl log::Log for SimpleLogger {
183 //! # fn enabled(&self, _: &Metadata) -> bool { false }
184 //! # fn log(&self, _: &log::Record) {}
185 //! # fn flush(&self) {}
186 //! # }
187 //! # fn main() {}
188 //! # #[cfg(feature = "std")]
189 //! pub fn init() -> Result<(), SetLoggerError> {
190 //! log::set_boxed_logger(Box::new(SimpleLogger))
191 //! .map(|()| log::set_max_level(LevelFilter::Info))
192 //! }
193 //! ```
194 //!
195 //! # Compile time filters
196 //!
197 //! Log levels can be statically disabled at compile time via Cargo features. Log invocations at
198 //! disabled levels will be skipped and will not even be present in the resulting binary unless the
199 //! log level is specified dynamically. This level is configured separately for release and debug
200 //! builds. The features are:
201 //!
202 //! * `max_level_off`
203 //! * `max_level_error`
204 //! * `max_level_warn`
205 //! * `max_level_info`
206 //! * `max_level_debug`
207 //! * `max_level_trace`
208 //! * `release_max_level_off`
209 //! * `release_max_level_error`
210 //! * `release_max_level_warn`
211 //! * `release_max_level_info`
212 //! * `release_max_level_debug`
213 //! * `release_max_level_trace`
214 //!
215 //! These features control the value of the `STATIC_MAX_LEVEL` constant. The logging macros check
216 //! this value before logging a message. By default, no levels are disabled.
217 //!
218 //! Libraries should avoid using the max level features because they're global and can't be changed
219 //! once they're set.
220 //!
221 //! For example, a crate can disable trace level logs in debug builds and trace, debug, and info
222 //! level logs in release builds with the following configuration:
223 //!
224 //! ```toml
225 //! [dependencies]
226 //! log = { version = "0.4", features = ["max_level_debug", "release_max_level_warn"] }
227 //! ```
228 //! # Crate Feature Flags
229 //!
230 //! The following crate feature flags are avaliable in addition to the filters. They are
231 //! configured in your `Cargo.toml`.
232 //!
233 //! * `std` allows use of `std` crate instead of the default `core`. Enables using `std::error` and
234 //! `set_boxed_logger` functionality.
235 //! * `serde` enables support for serialization and deserialization of `Level` and `LevelFilter`.
236 //!
237 //! ```toml
238 //! [dependencies]
239 //! log = { version = "0.4", features = ["std", "serde"] }
240 //! ```
241 //!
242 //! # Version compatibility
243 //!
244 //! The 0.3 and 0.4 versions of the `log` crate are almost entirely compatible. Log messages
245 //! made using `log` 0.3 will forward transparently to a logger implementation using `log` 0.4. Log
246 //! messages made using `log` 0.4 will forward to a logger implementation using `log` 0.3, but the
247 //! module path and file name information associated with the message will unfortunately be lost.
248 //!
249 //! [`Log`]: trait.Log.html
250 //! [level_link]: enum.Level.html
251 //! [filter_link]: enum.LevelFilter.html
252 //! [`set_logger`]: fn.set_logger.html
253 //! [`set_max_level`]: fn.set_max_level.html
254 //! [`try_set_logger_raw`]: fn.try_set_logger_raw.html
255 //! [`shutdown_logger_raw`]: fn.shutdown_logger_raw.html
256 //! [env_logger]: https://docs.rs/env_logger/*/env_logger/
257 //! [simple_logger]: https://github.com/borntyping/rust-simple_logger
258 //! [simplelog]: https://github.com/drakulix/simplelog.rs
259 //! [pretty_env_logger]: https://docs.rs/pretty_env_logger/*/pretty_env_logger/
260 //! [stderrlog]: https://docs.rs/stderrlog/*/stderrlog/
261 //! [flexi_logger]: https://docs.rs/flexi_logger/*/flexi_logger/
262 //! [syslog]: https://docs.rs/syslog/*/syslog/
263 //! [slog-stdlog]: https://docs.rs/slog-stdlog/*/slog_stdlog/
264 //! [log4rs]: https://docs.rs/log4rs/*/log4rs/
265 //! [fern]: https://docs.rs/fern/*/fern/
266
267 #![doc(
268 html_logo_url = "https://www.rust-lang.org/logos/rust-logo-128x128-blk-v2.png",
269 html_favicon_url = "https://www.rust-lang.org/favicon.ico",
270 html_root_url = "https://docs.rs/log/0.4.8"
271 )]
272 #![warn(missing_docs)]
273 #![deny(missing_debug_implementations)]
274 #![cfg_attr(all(not(feature = "std"), not(test)), no_std)]
275 // When compiled for the rustc compiler itself we want to make sure that this is
276 // an unstable crate
277 #![cfg_attr(rustbuild, feature(staged_api, rustc_private))]
278 #![cfg_attr(rustbuild, unstable(feature = "rustc_private", issue = "27812"))]
279
280 #[cfg(all(not(feature = "std"), not(test)))]
281 extern crate core as std;
282
283 #[macro_use]
284 extern crate cfg_if;
285
286 use std::cmp;
287 #[cfg(feature = "std")]
288 use std::error;
289 use std::fmt;
290 use std::mem;
291 use std::str::FromStr;
292 use std::sync::atomic::{AtomicUsize, Ordering};
293
294 // FIXME: ATOMIC_USIZE_INIT was deprecated in rust 1.34. Silence the
295 // deprecation warning until our MSRV >= 1.24, where we can use the
296 // replacement const fn `AtomicUsize::new`
297 #[allow(deprecated)]
298 use std::sync::atomic::ATOMIC_USIZE_INIT;
299
300 #[macro_use]
301 mod macros;
302 mod serde;
303
304 #[cfg(feature = "kv_unstable")]
305 pub mod kv;
306
307 // The LOGGER static holds a pointer to the global logger. It is protected by
308 // the STATE static which determines whether LOGGER has been initialized yet.
309 static mut LOGGER: &'static Log = &NopLogger;
310
311 #[allow(deprecated)]
312 static STATE: AtomicUsize = ATOMIC_USIZE_INIT;
313
314 // There are three different states that we care about: the logger's
315 // uninitialized, the logger's initializing (set_logger's been called but
316 // LOGGER hasn't actually been set yet), or the logger's active.
317 const UNINITIALIZED: usize = 0;
318 const INITIALIZING: usize = 1;
319 const INITIALIZED: usize = 2;
320
321 #[allow(deprecated)]
322 static MAX_LOG_LEVEL_FILTER: AtomicUsize = ATOMIC_USIZE_INIT;
323
324 static LOG_LEVEL_NAMES: [&'static str; 6] = ["OFF", "ERROR", "WARN", "INFO", "DEBUG", "TRACE"];
325
326 static SET_LOGGER_ERROR: &'static str = "attempted to set a logger after the logging system \
327 was already initialized";
328 static LEVEL_PARSE_ERROR: &'static str =
329 "attempted to convert a string that doesn't match an existing log level";
330
331 /// An enum representing the available verbosity levels of the logger.
332 ///
333 /// Typical usage includes: checking if a certain `Level` is enabled with
334 /// [`log_enabled!`](macro.log_enabled.html), specifying the `Level` of
335 /// [`log!`](macro.log.html), and comparing a `Level` directly to a
336 /// [`LevelFilter`](enum.LevelFilter.html).
337 #[repr(usize)]
338 #[derive(Copy, Eq, Debug, Hash)]
339 pub enum Level {
340 /// The "error" level.
341 ///
342 /// Designates very serious errors.
343 Error = 1, // This way these line up with the discriminants for LevelFilter below
344 /// The "warn" level.
345 ///
346 /// Designates hazardous situations.
347 Warn,
348 /// The "info" level.
349 ///
350 /// Designates useful information.
351 Info,
352 /// The "debug" level.
353 ///
354 /// Designates lower priority information.
355 Debug,
356 /// The "trace" level.
357 ///
358 /// Designates very low priority, often extremely verbose, information.
359 Trace,
360 }
361
362 impl Clone for Level {
363 #[inline]
clone(&self) -> Level364 fn clone(&self) -> Level {
365 *self
366 }
367 }
368
369 impl PartialEq for Level {
370 #[inline]
eq(&self, other: &Level) -> bool371 fn eq(&self, other: &Level) -> bool {
372 *self as usize == *other as usize
373 }
374 }
375
376 impl PartialEq<LevelFilter> for Level {
377 #[inline]
eq(&self, other: &LevelFilter) -> bool378 fn eq(&self, other: &LevelFilter) -> bool {
379 *self as usize == *other as usize
380 }
381 }
382
383 impl PartialOrd for Level {
384 #[inline]
partial_cmp(&self, other: &Level) -> Option<cmp::Ordering>385 fn partial_cmp(&self, other: &Level) -> Option<cmp::Ordering> {
386 Some(self.cmp(other))
387 }
388
389 #[inline]
lt(&self, other: &Level) -> bool390 fn lt(&self, other: &Level) -> bool {
391 (*self as usize) < *other as usize
392 }
393
394 #[inline]
le(&self, other: &Level) -> bool395 fn le(&self, other: &Level) -> bool {
396 *self as usize <= *other as usize
397 }
398
399 #[inline]
gt(&self, other: &Level) -> bool400 fn gt(&self, other: &Level) -> bool {
401 *self as usize > *other as usize
402 }
403
404 #[inline]
ge(&self, other: &Level) -> bool405 fn ge(&self, other: &Level) -> bool {
406 *self as usize >= *other as usize
407 }
408 }
409
410 impl PartialOrd<LevelFilter> for Level {
411 #[inline]
partial_cmp(&self, other: &LevelFilter) -> Option<cmp::Ordering>412 fn partial_cmp(&self, other: &LevelFilter) -> Option<cmp::Ordering> {
413 Some((*self as usize).cmp(&(*other as usize)))
414 }
415
416 #[inline]
lt(&self, other: &LevelFilter) -> bool417 fn lt(&self, other: &LevelFilter) -> bool {
418 (*self as usize) < *other as usize
419 }
420
421 #[inline]
le(&self, other: &LevelFilter) -> bool422 fn le(&self, other: &LevelFilter) -> bool {
423 *self as usize <= *other as usize
424 }
425
426 #[inline]
gt(&self, other: &LevelFilter) -> bool427 fn gt(&self, other: &LevelFilter) -> bool {
428 *self as usize > *other as usize
429 }
430
431 #[inline]
ge(&self, other: &LevelFilter) -> bool432 fn ge(&self, other: &LevelFilter) -> bool {
433 *self as usize >= *other as usize
434 }
435 }
436
437 impl Ord for Level {
438 #[inline]
cmp(&self, other: &Level) -> cmp::Ordering439 fn cmp(&self, other: &Level) -> cmp::Ordering {
440 (*self as usize).cmp(&(*other as usize))
441 }
442 }
443
ok_or<T, E>(t: Option<T>, e: E) -> Result<T, E>444 fn ok_or<T, E>(t: Option<T>, e: E) -> Result<T, E> {
445 match t {
446 Some(t) => Ok(t),
447 None => Err(e),
448 }
449 }
450
451 // Reimplemented here because std::ascii is not available in libcore
eq_ignore_ascii_case(a: &str, b: &str) -> bool452 fn eq_ignore_ascii_case(a: &str, b: &str) -> bool {
453 fn to_ascii_uppercase(c: u8) -> u8 {
454 if c >= b'a' && c <= b'z' {
455 c - b'a' + b'A'
456 } else {
457 c
458 }
459 }
460
461 if a.len() == b.len() {
462 a.bytes()
463 .zip(b.bytes())
464 .all(|(a, b)| to_ascii_uppercase(a) == to_ascii_uppercase(b))
465 } else {
466 false
467 }
468 }
469
470 impl FromStr for Level {
471 type Err = ParseLevelError;
from_str(level: &str) -> Result<Level, Self::Err>472 fn from_str(level: &str) -> Result<Level, Self::Err> {
473 ok_or(
474 LOG_LEVEL_NAMES
475 .iter()
476 .position(|&name| eq_ignore_ascii_case(name, level))
477 .into_iter()
478 .filter(|&idx| idx != 0)
479 .map(|idx| Level::from_usize(idx).unwrap())
480 .next(),
481 ParseLevelError(()),
482 )
483 }
484 }
485
486 impl fmt::Display for Level {
fmt(&self, fmt: &mut fmt::Formatter) -> fmt::Result487 fn fmt(&self, fmt: &mut fmt::Formatter) -> fmt::Result {
488 fmt.pad(LOG_LEVEL_NAMES[*self as usize])
489 }
490 }
491
492 impl Level {
from_usize(u: usize) -> Option<Level>493 fn from_usize(u: usize) -> Option<Level> {
494 match u {
495 1 => Some(Level::Error),
496 2 => Some(Level::Warn),
497 3 => Some(Level::Info),
498 4 => Some(Level::Debug),
499 5 => Some(Level::Trace),
500 _ => None,
501 }
502 }
503
504 /// Returns the most verbose logging level.
505 #[inline]
max() -> Level506 pub fn max() -> Level {
507 Level::Trace
508 }
509
510 /// Converts the `Level` to the equivalent `LevelFilter`.
511 #[inline]
to_level_filter(&self) -> LevelFilter512 pub fn to_level_filter(&self) -> LevelFilter {
513 LevelFilter::from_usize(*self as usize).unwrap()
514 }
515 }
516
517 /// An enum representing the available verbosity level filters of the logger.
518 ///
519 /// A `LevelFilter` may be compared directly to a [`Level`]. Use this type
520 /// to get and set the maximum log level with [`max_level()`] and [`set_max_level`].
521 ///
522 /// [`Level`]: enum.Level.html
523 /// [`max_level()`]: fn.max_level.html
524 /// [`set_max_level`]: fn.set_max_level.html
525 #[repr(usize)]
526 #[derive(Copy, Eq, Debug, Hash)]
527 pub enum LevelFilter {
528 /// A level lower than all log levels.
529 Off,
530 /// Corresponds to the `Error` log level.
531 Error,
532 /// Corresponds to the `Warn` log level.
533 Warn,
534 /// Corresponds to the `Info` log level.
535 Info,
536 /// Corresponds to the `Debug` log level.
537 Debug,
538 /// Corresponds to the `Trace` log level.
539 Trace,
540 }
541
542 // Deriving generates terrible impls of these traits
543
544 impl Clone for LevelFilter {
545 #[inline]
clone(&self) -> LevelFilter546 fn clone(&self) -> LevelFilter {
547 *self
548 }
549 }
550
551 impl PartialEq for LevelFilter {
552 #[inline]
eq(&self, other: &LevelFilter) -> bool553 fn eq(&self, other: &LevelFilter) -> bool {
554 *self as usize == *other as usize
555 }
556 }
557
558 impl PartialEq<Level> for LevelFilter {
559 #[inline]
eq(&self, other: &Level) -> bool560 fn eq(&self, other: &Level) -> bool {
561 other.eq(self)
562 }
563 }
564
565 impl PartialOrd for LevelFilter {
566 #[inline]
partial_cmp(&self, other: &LevelFilter) -> Option<cmp::Ordering>567 fn partial_cmp(&self, other: &LevelFilter) -> Option<cmp::Ordering> {
568 Some(self.cmp(other))
569 }
570
571 #[inline]
lt(&self, other: &LevelFilter) -> bool572 fn lt(&self, other: &LevelFilter) -> bool {
573 (*self as usize) < *other as usize
574 }
575
576 #[inline]
le(&self, other: &LevelFilter) -> bool577 fn le(&self, other: &LevelFilter) -> bool {
578 *self as usize <= *other as usize
579 }
580
581 #[inline]
gt(&self, other: &LevelFilter) -> bool582 fn gt(&self, other: &LevelFilter) -> bool {
583 *self as usize > *other as usize
584 }
585
586 #[inline]
ge(&self, other: &LevelFilter) -> bool587 fn ge(&self, other: &LevelFilter) -> bool {
588 *self as usize >= *other as usize
589 }
590 }
591
592 impl PartialOrd<Level> for LevelFilter {
593 #[inline]
partial_cmp(&self, other: &Level) -> Option<cmp::Ordering>594 fn partial_cmp(&self, other: &Level) -> Option<cmp::Ordering> {
595 Some((*self as usize).cmp(&(*other as usize)))
596 }
597
598 #[inline]
lt(&self, other: &Level) -> bool599 fn lt(&self, other: &Level) -> bool {
600 (*self as usize) < *other as usize
601 }
602
603 #[inline]
le(&self, other: &Level) -> bool604 fn le(&self, other: &Level) -> bool {
605 *self as usize <= *other as usize
606 }
607
608 #[inline]
gt(&self, other: &Level) -> bool609 fn gt(&self, other: &Level) -> bool {
610 *self as usize > *other as usize
611 }
612
613 #[inline]
ge(&self, other: &Level) -> bool614 fn ge(&self, other: &Level) -> bool {
615 *self as usize >= *other as usize
616 }
617 }
618
619 impl Ord for LevelFilter {
620 #[inline]
cmp(&self, other: &LevelFilter) -> cmp::Ordering621 fn cmp(&self, other: &LevelFilter) -> cmp::Ordering {
622 (*self as usize).cmp(&(*other as usize))
623 }
624 }
625
626 impl FromStr for LevelFilter {
627 type Err = ParseLevelError;
from_str(level: &str) -> Result<LevelFilter, Self::Err>628 fn from_str(level: &str) -> Result<LevelFilter, Self::Err> {
629 ok_or(
630 LOG_LEVEL_NAMES
631 .iter()
632 .position(|&name| eq_ignore_ascii_case(name, level))
633 .map(|p| LevelFilter::from_usize(p).unwrap()),
634 ParseLevelError(()),
635 )
636 }
637 }
638
639 impl fmt::Display for LevelFilter {
fmt(&self, fmt: &mut fmt::Formatter) -> fmt::Result640 fn fmt(&self, fmt: &mut fmt::Formatter) -> fmt::Result {
641 fmt.pad(LOG_LEVEL_NAMES[*self as usize])
642 }
643 }
644
645 impl LevelFilter {
from_usize(u: usize) -> Option<LevelFilter>646 fn from_usize(u: usize) -> Option<LevelFilter> {
647 match u {
648 0 => Some(LevelFilter::Off),
649 1 => Some(LevelFilter::Error),
650 2 => Some(LevelFilter::Warn),
651 3 => Some(LevelFilter::Info),
652 4 => Some(LevelFilter::Debug),
653 5 => Some(LevelFilter::Trace),
654 _ => None,
655 }
656 }
657 /// Returns the most verbose logging level filter.
658 #[inline]
max() -> LevelFilter659 pub fn max() -> LevelFilter {
660 LevelFilter::Trace
661 }
662
663 /// Converts `self` to the equivalent `Level`.
664 ///
665 /// Returns `None` if `self` is `LevelFilter::Off`.
666 #[inline]
to_level(&self) -> Option<Level>667 pub fn to_level(&self) -> Option<Level> {
668 Level::from_usize(*self as usize)
669 }
670 }
671
672 #[derive(Copy, Clone, Eq, PartialEq, Ord, PartialOrd, Hash, Debug)]
673 enum MaybeStaticStr<'a> {
674 Static(&'static str),
675 Borrowed(&'a str),
676 }
677
678 impl<'a> MaybeStaticStr<'a> {
679 #[inline]
get(&self) -> &'a str680 fn get(&self) -> &'a str {
681 match *self {
682 MaybeStaticStr::Static(s) => s,
683 MaybeStaticStr::Borrowed(s) => s,
684 }
685 }
686 }
687
688 /// The "payload" of a log message.
689 ///
690 /// # Use
691 ///
692 /// `Record` structures are passed as parameters to the [`log`][method.log]
693 /// method of the [`Log`] trait. Logger implementors manipulate these
694 /// structures in order to display log messages. `Record`s are automatically
695 /// created by the [`log!`] macro and so are not seen by log users.
696 ///
697 /// Note that the [`level()`] and [`target()`] accessors are equivalent to
698 /// `self.metadata().level()` and `self.metadata().target()` respectively.
699 /// These methods are provided as a convenience for users of this structure.
700 ///
701 /// # Example
702 ///
703 /// The following example shows a simple logger that displays the level,
704 /// module path, and message of any `Record` that is passed to it.
705 ///
706 /// ```edition2018
707 /// struct SimpleLogger;
708 ///
709 /// impl log::Log for SimpleLogger {
710 /// fn enabled(&self, metadata: &log::Metadata) -> bool {
711 /// true
712 /// }
713 ///
714 /// fn log(&self, record: &log::Record) {
715 /// if !self.enabled(record.metadata()) {
716 /// return;
717 /// }
718 ///
719 /// println!("{}:{} -- {}",
720 /// record.level(),
721 /// record.target(),
722 /// record.args());
723 /// }
724 /// fn flush(&self) {}
725 /// }
726 /// ```
727 ///
728 /// [method.log]: trait.Log.html#tymethod.log
729 /// [`Log`]: trait.Log.html
730 /// [`log!`]: macro.log.html
731 /// [`level()`]: struct.Record.html#method.level
732 /// [`target()`]: struct.Record.html#method.target
733 #[derive(Clone, Debug)]
734 pub struct Record<'a> {
735 metadata: Metadata<'a>,
736 args: fmt::Arguments<'a>,
737 module_path: Option<MaybeStaticStr<'a>>,
738 file: Option<MaybeStaticStr<'a>>,
739 line: Option<u32>,
740 #[cfg(feature = "kv_unstable")]
741 key_values: KeyValues<'a>,
742 }
743
744 // This wrapper type is only needed so we can
745 // `#[derive(Debug)]` on `Record`. It also
746 // provides a useful `Debug` implementation for
747 // the underlying `Source`.
748 #[cfg(feature = "kv_unstable")]
749 #[derive(Clone)]
750 struct KeyValues<'a>(&'a kv::Source);
751
752 #[cfg(feature = "kv_unstable")]
753 impl<'a> fmt::Debug for KeyValues<'a> {
fmt(&self, f: &mut fmt::Formatter) -> fmt::Result754 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
755 let mut visitor = f.debug_map();
756 self.0.visit(&mut visitor)?;
757 visitor.finish()
758 }
759 }
760
761 impl<'a> Record<'a> {
762 /// Returns a new builder.
763 #[inline]
builder() -> RecordBuilder<'a>764 pub fn builder() -> RecordBuilder<'a> {
765 RecordBuilder::new()
766 }
767
768 /// The message body.
769 #[inline]
args(&self) -> &fmt::Arguments<'a>770 pub fn args(&self) -> &fmt::Arguments<'a> {
771 &self.args
772 }
773
774 /// Metadata about the log directive.
775 #[inline]
metadata(&self) -> &Metadata<'a>776 pub fn metadata(&self) -> &Metadata<'a> {
777 &self.metadata
778 }
779
780 /// The verbosity level of the message.
781 #[inline]
level(&self) -> Level782 pub fn level(&self) -> Level {
783 self.metadata.level()
784 }
785
786 /// The name of the target of the directive.
787 #[inline]
target(&self) -> &'a str788 pub fn target(&self) -> &'a str {
789 self.metadata.target()
790 }
791
792 /// The module path of the message.
793 #[inline]
module_path(&self) -> Option<&'a str>794 pub fn module_path(&self) -> Option<&'a str> {
795 self.module_path.map(|s| s.get())
796 }
797
798 /// The module path of the message, if it is a `'static` string.
799 #[inline]
module_path_static(&self) -> Option<&'static str>800 pub fn module_path_static(&self) -> Option<&'static str> {
801 match self.module_path {
802 Some(MaybeStaticStr::Static(s)) => Some(s),
803 _ => None,
804 }
805 }
806
807 /// The source file containing the message.
808 #[inline]
file(&self) -> Option<&'a str>809 pub fn file(&self) -> Option<&'a str> {
810 self.file.map(|s| s.get())
811 }
812
813 /// The module path of the message, if it is a `'static` string.
814 #[inline]
file_static(&self) -> Option<&'static str>815 pub fn file_static(&self) -> Option<&'static str> {
816 match self.file {
817 Some(MaybeStaticStr::Static(s)) => Some(s),
818 _ => None,
819 }
820 }
821
822 /// The line containing the message.
823 #[inline]
line(&self) -> Option<u32>824 pub fn line(&self) -> Option<u32> {
825 self.line
826 }
827
828 /// The structued key-value pairs associated with the message.
829 #[cfg(feature = "kv_unstable")]
830 #[inline]
key_values(&self) -> &kv::Source831 pub fn key_values(&self) -> &kv::Source {
832 self.key_values.0
833 }
834
835 /// Create a new [`Builder`](struct.Builder.html) based on this record.
836 #[cfg(feature = "kv_unstable")]
837 #[inline]
to_builder(&self) -> RecordBuilder838 pub fn to_builder(&self) -> RecordBuilder {
839 RecordBuilder {
840 record: Record {
841 metadata: Metadata {
842 level: self.metadata.level,
843 target: self.metadata.target,
844 },
845 args: self.args,
846 module_path: self.module_path,
847 file: self.file,
848 line: self.line,
849 key_values: self.key_values.clone(),
850 }
851 }
852 }
853 }
854
855 /// Builder for [`Record`](struct.Record.html).
856 ///
857 /// Typically should only be used by log library creators or for testing and "shim loggers".
858 /// The `RecordBuilder` can set the different parameters of `Record` object, and returns
859 /// the created object when `build` is called.
860 ///
861 /// # Examples
862 ///
863 ///
864 /// ```edition2018
865 /// use log::{Level, Record};
866 ///
867 /// let record = Record::builder()
868 /// .args(format_args!("Error!"))
869 /// .level(Level::Error)
870 /// .target("myApp")
871 /// .file(Some("server.rs"))
872 /// .line(Some(144))
873 /// .module_path(Some("server"))
874 /// .build();
875 /// ```
876 ///
877 /// Alternatively, use [`MetadataBuilder`](struct.MetadataBuilder.html):
878 ///
879 /// ```edition2018
880 /// use log::{Record, Level, MetadataBuilder};
881 ///
882 /// let error_metadata = MetadataBuilder::new()
883 /// .target("myApp")
884 /// .level(Level::Error)
885 /// .build();
886 ///
887 /// let record = Record::builder()
888 /// .metadata(error_metadata)
889 /// .args(format_args!("Error!"))
890 /// .line(Some(433))
891 /// .file(Some("app.rs"))
892 /// .module_path(Some("server"))
893 /// .build();
894 /// ```
895 #[derive(Debug)]
896 pub struct RecordBuilder<'a> {
897 record: Record<'a>,
898 }
899
900 impl<'a> RecordBuilder<'a> {
901 /// Construct new `RecordBuilder`.
902 ///
903 /// The default options are:
904 ///
905 /// - `args`: [`format_args!("")`]
906 /// - `metadata`: [`Metadata::builder().build()`]
907 /// - `module_path`: `None`
908 /// - `file`: `None`
909 /// - `line`: `None`
910 ///
911 /// [`format_args!("")`]: https://doc.rust-lang.org/std/macro.format_args.html
912 /// [`Metadata::builder().build()`]: struct.MetadataBuilder.html#method.build
913 #[inline]
new() -> RecordBuilder<'a>914 pub fn new() -> RecordBuilder<'a> {
915 #[cfg(feature = "kv_unstable")]
916 return RecordBuilder {
917 record: Record {
918 args: format_args!(""),
919 metadata: Metadata::builder().build(),
920 module_path: None,
921 file: None,
922 line: None,
923 key_values: KeyValues(&Option::None::<(kv::Key, kv::Value)>),
924 },
925 };
926
927 #[cfg(not(feature = "kv_unstable"))]
928 return RecordBuilder {
929 record: Record {
930 args: format_args!(""),
931 metadata: Metadata::builder().build(),
932 module_path: None,
933 file: None,
934 line: None,
935 },
936 };
937 }
938
939 /// Set [`args`](struct.Record.html#method.args).
940 #[inline]
args(&mut self, args: fmt::Arguments<'a>) -> &mut RecordBuilder<'a>941 pub fn args(&mut self, args: fmt::Arguments<'a>) -> &mut RecordBuilder<'a> {
942 self.record.args = args;
943 self
944 }
945
946 /// Set [`metadata`](struct.Record.html#method.metadata). Construct a `Metadata` object with [`MetadataBuilder`](struct.MetadataBuilder.html).
947 #[inline]
metadata(&mut self, metadata: Metadata<'a>) -> &mut RecordBuilder<'a>948 pub fn metadata(&mut self, metadata: Metadata<'a>) -> &mut RecordBuilder<'a> {
949 self.record.metadata = metadata;
950 self
951 }
952
953 /// Set [`Metadata::level`](struct.Metadata.html#method.level).
954 #[inline]
level(&mut self, level: Level) -> &mut RecordBuilder<'a>955 pub fn level(&mut self, level: Level) -> &mut RecordBuilder<'a> {
956 self.record.metadata.level = level;
957 self
958 }
959
960 /// Set [`Metadata::target`](struct.Metadata.html#method.target)
961 #[inline]
target(&mut self, target: &'a str) -> &mut RecordBuilder<'a>962 pub fn target(&mut self, target: &'a str) -> &mut RecordBuilder<'a> {
963 self.record.metadata.target = target;
964 self
965 }
966
967 /// Set [`module_path`](struct.Record.html#method.module_path)
968 #[inline]
module_path(&mut self, path: Option<&'a str>) -> &mut RecordBuilder<'a>969 pub fn module_path(&mut self, path: Option<&'a str>) -> &mut RecordBuilder<'a> {
970 self.record.module_path = path.map(MaybeStaticStr::Borrowed);
971 self
972 }
973
974 /// Set [`module_path`](struct.Record.html#method.module_path) to a `'static` string
975 #[inline]
module_path_static(&mut self, path: Option<&'static str>) -> &mut RecordBuilder<'a>976 pub fn module_path_static(&mut self, path: Option<&'static str>) -> &mut RecordBuilder<'a> {
977 self.record.module_path = path.map(MaybeStaticStr::Static);
978 self
979 }
980
981 /// Set [`file`](struct.Record.html#method.file)
982 #[inline]
file(&mut self, file: Option<&'a str>) -> &mut RecordBuilder<'a>983 pub fn file(&mut self, file: Option<&'a str>) -> &mut RecordBuilder<'a> {
984 self.record.file = file.map(MaybeStaticStr::Borrowed);
985 self
986 }
987
988 /// Set [`file`](struct.Record.html#method.file) to a `'static` string.
989 #[inline]
file_static(&mut self, file: Option<&'static str>) -> &mut RecordBuilder<'a>990 pub fn file_static(&mut self, file: Option<&'static str>) -> &mut RecordBuilder<'a> {
991 self.record.file = file.map(MaybeStaticStr::Static);
992 self
993 }
994
995 /// Set [`line`](struct.Record.html#method.line)
996 #[inline]
line(&mut self, line: Option<u32>) -> &mut RecordBuilder<'a>997 pub fn line(&mut self, line: Option<u32>) -> &mut RecordBuilder<'a> {
998 self.record.line = line;
999 self
1000 }
1001
1002 /// Set [`key_values`](struct.Record.html#method.key_values)
1003 #[cfg(feature = "kv_unstable")]
1004 #[inline]
key_values(&mut self, kvs: &'a kv::Source) -> &mut RecordBuilder<'a>1005 pub fn key_values(&mut self, kvs: &'a kv::Source) -> &mut RecordBuilder<'a> {
1006 self.record.key_values = KeyValues(kvs);
1007 self
1008 }
1009
1010 /// Invoke the builder and return a `Record`
1011 #[inline]
build(&self) -> Record<'a>1012 pub fn build(&self) -> Record<'a> {
1013 self.record.clone()
1014 }
1015 }
1016
1017 /// Metadata about a log message.
1018 ///
1019 /// # Use
1020 ///
1021 /// `Metadata` structs are created when users of the library use
1022 /// logging macros.
1023 ///
1024 /// They are consumed by implementations of the `Log` trait in the
1025 /// `enabled` method.
1026 ///
1027 /// `Record`s use `Metadata` to determine the log message's severity
1028 /// and target.
1029 ///
1030 /// Users should use the `log_enabled!` macro in their code to avoid
1031 /// constructing expensive log messages.
1032 ///
1033 /// # Examples
1034 ///
1035 /// ```edition2018
1036 /// use log::{Record, Level, Metadata};
1037 ///
1038 /// struct MyLogger;
1039 ///
1040 /// impl log::Log for MyLogger {
1041 /// fn enabled(&self, metadata: &Metadata) -> bool {
1042 /// metadata.level() <= Level::Info
1043 /// }
1044 ///
1045 /// fn log(&self, record: &Record) {
1046 /// if self.enabled(record.metadata()) {
1047 /// println!("{} - {}", record.level(), record.args());
1048 /// }
1049 /// }
1050 /// fn flush(&self) {}
1051 /// }
1052 ///
1053 /// # fn main(){}
1054 /// ```
1055 #[derive(Clone, Eq, PartialEq, Ord, PartialOrd, Hash, Debug)]
1056 pub struct Metadata<'a> {
1057 level: Level,
1058 target: &'a str,
1059 }
1060
1061 impl<'a> Metadata<'a> {
1062 /// Returns a new builder.
1063 #[inline]
builder() -> MetadataBuilder<'a>1064 pub fn builder() -> MetadataBuilder<'a> {
1065 MetadataBuilder::new()
1066 }
1067
1068 /// The verbosity level of the message.
1069 #[inline]
level(&self) -> Level1070 pub fn level(&self) -> Level {
1071 self.level
1072 }
1073
1074 /// The name of the target of the directive.
1075 #[inline]
target(&self) -> &'a str1076 pub fn target(&self) -> &'a str {
1077 self.target
1078 }
1079 }
1080
1081 /// Builder for [`Metadata`](struct.Metadata.html).
1082 ///
1083 /// Typically should only be used by log library creators or for testing and "shim loggers".
1084 /// The `MetadataBuilder` can set the different parameters of a `Metadata` object, and returns
1085 /// the created object when `build` is called.
1086 ///
1087 /// # Example
1088 ///
1089 /// ```edition2018
1090 /// let target = "myApp";
1091 /// use log::{Level, MetadataBuilder};
1092 /// let metadata = MetadataBuilder::new()
1093 /// .level(Level::Debug)
1094 /// .target(target)
1095 /// .build();
1096 /// ```
1097 #[derive(Eq, PartialEq, Ord, PartialOrd, Hash, Debug)]
1098 pub struct MetadataBuilder<'a> {
1099 metadata: Metadata<'a>,
1100 }
1101
1102 impl<'a> MetadataBuilder<'a> {
1103 /// Construct a new `MetadataBuilder`.
1104 ///
1105 /// The default options are:
1106 ///
1107 /// - `level`: `Level::Info`
1108 /// - `target`: `""`
1109 #[inline]
new() -> MetadataBuilder<'a>1110 pub fn new() -> MetadataBuilder<'a> {
1111 MetadataBuilder {
1112 metadata: Metadata {
1113 level: Level::Info,
1114 target: "",
1115 },
1116 }
1117 }
1118
1119 /// Setter for [`level`](struct.Metadata.html#method.level).
1120 #[inline]
level(&mut self, arg: Level) -> &mut MetadataBuilder<'a>1121 pub fn level(&mut self, arg: Level) -> &mut MetadataBuilder<'a> {
1122 self.metadata.level = arg;
1123 self
1124 }
1125
1126 /// Setter for [`target`](struct.Metadata.html#method.target).
1127 #[inline]
target(&mut self, target: &'a str) -> &mut MetadataBuilder<'a>1128 pub fn target(&mut self, target: &'a str) -> &mut MetadataBuilder<'a> {
1129 self.metadata.target = target;
1130 self
1131 }
1132
1133 /// Returns a `Metadata` object.
1134 #[inline]
build(&self) -> Metadata<'a>1135 pub fn build(&self) -> Metadata<'a> {
1136 self.metadata.clone()
1137 }
1138 }
1139
1140 /// A trait encapsulating the operations required of a logger.
1141 pub trait Log: Sync + Send {
1142 /// Determines if a log message with the specified metadata would be
1143 /// logged.
1144 ///
1145 /// This is used by the `log_enabled!` macro to allow callers to avoid
1146 /// expensive computation of log message arguments if the message would be
1147 /// discarded anyway.
enabled(&self, metadata: &Metadata) -> bool1148 fn enabled(&self, metadata: &Metadata) -> bool;
1149
1150 /// Logs the `Record`.
1151 ///
1152 /// Note that `enabled` is *not* necessarily called before this method.
1153 /// Implementations of `log` should perform all necessary filtering
1154 /// internally.
log(&self, record: &Record)1155 fn log(&self, record: &Record);
1156
1157 /// Flushes any buffered records.
flush(&self)1158 fn flush(&self);
1159 }
1160
1161 // Just used as a dummy initial value for LOGGER
1162 struct NopLogger;
1163
1164 impl Log for NopLogger {
enabled(&self, _: &Metadata) -> bool1165 fn enabled(&self, _: &Metadata) -> bool {
1166 false
1167 }
1168
log(&self, _: &Record)1169 fn log(&self, _: &Record) {}
flush(&self)1170 fn flush(&self) {}
1171 }
1172
1173 /// Sets the global maximum log level.
1174 ///
1175 /// Generally, this should only be called by the active logging implementation.
1176 #[inline]
set_max_level(level: LevelFilter)1177 pub fn set_max_level(level: LevelFilter) {
1178 MAX_LOG_LEVEL_FILTER.store(level as usize, Ordering::SeqCst)
1179 }
1180
1181 /// Returns the current maximum log level.
1182 ///
1183 /// The [`log!`], [`error!`], [`warn!`], [`info!`], [`debug!`], and [`trace!`] macros check
1184 /// this value and discard any message logged at a higher level. The maximum
1185 /// log level is set by the [`set_max_level`] function.
1186 ///
1187 /// [`log!`]: macro.log.html
1188 /// [`error!`]: macro.error.html
1189 /// [`warn!`]: macro.warn.html
1190 /// [`info!`]: macro.info.html
1191 /// [`debug!`]: macro.debug.html
1192 /// [`trace!`]: macro.trace.html
1193 /// [`set_max_level`]: fn.set_max_level.html
1194 #[inline(always)]
max_level() -> LevelFilter1195 pub fn max_level() -> LevelFilter {
1196 unsafe { mem::transmute(MAX_LOG_LEVEL_FILTER.load(Ordering::Relaxed)) }
1197 }
1198
1199 /// Sets the global logger to a `Box<Log>`.
1200 ///
1201 /// This is a simple convenience wrapper over `set_logger`, which takes a
1202 /// `Box<Log>` rather than a `&'static Log`. See the documentation for
1203 /// [`set_logger`] for more details.
1204 ///
1205 /// Requires the `std` feature.
1206 ///
1207 /// # Errors
1208 ///
1209 /// An error is returned if a logger has already been set.
1210 ///
1211 /// [`set_logger`]: fn.set_logger.html
1212 #[cfg(all(feature = "std", atomic_cas))]
set_boxed_logger(logger: Box<Log>) -> Result<(), SetLoggerError>1213 pub fn set_boxed_logger(logger: Box<Log>) -> Result<(), SetLoggerError> {
1214 set_logger_inner(|| unsafe { &*Box::into_raw(logger) })
1215 }
1216
1217 /// Sets the global logger to a `&'static Log`.
1218 ///
1219 /// This function may only be called once in the lifetime of a program. Any log
1220 /// events that occur before the call to `set_logger` completes will be ignored.
1221 ///
1222 /// This function does not typically need to be called manually. Logger
1223 /// implementations should provide an initialization method that installs the
1224 /// logger internally.
1225 ///
1226 /// # Availability
1227 ///
1228 /// This method is available even when the `std` feature is disabled. However,
1229 /// it is currently unavailable on `thumbv6` targets, which lack support for
1230 /// some atomic operations which are used by this function. Even on those
1231 /// targets, [`set_logger_racy`] will be available.
1232 ///
1233 /// # Errors
1234 ///
1235 /// An error is returned if a logger has already been set.
1236 ///
1237 /// # Examples
1238 ///
1239 /// ```edition2018
1240 /// use log::{error, info, warn, Record, Level, Metadata, LevelFilter};
1241 ///
1242 /// static MY_LOGGER: MyLogger = MyLogger;
1243 ///
1244 /// struct MyLogger;
1245 ///
1246 /// impl log::Log for MyLogger {
1247 /// fn enabled(&self, metadata: &Metadata) -> bool {
1248 /// metadata.level() <= Level::Info
1249 /// }
1250 ///
1251 /// fn log(&self, record: &Record) {
1252 /// if self.enabled(record.metadata()) {
1253 /// println!("{} - {}", record.level(), record.args());
1254 /// }
1255 /// }
1256 /// fn flush(&self) {}
1257 /// }
1258 ///
1259 /// # fn main(){
1260 /// log::set_logger(&MY_LOGGER).unwrap();
1261 /// log::set_max_level(LevelFilter::Info);
1262 ///
1263 /// info!("hello log");
1264 /// warn!("warning");
1265 /// error!("oops");
1266 /// # }
1267 /// ```
1268 ///
1269 /// [`set_logger_racy`]: fn.set_logger_racy.html
1270 #[cfg(atomic_cas)]
set_logger(logger: &'static Log) -> Result<(), SetLoggerError>1271 pub fn set_logger(logger: &'static Log) -> Result<(), SetLoggerError> {
1272 set_logger_inner(|| logger)
1273 }
1274
1275 #[cfg(atomic_cas)]
set_logger_inner<F>(make_logger: F) -> Result<(), SetLoggerError> where F: FnOnce() -> &'static Log,1276 fn set_logger_inner<F>(make_logger: F) -> Result<(), SetLoggerError>
1277 where
1278 F: FnOnce() -> &'static Log,
1279 {
1280 unsafe {
1281 match STATE.compare_and_swap(UNINITIALIZED, INITIALIZING, Ordering::SeqCst) {
1282 UNINITIALIZED => {
1283 LOGGER = make_logger();
1284 STATE.store(INITIALIZED, Ordering::SeqCst);
1285 Ok(())
1286 }
1287 INITIALIZING => {
1288 while STATE.load(Ordering::SeqCst) == INITIALIZING {}
1289 Err(SetLoggerError(()))
1290 }
1291 _ => Err(SetLoggerError(())),
1292 }
1293 }
1294 }
1295
1296 /// A thread-unsafe version of [`set_logger`].
1297 ///
1298 /// This function is available on all platforms, even those that do not have
1299 /// support for atomics that is needed by [`set_logger`].
1300 ///
1301 /// In almost all cases, [`set_logger`] should be preferred.
1302 ///
1303 /// # Safety
1304 ///
1305 /// This function is only safe to call when no other logger initialization
1306 /// function is called while this function still executes.
1307 ///
1308 /// This can be upheld by (for example) making sure that **there are no other
1309 /// threads**, and (on embedded) that **interrupts are disabled**.
1310 ///
1311 /// It is safe to use other logging functions while this function runs
1312 /// (including all logging macros).
1313 ///
1314 /// [`set_logger`]: fn.set_logger.html
set_logger_racy(logger: &'static Log) -> Result<(), SetLoggerError>1315 pub unsafe fn set_logger_racy(logger: &'static Log) -> Result<(), SetLoggerError> {
1316 match STATE.load(Ordering::SeqCst) {
1317 UNINITIALIZED => {
1318 LOGGER = logger;
1319 STATE.store(INITIALIZED, Ordering::SeqCst);
1320 Ok(())
1321 }
1322 INITIALIZING => {
1323 // This is just plain UB, since we were racing another initialization function
1324 unreachable!("set_logger_racy must not be used with other initialization functions")
1325 }
1326 _ => Err(SetLoggerError(())),
1327 }
1328 }
1329
1330 /// The type returned by [`set_logger`] if [`set_logger`] has already been called.
1331 ///
1332 /// [`set_logger`]: fn.set_logger.html
1333 #[allow(missing_copy_implementations)]
1334 #[derive(Debug)]
1335 pub struct SetLoggerError(());
1336
1337 impl fmt::Display for SetLoggerError {
fmt(&self, fmt: &mut fmt::Formatter) -> fmt::Result1338 fn fmt(&self, fmt: &mut fmt::Formatter) -> fmt::Result {
1339 fmt.write_str(SET_LOGGER_ERROR)
1340 }
1341 }
1342
1343 // The Error trait is not available in libcore
1344 #[cfg(feature = "std")]
1345 impl error::Error for SetLoggerError {
description(&self) -> &str1346 fn description(&self) -> &str {
1347 SET_LOGGER_ERROR
1348 }
1349 }
1350
1351 /// The type returned by [`from_str`] when the string doesn't match any of the log levels.
1352 ///
1353 /// [`from_str`]: https://doc.rust-lang.org/std/str/trait.FromStr.html#tymethod.from_str
1354 #[allow(missing_copy_implementations)]
1355 #[derive(Debug, PartialEq)]
1356 pub struct ParseLevelError(());
1357
1358 impl fmt::Display for ParseLevelError {
fmt(&self, fmt: &mut fmt::Formatter) -> fmt::Result1359 fn fmt(&self, fmt: &mut fmt::Formatter) -> fmt::Result {
1360 fmt.write_str(LEVEL_PARSE_ERROR)
1361 }
1362 }
1363
1364 // The Error trait is not available in libcore
1365 #[cfg(feature = "std")]
1366 impl error::Error for ParseLevelError {
description(&self) -> &str1367 fn description(&self) -> &str {
1368 LEVEL_PARSE_ERROR
1369 }
1370 }
1371
1372 /// Returns a reference to the logger.
1373 ///
1374 /// If a logger has not been set, a no-op implementation is returned.
logger() -> &'static Log1375 pub fn logger() -> &'static Log {
1376 unsafe {
1377 if STATE.load(Ordering::SeqCst) != INITIALIZED {
1378 static NOP: NopLogger = NopLogger;
1379 &NOP
1380 } else {
1381 LOGGER
1382 }
1383 }
1384 }
1385
1386 // WARNING: this is not part of the crate's public API and is subject to change at any time
1387 #[doc(hidden)]
__private_api_log( args: fmt::Arguments, level: Level, &(target, module_path, file, line): &(&str, &'static str, &'static str, u32), )1388 pub fn __private_api_log(
1389 args: fmt::Arguments,
1390 level: Level,
1391 &(target, module_path, file, line): &(&str, &'static str, &'static str, u32),
1392 ) {
1393 logger().log(
1394 &Record::builder()
1395 .args(args)
1396 .level(level)
1397 .target(target)
1398 .module_path_static(Some(module_path))
1399 .file_static(Some(file))
1400 .line(Some(line))
1401 .build(),
1402 );
1403 }
1404
1405 // WARNING: this is not part of the crate's public API and is subject to change at any time
1406 #[doc(hidden)]
__private_api_enabled(level: Level, target: &str) -> bool1407 pub fn __private_api_enabled(level: Level, target: &str) -> bool {
1408 logger().enabled(&Metadata::builder().level(level).target(target).build())
1409 }
1410
1411 /// The statically resolved maximum log level.
1412 ///
1413 /// See the crate level documentation for information on how to configure this.
1414 ///
1415 /// This value is checked by the log macros, but not by the `Log`ger returned by
1416 /// the [`logger`] function. Code that manually calls functions on that value
1417 /// should compare the level against this value.
1418 ///
1419 /// [`logger`]: fn.logger.html
1420 pub const STATIC_MAX_LEVEL: LevelFilter = MAX_LEVEL_INNER;
1421
1422 cfg_if! {
1423 if #[cfg(all(not(debug_assertions), feature = "release_max_level_off"))] {
1424 const MAX_LEVEL_INNER: LevelFilter = LevelFilter::Off;
1425 } else if #[cfg(all(not(debug_assertions), feature = "release_max_level_error"))] {
1426 const MAX_LEVEL_INNER: LevelFilter = LevelFilter::Error;
1427 } else if #[cfg(all(not(debug_assertions), feature = "release_max_level_warn"))] {
1428 const MAX_LEVEL_INNER: LevelFilter = LevelFilter::Warn;
1429 } else if #[cfg(all(not(debug_assertions), feature = "release_max_level_info"))] {
1430 const MAX_LEVEL_INNER: LevelFilter = LevelFilter::Info;
1431 } else if #[cfg(all(not(debug_assertions), feature = "release_max_level_debug"))] {
1432 const MAX_LEVEL_INNER: LevelFilter = LevelFilter::Debug;
1433 } else if #[cfg(all(not(debug_assertions), feature = "release_max_level_trace"))] {
1434 const MAX_LEVEL_INNER: LevelFilter = LevelFilter::Trace;
1435 } else if #[cfg(feature = "max_level_off")] {
1436 const MAX_LEVEL_INNER: LevelFilter = LevelFilter::Off;
1437 } else if #[cfg(feature = "max_level_error")] {
1438 const MAX_LEVEL_INNER: LevelFilter = LevelFilter::Error;
1439 } else if #[cfg(feature = "max_level_warn")] {
1440 const MAX_LEVEL_INNER: LevelFilter = LevelFilter::Warn;
1441 } else if #[cfg(feature = "max_level_info")] {
1442 const MAX_LEVEL_INNER: LevelFilter = LevelFilter::Info;
1443 } else if #[cfg(feature = "max_level_debug")] {
1444 const MAX_LEVEL_INNER: LevelFilter = LevelFilter::Debug;
1445 } else {
1446 const MAX_LEVEL_INNER: LevelFilter = LevelFilter::Trace;
1447 }
1448 }
1449
1450 #[cfg(test)]
1451 mod tests {
1452 extern crate std;
1453 use super::{Level, LevelFilter, ParseLevelError};
1454 use tests::std::string::ToString;
1455
1456 #[test]
test_levelfilter_from_str()1457 fn test_levelfilter_from_str() {
1458 let tests = [
1459 ("off", Ok(LevelFilter::Off)),
1460 ("error", Ok(LevelFilter::Error)),
1461 ("warn", Ok(LevelFilter::Warn)),
1462 ("info", Ok(LevelFilter::Info)),
1463 ("debug", Ok(LevelFilter::Debug)),
1464 ("trace", Ok(LevelFilter::Trace)),
1465 ("OFF", Ok(LevelFilter::Off)),
1466 ("ERROR", Ok(LevelFilter::Error)),
1467 ("WARN", Ok(LevelFilter::Warn)),
1468 ("INFO", Ok(LevelFilter::Info)),
1469 ("DEBUG", Ok(LevelFilter::Debug)),
1470 ("TRACE", Ok(LevelFilter::Trace)),
1471 ("asdf", Err(ParseLevelError(()))),
1472 ];
1473 for &(s, ref expected) in &tests {
1474 assert_eq!(expected, &s.parse());
1475 }
1476 }
1477
1478 #[test]
test_level_from_str()1479 fn test_level_from_str() {
1480 let tests = [
1481 ("OFF", Err(ParseLevelError(()))),
1482 ("error", Ok(Level::Error)),
1483 ("warn", Ok(Level::Warn)),
1484 ("info", Ok(Level::Info)),
1485 ("debug", Ok(Level::Debug)),
1486 ("trace", Ok(Level::Trace)),
1487 ("ERROR", Ok(Level::Error)),
1488 ("WARN", Ok(Level::Warn)),
1489 ("INFO", Ok(Level::Info)),
1490 ("DEBUG", Ok(Level::Debug)),
1491 ("TRACE", Ok(Level::Trace)),
1492 ("asdf", Err(ParseLevelError(()))),
1493 ];
1494 for &(s, ref expected) in &tests {
1495 assert_eq!(expected, &s.parse());
1496 }
1497 }
1498
1499 #[test]
test_level_show()1500 fn test_level_show() {
1501 assert_eq!("INFO", Level::Info.to_string());
1502 assert_eq!("ERROR", Level::Error.to_string());
1503 }
1504
1505 #[test]
test_levelfilter_show()1506 fn test_levelfilter_show() {
1507 assert_eq!("OFF", LevelFilter::Off.to_string());
1508 assert_eq!("ERROR", LevelFilter::Error.to_string());
1509 }
1510
1511 #[test]
test_cross_cmp()1512 fn test_cross_cmp() {
1513 assert!(Level::Debug > LevelFilter::Error);
1514 assert!(LevelFilter::Warn < Level::Trace);
1515 assert!(LevelFilter::Off < Level::Error);
1516 }
1517
1518 #[test]
test_cross_eq()1519 fn test_cross_eq() {
1520 assert!(Level::Error == LevelFilter::Error);
1521 assert!(LevelFilter::Off != Level::Error);
1522 assert!(Level::Trace == LevelFilter::Trace);
1523 }
1524
1525 #[test]
test_to_level()1526 fn test_to_level() {
1527 assert_eq!(Some(Level::Error), LevelFilter::Error.to_level());
1528 assert_eq!(None, LevelFilter::Off.to_level());
1529 assert_eq!(Some(Level::Debug), LevelFilter::Debug.to_level());
1530 }
1531
1532 #[test]
test_to_level_filter()1533 fn test_to_level_filter() {
1534 assert_eq!(LevelFilter::Error, Level::Error.to_level_filter());
1535 assert_eq!(LevelFilter::Trace, Level::Trace.to_level_filter());
1536 }
1537
1538 #[test]
1539 #[cfg(feature = "std")]
test_error_trait()1540 fn test_error_trait() {
1541 use super::SetLoggerError;
1542 use std::error::Error;
1543 let e = SetLoggerError(());
1544 assert_eq!(
1545 e.description(),
1546 "attempted to set a logger after the logging system \
1547 was already initialized"
1548 );
1549 }
1550
1551 #[test]
test_metadata_builder()1552 fn test_metadata_builder() {
1553 use super::MetadataBuilder;
1554 let target = "myApp";
1555 let metadata_test = MetadataBuilder::new()
1556 .level(Level::Debug)
1557 .target(target)
1558 .build();
1559 assert_eq!(metadata_test.level(), Level::Debug);
1560 assert_eq!(metadata_test.target(), "myApp");
1561 }
1562
1563 #[test]
test_metadata_convenience_builder()1564 fn test_metadata_convenience_builder() {
1565 use super::Metadata;
1566 let target = "myApp";
1567 let metadata_test = Metadata::builder()
1568 .level(Level::Debug)
1569 .target(target)
1570 .build();
1571 assert_eq!(metadata_test.level(), Level::Debug);
1572 assert_eq!(metadata_test.target(), "myApp");
1573 }
1574
1575 #[test]
test_record_builder()1576 fn test_record_builder() {
1577 use super::{MetadataBuilder, RecordBuilder};
1578 let target = "myApp";
1579 let metadata = MetadataBuilder::new().target(target).build();
1580 let fmt_args = format_args!("hello");
1581 let record_test = RecordBuilder::new()
1582 .args(fmt_args)
1583 .metadata(metadata)
1584 .module_path(Some("foo"))
1585 .file(Some("bar"))
1586 .line(Some(30))
1587 .build();
1588 assert_eq!(record_test.metadata().target(), "myApp");
1589 assert_eq!(record_test.module_path(), Some("foo"));
1590 assert_eq!(record_test.file(), Some("bar"));
1591 assert_eq!(record_test.line(), Some(30));
1592 }
1593
1594 #[test]
test_record_convenience_builder()1595 fn test_record_convenience_builder() {
1596 use super::{Metadata, Record};
1597 let target = "myApp";
1598 let metadata = Metadata::builder().target(target).build();
1599 let fmt_args = format_args!("hello");
1600 let record_test = Record::builder()
1601 .args(fmt_args)
1602 .metadata(metadata)
1603 .module_path(Some("foo"))
1604 .file(Some("bar"))
1605 .line(Some(30))
1606 .build();
1607 assert_eq!(record_test.target(), "myApp");
1608 assert_eq!(record_test.module_path(), Some("foo"));
1609 assert_eq!(record_test.file(), Some("bar"));
1610 assert_eq!(record_test.line(), Some(30));
1611 }
1612
1613 #[test]
test_record_complete_builder()1614 fn test_record_complete_builder() {
1615 use super::{Level, Record};
1616 let target = "myApp";
1617 let record_test = Record::builder()
1618 .module_path(Some("foo"))
1619 .file(Some("bar"))
1620 .line(Some(30))
1621 .target(target)
1622 .level(Level::Error)
1623 .build();
1624 assert_eq!(record_test.target(), "myApp");
1625 assert_eq!(record_test.level(), Level::Error);
1626 assert_eq!(record_test.module_path(), Some("foo"));
1627 assert_eq!(record_test.file(), Some("bar"));
1628 assert_eq!(record_test.line(), Some(30));
1629 }
1630
1631 #[test]
1632 #[cfg(feature = "kv_unstable")]
test_record_key_values_builder()1633 fn test_record_key_values_builder() {
1634 use super::Record;
1635 use kv::{self, Visitor};
1636
1637 struct TestVisitor {
1638 seen_pairs: usize,
1639 }
1640
1641 impl<'kvs> Visitor<'kvs> for TestVisitor {
1642 fn visit_pair(
1643 &mut self,
1644 _: kv::Key<'kvs>,
1645 _: kv::Value<'kvs>
1646 ) -> Result<(), kv::Error> {
1647 self.seen_pairs += 1;
1648 Ok(())
1649 }
1650 }
1651
1652 let kvs: &[(&str, i32)] = &[
1653 ("a", 1),
1654 ("b", 2)
1655 ];
1656 let record_test = Record::builder()
1657 .key_values(&kvs)
1658 .build();
1659
1660 let mut visitor = TestVisitor {
1661 seen_pairs: 0,
1662 };
1663
1664 record_test.key_values().visit(&mut visitor).unwrap();
1665
1666 assert_eq!(2, visitor.seen_pairs);
1667 }
1668 }
1669