Coverage Report

Created: 2024-05-21 06:19

/rust/registry/src/index.crates.io-6f17d22bba15001f/log-0.4.21/src/lib.rs
Line
Count
Source (jump to first uncovered line)
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
//! # Usage
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
//! ```
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: {err}, retrying");
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
//! ## Structured logging
90
//!
91
//! If you enable the `kv` feature you can associate structured values
92
//! with your log records. If we take the example from before, we can include
93
//! some additional context besides what's in the formatted message:
94
//!
95
//! ```
96
//! # use serde::Serialize;
97
//! # #[derive(Debug, Serialize)] pub struct Yak(String);
98
//! # impl Yak { fn shave(&mut self, _: u32) {} }
99
//! # fn find_a_razor() -> Result<u32, std::io::Error> { Ok(1) }
100
//! # #[cfg(feature = "kv_serde")]
101
//! # fn main() {
102
//! use log::{info, warn};
103
//!
104
//! pub fn shave_the_yak(yak: &mut Yak) {
105
//!     info!(target: "yak_events", yak:serde; "Commencing yak shaving");
106
//!
107
//!     loop {
108
//!         match find_a_razor() {
109
//!             Ok(razor) => {
110
//!                 info!(razor; "Razor located");
111
//!                 yak.shave(razor);
112
//!                 break;
113
//!             }
114
//!             Err(e) => {
115
//!                 warn!(e:err; "Unable to locate a razor, retrying");
116
//!             }
117
//!         }
118
//!     }
119
//! }
120
//! # }
121
//! # #[cfg(not(feature = "kv_serde"))]
122
//! # fn main() {}
123
//! ```
124
//!
125
//! See the [`kv`] module documentation for more details.
126
//!
127
//! # Available logging implementations
128
//!
129
//! In order to produce log output executables have to use
130
//! a logger implementation compatible with the facade.
131
//! There are many available implementations to choose from,
132
//! here are some of the most popular ones:
133
//!
134
//! * Simple minimal loggers:
135
//!     * [env_logger]
136
//!     * [simple_logger]
137
//!     * [simplelog]
138
//!     * [pretty_env_logger]
139
//!     * [stderrlog]
140
//!     * [flexi_logger]
141
//!     * [call_logger]
142
//!     * [structured-logger]
143
//! * Complex configurable frameworks:
144
//!     * [log4rs]
145
//!     * [fern]
146
//! * Adaptors for other facilities:
147
//!     * [syslog]
148
//!     * [slog-stdlog]
149
//!     * [systemd-journal-logger]
150
//!     * [android_log]
151
//!     * [win_dbg_logger]
152
//!     * [db_logger]
153
//!     * [log-to-defmt]
154
//!     * [logcontrol-log]
155
//! * For WebAssembly binaries:
156
//!     * [console_log]
157
//! * For dynamic libraries:
158
//!     * You may need to construct an FFI-safe wrapper over `log` to initialize in your libraries
159
//! * Utilities:
160
//!     * [log_err]
161
//!     * [log-reload]
162
//!
163
//! # Implementing a Logger
164
//!
165
//! Loggers implement the [`Log`] trait. Here's a very basic example that simply
166
//! logs all messages at the [`Error`][level_link], [`Warn`][level_link] or
167
//! [`Info`][level_link] levels to stdout:
168
//!
169
//! ```
170
//! use log::{Record, Level, Metadata};
171
//!
172
//! struct SimpleLogger;
173
//!
174
//! impl log::Log for SimpleLogger {
175
//!     fn enabled(&self, metadata: &Metadata) -> bool {
176
//!         metadata.level() <= Level::Info
177
//!     }
178
//!
179
//!     fn log(&self, record: &Record) {
180
//!         if self.enabled(record.metadata()) {
181
//!             println!("{} - {}", record.level(), record.args());
182
//!         }
183
//!     }
184
//!
185
//!     fn flush(&self) {}
186
//! }
187
//!
188
//! # fn main() {}
189
//! ```
190
//!
191
//! Loggers are installed by calling the [`set_logger`] function. The maximum
192
//! log level also needs to be adjusted via the [`set_max_level`] function. The
193
//! logging facade uses this as an optimization to improve performance of log
194
//! messages at levels that are disabled. It's important to set it, as it
195
//! defaults to [`Off`][filter_link], so no log messages will ever be captured!
196
//! In the case of our example logger, we'll want to set the maximum log level
197
//! to [`Info`][filter_link], since we ignore any [`Debug`][level_link] or
198
//! [`Trace`][level_link] level log messages. A logging implementation should
199
//! provide a function that wraps a call to [`set_logger`] and
200
//! [`set_max_level`], handling initialization of the logger:
201
//!
202
//! ```
203
//! # use log::{Level, Metadata};
204
//! # struct SimpleLogger;
205
//! # impl log::Log for SimpleLogger {
206
//! #   fn enabled(&self, _: &Metadata) -> bool { false }
207
//! #   fn log(&self, _: &log::Record) {}
208
//! #   fn flush(&self) {}
209
//! # }
210
//! # fn main() {}
211
//! use log::{SetLoggerError, LevelFilter};
212
//!
213
//! static LOGGER: SimpleLogger = SimpleLogger;
214
//!
215
//! pub fn init() -> Result<(), SetLoggerError> {
216
//!     log::set_logger(&LOGGER)
217
//!         .map(|()| log::set_max_level(LevelFilter::Info))
218
//! }
219
//! ```
220
//!
221
//! Implementations that adjust their configurations at runtime should take care
222
//! to adjust the maximum log level as well.
223
//!
224
//! # Use with `std`
225
//!
226
//! `set_logger` requires you to provide a `&'static Log`, which can be hard to
227
//! obtain if your logger depends on some runtime configuration. The
228
//! `set_boxed_logger` function is available with the `std` Cargo feature. It is
229
//! identical to `set_logger` except that it takes a `Box<Log>` rather than a
230
//! `&'static Log`:
231
//!
232
//! ```
233
//! # use log::{Level, LevelFilter, Log, SetLoggerError, Metadata};
234
//! # struct SimpleLogger;
235
//! # impl log::Log for SimpleLogger {
236
//! #   fn enabled(&self, _: &Metadata) -> bool { false }
237
//! #   fn log(&self, _: &log::Record) {}
238
//! #   fn flush(&self) {}
239
//! # }
240
//! # fn main() {}
241
//! # #[cfg(feature = "std")]
242
//! pub fn init() -> Result<(), SetLoggerError> {
243
//!     log::set_boxed_logger(Box::new(SimpleLogger))
244
//!         .map(|()| log::set_max_level(LevelFilter::Info))
245
//! }
246
//! ```
247
//!
248
//! # Compile time filters
249
//!
250
//! Log levels can be statically disabled at compile time by enabling one of these Cargo features:
251
//!
252
//! * `max_level_off`
253
//! * `max_level_error`
254
//! * `max_level_warn`
255
//! * `max_level_info`
256
//! * `max_level_debug`
257
//! * `max_level_trace`
258
//!
259
//! Log invocations at disabled levels will be skipped and will not even be present in the
260
//! resulting binary. These features control the value of the `STATIC_MAX_LEVEL` constant. The
261
//! logging macros check this value before logging a message. By default, no levels are disabled.
262
//!
263
//! It is possible to override this level for release builds only with the following features:
264
//!
265
//! * `release_max_level_off`
266
//! * `release_max_level_error`
267
//! * `release_max_level_warn`
268
//! * `release_max_level_info`
269
//! * `release_max_level_debug`
270
//! * `release_max_level_trace`
271
//!
272
//! Libraries should avoid using the max level features because they're global and can't be changed
273
//! once they're set.
274
//!
275
//! For example, a crate can disable trace level logs in debug builds and trace, debug, and info
276
//! level logs in release builds with the following configuration:
277
//!
278
//! ```toml
279
//! [dependencies]
280
//! log = { version = "0.4", features = ["max_level_debug", "release_max_level_warn"] }
281
//! ```
282
//! # Crate Feature Flags
283
//!
284
//! The following crate feature flags are available in addition to the filters. They are
285
//! configured in your `Cargo.toml`.
286
//!
287
//! * `std` allows use of `std` crate instead of the default `core`. Enables using `std::error` and
288
//! `set_boxed_logger` functionality.
289
//! * `serde` enables support for serialization and deserialization of `Level` and `LevelFilter`.
290
//!
291
//! ```toml
292
//! [dependencies]
293
//! log = { version = "0.4", features = ["std", "serde"] }
294
//! ```
295
//!
296
//! # Version compatibility
297
//!
298
//! The 0.3 and 0.4 versions of the `log` crate are almost entirely compatible. Log messages
299
//! made using `log` 0.3 will forward transparently to a logger implementation using `log` 0.4. Log
300
//! messages made using `log` 0.4 will forward to a logger implementation using `log` 0.3, but the
301
//! module path and file name information associated with the message will unfortunately be lost.
302
//!
303
//! [`Log`]: trait.Log.html
304
//! [level_link]: enum.Level.html
305
//! [filter_link]: enum.LevelFilter.html
306
//! [`set_logger`]: fn.set_logger.html
307
//! [`set_max_level`]: fn.set_max_level.html
308
//! [`try_set_logger_raw`]: fn.try_set_logger_raw.html
309
//! [`shutdown_logger_raw`]: fn.shutdown_logger_raw.html
310
//! [env_logger]: https://docs.rs/env_logger/*/env_logger/
311
//! [simple_logger]: https://github.com/borntyping/rust-simple_logger
312
//! [simplelog]: https://github.com/drakulix/simplelog.rs
313
//! [pretty_env_logger]: https://docs.rs/pretty_env_logger/*/pretty_env_logger/
314
//! [stderrlog]: https://docs.rs/stderrlog/*/stderrlog/
315
//! [flexi_logger]: https://docs.rs/flexi_logger/*/flexi_logger/
316
//! [call_logger]: https://docs.rs/call_logger/*/call_logger/
317
//! [syslog]: https://docs.rs/syslog/*/syslog/
318
//! [slog-stdlog]: https://docs.rs/slog-stdlog/*/slog_stdlog/
319
//! [log4rs]: https://docs.rs/log4rs/*/log4rs/
320
//! [fern]: https://docs.rs/fern/*/fern/
321
//! [systemd-journal-logger]: https://docs.rs/systemd-journal-logger/*/systemd_journal_logger/
322
//! [android_log]: https://docs.rs/android_log/*/android_log/
323
//! [win_dbg_logger]: https://docs.rs/win_dbg_logger/*/win_dbg_logger/
324
//! [db_logger]: https://docs.rs/db_logger/*/db_logger/
325
//! [log-to-defmt]: https://docs.rs/log-to-defmt/*/log_to_defmt/
326
//! [console_log]: https://docs.rs/console_log/*/console_log/
327
//! [structured-logger]: https://docs.rs/structured-logger/latest/structured_logger/
328
//! [logcontrol-log]: https://docs.rs/logcontrol-log/*/logcontrol_log/
329
//! [log_err]: https://docs.rs/log_err/*/log_err/
330
//! [log-reload]: https://docs.rs/log-reload/*/log_reload/
331
332
#![doc(
333
    html_logo_url = "https://www.rust-lang.org/logos/rust-logo-128x128-blk-v2.png",
334
    html_favicon_url = "https://www.rust-lang.org/favicon.ico",
335
    html_root_url = "https://docs.rs/log/0.4.21"
336
)]
337
#![warn(missing_docs)]
338
#![deny(missing_debug_implementations, unconditional_recursion)]
339
#![cfg_attr(all(not(feature = "std"), not(test)), no_std)]
340
// When compiled for the rustc compiler itself we want to make sure that this is
341
// an unstable crate
342
#![cfg_attr(rustbuild, feature(staged_api, rustc_private))]
343
#![cfg_attr(rustbuild, unstable(feature = "rustc_private", issue = "27812"))]
344
345
#[cfg(all(not(feature = "std"), not(test)))]
346
extern crate core as std;
347
348
use std::cfg;
349
#[cfg(feature = "std")]
350
use std::error;
351
use std::str::FromStr;
352
use std::{cmp, fmt, mem};
353
354
#[macro_use]
355
mod macros;
356
mod serde;
357
358
#[cfg(feature = "kv")]
359
pub mod kv;
360
361
#[cfg(target_has_atomic = "ptr")]
362
use std::sync::atomic::{AtomicUsize, Ordering};
363
364
#[cfg(not(target_has_atomic = "ptr"))]
365
use std::cell::Cell;
366
#[cfg(not(target_has_atomic = "ptr"))]
367
use std::sync::atomic::Ordering;
368
369
#[cfg(not(target_has_atomic = "ptr"))]
370
struct AtomicUsize {
371
    v: Cell<usize>,
372
}
373
374
#[cfg(not(target_has_atomic = "ptr"))]
375
impl AtomicUsize {
376
    const fn new(v: usize) -> AtomicUsize {
377
        AtomicUsize { v: Cell::new(v) }
378
    }
379
380
    fn load(&self, _order: Ordering) -> usize {
381
        self.v.get()
382
    }
383
384
    fn store(&self, val: usize, _order: Ordering) {
385
        self.v.set(val)
386
    }
387
388
    #[cfg(target_has_atomic = "ptr")]
389
    fn compare_exchange(
390
        &self,
391
        current: usize,
392
        new: usize,
393
        _success: Ordering,
394
        _failure: Ordering,
395
    ) -> Result<usize, usize> {
396
        let prev = self.v.get();
397
        if current == prev {
398
            self.v.set(new);
399
        }
400
        Ok(prev)
401
    }
402
}
403
404
// Any platform without atomics is unlikely to have multiple cores, so
405
// writing via Cell will not be a race condition.
406
#[cfg(not(target_has_atomic = "ptr"))]
407
unsafe impl Sync for AtomicUsize {}
408
409
// The LOGGER static holds a pointer to the global logger. It is protected by
410
// the STATE static which determines whether LOGGER has been initialized yet.
411
static mut LOGGER: &dyn Log = &NopLogger;
412
413
static STATE: AtomicUsize = AtomicUsize::new(0);
414
415
// There are three different states that we care about: the logger's
416
// uninitialized, the logger's initializing (set_logger's been called but
417
// LOGGER hasn't actually been set yet), or the logger's active.
418
const UNINITIALIZED: usize = 0;
419
const INITIALIZING: usize = 1;
420
const INITIALIZED: usize = 2;
421
422
static MAX_LOG_LEVEL_FILTER: AtomicUsize = AtomicUsize::new(0);
423
424
static LOG_LEVEL_NAMES: [&str; 6] = ["OFF", "ERROR", "WARN", "INFO", "DEBUG", "TRACE"];
425
426
static SET_LOGGER_ERROR: &str = "attempted to set a logger after the logging system \
427
                                 was already initialized";
428
static LEVEL_PARSE_ERROR: &str =
429
    "attempted to convert a string that doesn't match an existing log level";
430
431
/// An enum representing the available verbosity levels of the logger.
432
///
433
/// Typical usage includes: checking if a certain `Level` is enabled with
434
/// [`log_enabled!`](macro.log_enabled.html), specifying the `Level` of
435
/// [`log!`](macro.log.html), and comparing a `Level` directly to a
436
/// [`LevelFilter`](enum.LevelFilter.html).
437
#[repr(usize)]
438
0
#[derive(Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Debug, Hash)]
439
pub enum Level {
440
    /// The "error" level.
441
    ///
442
    /// Designates very serious errors.
443
    // This way these line up with the discriminants for LevelFilter below
444
    // This works because Rust treats field-less enums the same way as C does:
445
    // https://doc.rust-lang.org/reference/items/enumerations.html#custom-discriminant-values-for-field-less-enumerations
446
    Error = 1,
447
    /// The "warn" level.
448
    ///
449
    /// Designates hazardous situations.
450
    Warn,
451
    /// The "info" level.
452
    ///
453
    /// Designates useful information.
454
    Info,
455
    /// The "debug" level.
456
    ///
457
    /// Designates lower priority information.
458
    Debug,
459
    /// The "trace" level.
460
    ///
461
    /// Designates very low priority, often extremely verbose, information.
462
    Trace,
463
}
464
465
impl PartialEq<LevelFilter> for Level {
466
    #[inline]
467
0
    fn eq(&self, other: &LevelFilter) -> bool {
468
0
        *self as usize == *other as usize
469
0
    }
470
}
471
472
impl PartialOrd<LevelFilter> for Level {
473
    #[inline]
474
177k
    fn partial_cmp(&self, other: &LevelFilter) -> Option<cmp::Ordering> {
475
177k
        Some((*self as usize).cmp(&(*other as usize)))
476
177k
    }
<log::Level as core::cmp::PartialOrd<log::LevelFilter>>::partial_cmp
Line
Count
Source
474
151k
    fn partial_cmp(&self, other: &LevelFilter) -> Option<cmp::Ordering> {
475
151k
        Some((*self as usize).cmp(&(*other as usize)))
476
151k
    }
Unexecuted instantiation: <log::Level as core::cmp::PartialOrd<log::LevelFilter>>::partial_cmp
<log::Level as core::cmp::PartialOrd<log::LevelFilter>>::partial_cmp
Line
Count
Source
474
652
    fn partial_cmp(&self, other: &LevelFilter) -> Option<cmp::Ordering> {
475
652
        Some((*self as usize).cmp(&(*other as usize)))
476
652
    }
<log::Level as core::cmp::PartialOrd<log::LevelFilter>>::partial_cmp
Line
Count
Source
474
17.9k
    fn partial_cmp(&self, other: &LevelFilter) -> Option<cmp::Ordering> {
475
17.9k
        Some((*self as usize).cmp(&(*other as usize)))
476
17.9k
    }
Unexecuted instantiation: <log::Level as core::cmp::PartialOrd<log::LevelFilter>>::partial_cmp
<log::Level as core::cmp::PartialOrd<log::LevelFilter>>::partial_cmp
Line
Count
Source
474
7.07k
    fn partial_cmp(&self, other: &LevelFilter) -> Option<cmp::Ordering> {
475
7.07k
        Some((*self as usize).cmp(&(*other as usize)))
476
7.07k
    }
Unexecuted instantiation: <log::Level as core::cmp::PartialOrd<log::LevelFilter>>::partial_cmp
477
}
478
479
impl FromStr for Level {
480
    type Err = ParseLevelError;
481
0
    fn from_str(level: &str) -> Result<Level, Self::Err> {
482
0
        LOG_LEVEL_NAMES
483
0
            .iter()
484
0
            .position(|&name| name.eq_ignore_ascii_case(level))
485
0
            .into_iter()
486
0
            .filter(|&idx| idx != 0)
487
0
            .map(|idx| Level::from_usize(idx).unwrap())
488
0
            .next()
489
0
            .ok_or(ParseLevelError(()))
490
0
    }
491
}
492
493
impl fmt::Display for Level {
494
0
    fn fmt(&self, fmt: &mut fmt::Formatter) -> fmt::Result {
495
0
        fmt.pad(self.as_str())
496
0
    }
497
}
498
499
impl Level {
500
0
    fn from_usize(u: usize) -> Option<Level> {
501
0
        match u {
502
0
            1 => Some(Level::Error),
503
0
            2 => Some(Level::Warn),
504
0
            3 => Some(Level::Info),
505
0
            4 => Some(Level::Debug),
506
0
            5 => Some(Level::Trace),
507
0
            _ => None,
508
        }
509
0
    }
510
511
    /// Returns the most verbose logging level.
512
    #[inline]
513
0
    pub fn max() -> Level {
514
0
        Level::Trace
515
0
    }
516
517
    /// Converts the `Level` to the equivalent `LevelFilter`.
518
    #[inline]
519
0
    pub fn to_level_filter(&self) -> LevelFilter {
520
0
        LevelFilter::from_usize(*self as usize).unwrap()
521
0
    }
522
523
    /// Returns the string representation of the `Level`.
524
    ///
525
    /// This returns the same string as the `fmt::Display` implementation.
526
0
    pub fn as_str(&self) -> &'static str {
527
0
        LOG_LEVEL_NAMES[*self as usize]
528
0
    }
529
530
    /// Iterate through all supported logging levels.
531
    ///
532
    /// The order of iteration is from more severe to less severe log messages.
533
    ///
534
    /// # Examples
535
    ///
536
    /// ```
537
    /// use log::Level;
538
    ///
539
    /// let mut levels = Level::iter();
540
    ///
541
    /// assert_eq!(Some(Level::Error), levels.next());
542
    /// assert_eq!(Some(Level::Trace), levels.last());
543
    /// ```
544
0
    pub fn iter() -> impl Iterator<Item = Self> {
545
0
        (1..6).map(|i| Self::from_usize(i).unwrap())
546
0
    }
547
}
548
549
/// An enum representing the available verbosity level filters of the logger.
550
///
551
/// A `LevelFilter` may be compared directly to a [`Level`]. Use this type
552
/// to get and set the maximum log level with [`max_level()`] and [`set_max_level`].
553
///
554
/// [`Level`]: enum.Level.html
555
/// [`max_level()`]: fn.max_level.html
556
/// [`set_max_level`]: fn.set_max_level.html
557
#[repr(usize)]
558
0
#[derive(Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Debug, Hash)]
559
pub enum LevelFilter {
560
    /// A level lower than all log levels.
561
    Off,
562
    /// Corresponds to the `Error` log level.
563
    Error,
564
    /// Corresponds to the `Warn` log level.
565
    Warn,
566
    /// Corresponds to the `Info` log level.
567
    Info,
568
    /// Corresponds to the `Debug` log level.
569
    Debug,
570
    /// Corresponds to the `Trace` log level.
571
    Trace,
572
}
573
574
impl PartialEq<Level> for LevelFilter {
575
    #[inline]
576
0
    fn eq(&self, other: &Level) -> bool {
577
0
        other.eq(self)
578
0
    }
579
}
580
581
impl PartialOrd<Level> for LevelFilter {
582
    #[inline]
583
0
    fn partial_cmp(&self, other: &Level) -> Option<cmp::Ordering> {
584
0
        Some((*self as usize).cmp(&(*other as usize)))
585
0
    }
586
}
587
588
impl FromStr for LevelFilter {
589
    type Err = ParseLevelError;
590
0
    fn from_str(level: &str) -> Result<LevelFilter, Self::Err> {
591
0
        LOG_LEVEL_NAMES
592
0
            .iter()
593
0
            .position(|&name| name.eq_ignore_ascii_case(level))
594
0
            .map(|p| LevelFilter::from_usize(p).unwrap())
595
0
            .ok_or(ParseLevelError(()))
596
0
    }
597
}
598
599
impl fmt::Display for LevelFilter {
600
0
    fn fmt(&self, fmt: &mut fmt::Formatter) -> fmt::Result {
601
0
        fmt.pad(self.as_str())
602
0
    }
603
}
604
605
impl LevelFilter {
606
0
    fn from_usize(u: usize) -> Option<LevelFilter> {
607
0
        match u {
608
0
            0 => Some(LevelFilter::Off),
609
0
            1 => Some(LevelFilter::Error),
610
0
            2 => Some(LevelFilter::Warn),
611
0
            3 => Some(LevelFilter::Info),
612
0
            4 => Some(LevelFilter::Debug),
613
0
            5 => Some(LevelFilter::Trace),
614
0
            _ => None,
615
        }
616
0
    }
617
618
    /// Returns the most verbose logging level filter.
619
    #[inline]
620
0
    pub fn max() -> LevelFilter {
621
0
        LevelFilter::Trace
622
0
    }
623
624
    /// Converts `self` to the equivalent `Level`.
625
    ///
626
    /// Returns `None` if `self` is `LevelFilter::Off`.
627
    #[inline]
628
0
    pub fn to_level(&self) -> Option<Level> {
629
0
        Level::from_usize(*self as usize)
630
0
    }
631
632
    /// Returns the string representation of the `LevelFilter`.
633
    ///
634
    /// This returns the same string as the `fmt::Display` implementation.
635
0
    pub fn as_str(&self) -> &'static str {
636
0
        LOG_LEVEL_NAMES[*self as usize]
637
0
    }
638
639
    /// Iterate through all supported filtering levels.
640
    ///
641
    /// The order of iteration is from less to more verbose filtering.
642
    ///
643
    /// # Examples
644
    ///
645
    /// ```
646
    /// use log::LevelFilter;
647
    ///
648
    /// let mut levels = LevelFilter::iter();
649
    ///
650
    /// assert_eq!(Some(LevelFilter::Off), levels.next());
651
    /// assert_eq!(Some(LevelFilter::Trace), levels.last());
652
    /// ```
653
0
    pub fn iter() -> impl Iterator<Item = Self> {
654
0
        (0..6).map(|i| Self::from_usize(i).unwrap())
655
0
    }
656
}
657
658
0
#[derive(Copy, Clone, Eq, PartialEq, Ord, PartialOrd, Hash, Debug)]
659
enum MaybeStaticStr<'a> {
660
    Static(&'static str),
661
    Borrowed(&'a str),
662
}
663
664
impl<'a> MaybeStaticStr<'a> {
665
    #[inline]
666
0
    fn get(&self) -> &'a str {
667
0
        match *self {
668
0
            MaybeStaticStr::Static(s) => s,
669
0
            MaybeStaticStr::Borrowed(s) => s,
670
        }
671
0
    }
672
}
673
674
/// The "payload" of a log message.
675
///
676
/// # Use
677
///
678
/// `Record` structures are passed as parameters to the [`log`][method.log]
679
/// method of the [`Log`] trait. Logger implementors manipulate these
680
/// structures in order to display log messages. `Record`s are automatically
681
/// created by the [`log!`] macro and so are not seen by log users.
682
///
683
/// Note that the [`level()`] and [`target()`] accessors are equivalent to
684
/// `self.metadata().level()` and `self.metadata().target()` respectively.
685
/// These methods are provided as a convenience for users of this structure.
686
///
687
/// # Example
688
///
689
/// The following example shows a simple logger that displays the level,
690
/// module path, and message of any `Record` that is passed to it.
691
///
692
/// ```
693
/// struct SimpleLogger;
694
///
695
/// impl log::Log for SimpleLogger {
696
///    fn enabled(&self, _metadata: &log::Metadata) -> bool {
697
///        true
698
///    }
699
///
700
///    fn log(&self, record: &log::Record) {
701
///        if !self.enabled(record.metadata()) {
702
///            return;
703
///        }
704
///
705
///        println!("{}:{} -- {}",
706
///                 record.level(),
707
///                 record.target(),
708
///                 record.args());
709
///    }
710
///    fn flush(&self) {}
711
/// }
712
/// ```
713
///
714
/// [method.log]: trait.Log.html#tymethod.log
715
/// [`Log`]: trait.Log.html
716
/// [`log!`]: macro.log.html
717
/// [`level()`]: struct.Record.html#method.level
718
/// [`target()`]: struct.Record.html#method.target
719
0
#[derive(Clone, Debug)]
720
pub struct Record<'a> {
721
    metadata: Metadata<'a>,
722
    args: fmt::Arguments<'a>,
723
    module_path: Option<MaybeStaticStr<'a>>,
724
    file: Option<MaybeStaticStr<'a>>,
725
    line: Option<u32>,
726
    #[cfg(feature = "kv")]
727
    key_values: KeyValues<'a>,
728
}
729
730
// This wrapper type is only needed so we can
731
// `#[derive(Debug)]` on `Record`. It also
732
// provides a useful `Debug` implementation for
733
// the underlying `Source`.
734
#[cfg(feature = "kv")]
735
#[derive(Clone)]
736
struct KeyValues<'a>(&'a dyn kv::Source);
737
738
#[cfg(feature = "kv")]
739
impl<'a> fmt::Debug for KeyValues<'a> {
740
    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
741
        let mut visitor = f.debug_map();
742
        self.0.visit(&mut visitor).map_err(|_| fmt::Error)?;
743
        visitor.finish()
744
    }
745
}
746
747
impl<'a> Record<'a> {
748
    /// Returns a new builder.
749
    #[inline]
750
0
    pub fn builder() -> RecordBuilder<'a> {
751
0
        RecordBuilder::new()
752
0
    }
753
754
    /// The message body.
755
    #[inline]
756
0
    pub fn args(&self) -> &fmt::Arguments<'a> {
757
0
        &self.args
758
0
    }
759
760
    /// Metadata about the log directive.
761
    #[inline]
762
0
    pub fn metadata(&self) -> &Metadata<'a> {
763
0
        &self.metadata
764
0
    }
765
766
    /// The verbosity level of the message.
767
    #[inline]
768
0
    pub fn level(&self) -> Level {
769
0
        self.metadata.level()
770
0
    }
771
772
    /// The name of the target of the directive.
773
    #[inline]
774
0
    pub fn target(&self) -> &'a str {
775
0
        self.metadata.target()
776
0
    }
777
778
    /// The module path of the message.
779
    #[inline]
780
0
    pub fn module_path(&self) -> Option<&'a str> {
781
0
        self.module_path.map(|s| s.get())
782
0
    }
783
784
    /// The module path of the message, if it is a `'static` string.
785
    #[inline]
786
0
    pub fn module_path_static(&self) -> Option<&'static str> {
787
0
        match self.module_path {
788
0
            Some(MaybeStaticStr::Static(s)) => Some(s),
789
0
            _ => None,
790
        }
791
0
    }
792
793
    /// The source file containing the message.
794
    #[inline]
795
0
    pub fn file(&self) -> Option<&'a str> {
796
0
        self.file.map(|s| s.get())
797
0
    }
798
799
    /// The source file containing the message, if it is a `'static` string.
800
    #[inline]
801
0
    pub fn file_static(&self) -> Option<&'static str> {
802
0
        match self.file {
803
0
            Some(MaybeStaticStr::Static(s)) => Some(s),
804
0
            _ => None,
805
        }
806
0
    }
807
808
    /// The line containing the message.
809
    #[inline]
810
0
    pub fn line(&self) -> Option<u32> {
811
0
        self.line
812
0
    }
813
814
    /// The structured key-value pairs associated with the message.
815
    #[cfg(feature = "kv")]
816
    #[inline]
817
    pub fn key_values(&self) -> &dyn kv::Source {
818
        self.key_values.0
819
    }
820
821
    /// Create a new [`RecordBuilder`](struct.RecordBuilder.html) based on this record.
822
    #[cfg(feature = "kv")]
823
    #[inline]
824
    pub fn to_builder(&self) -> RecordBuilder {
825
        RecordBuilder {
826
            record: Record {
827
                metadata: Metadata {
828
                    level: self.metadata.level,
829
                    target: self.metadata.target,
830
                },
831
                args: self.args,
832
                module_path: self.module_path,
833
                file: self.file,
834
                line: self.line,
835
                key_values: self.key_values.clone(),
836
            },
837
        }
838
    }
839
}
840
841
/// Builder for [`Record`](struct.Record.html).
842
///
843
/// Typically should only be used by log library creators or for testing and "shim loggers".
844
/// The `RecordBuilder` can set the different parameters of `Record` object, and returns
845
/// the created object when `build` is called.
846
///
847
/// # Examples
848
///
849
/// ```
850
/// use log::{Level, Record};
851
///
852
/// let record = Record::builder()
853
///                 .args(format_args!("Error!"))
854
///                 .level(Level::Error)
855
///                 .target("myApp")
856
///                 .file(Some("server.rs"))
857
///                 .line(Some(144))
858
///                 .module_path(Some("server"))
859
///                 .build();
860
/// ```
861
///
862
/// Alternatively, use [`MetadataBuilder`](struct.MetadataBuilder.html):
863
///
864
/// ```
865
/// use log::{Record, Level, MetadataBuilder};
866
///
867
/// let error_metadata = MetadataBuilder::new()
868
///                         .target("myApp")
869
///                         .level(Level::Error)
870
///                         .build();
871
///
872
/// let record = Record::builder()
873
///                 .metadata(error_metadata)
874
///                 .args(format_args!("Error!"))
875
///                 .line(Some(433))
876
///                 .file(Some("app.rs"))
877
///                 .module_path(Some("server"))
878
///                 .build();
879
/// ```
880
0
#[derive(Debug)]
881
pub struct RecordBuilder<'a> {
882
    record: Record<'a>,
883
}
884
885
impl<'a> RecordBuilder<'a> {
886
    /// Construct new `RecordBuilder`.
887
    ///
888
    /// The default options are:
889
    ///
890
    /// - `args`: [`format_args!("")`]
891
    /// - `metadata`: [`Metadata::builder().build()`]
892
    /// - `module_path`: `None`
893
    /// - `file`: `None`
894
    /// - `line`: `None`
895
    ///
896
    /// [`format_args!("")`]: https://doc.rust-lang.org/std/macro.format_args.html
897
    /// [`Metadata::builder().build()`]: struct.MetadataBuilder.html#method.build
898
    #[inline]
899
0
    pub fn new() -> RecordBuilder<'a> {
900
0
        RecordBuilder {
901
0
            record: Record {
902
0
                args: format_args!(""),
903
0
                metadata: Metadata::builder().build(),
904
0
                module_path: None,
905
0
                file: None,
906
0
                line: None,
907
0
                #[cfg(feature = "kv")]
908
0
                key_values: KeyValues(&None::<(kv::Key, kv::Value)>),
909
0
            },
910
0
        }
911
0
    }
912
913
    /// Set [`args`](struct.Record.html#method.args).
914
    #[inline]
915
0
    pub fn args(&mut self, args: fmt::Arguments<'a>) -> &mut RecordBuilder<'a> {
916
0
        self.record.args = args;
917
0
        self
918
0
    }
919
920
    /// Set [`metadata`](struct.Record.html#method.metadata). Construct a `Metadata` object with [`MetadataBuilder`](struct.MetadataBuilder.html).
921
    #[inline]
922
0
    pub fn metadata(&mut self, metadata: Metadata<'a>) -> &mut RecordBuilder<'a> {
923
0
        self.record.metadata = metadata;
924
0
        self
925
0
    }
926
927
    /// Set [`Metadata::level`](struct.Metadata.html#method.level).
928
    #[inline]
929
0
    pub fn level(&mut self, level: Level) -> &mut RecordBuilder<'a> {
930
0
        self.record.metadata.level = level;
931
0
        self
932
0
    }
933
934
    /// Set [`Metadata::target`](struct.Metadata.html#method.target)
935
    #[inline]
936
0
    pub fn target(&mut self, target: &'a str) -> &mut RecordBuilder<'a> {
937
0
        self.record.metadata.target = target;
938
0
        self
939
0
    }
940
941
    /// Set [`module_path`](struct.Record.html#method.module_path)
942
    #[inline]
943
0
    pub fn module_path(&mut self, path: Option<&'a str>) -> &mut RecordBuilder<'a> {
944
0
        self.record.module_path = path.map(MaybeStaticStr::Borrowed);
945
0
        self
946
0
    }
947
948
    /// Set [`module_path`](struct.Record.html#method.module_path) to a `'static` string
949
    #[inline]
950
0
    pub fn module_path_static(&mut self, path: Option<&'static str>) -> &mut RecordBuilder<'a> {
951
0
        self.record.module_path = path.map(MaybeStaticStr::Static);
952
0
        self
953
0
    }
954
955
    /// Set [`file`](struct.Record.html#method.file)
956
    #[inline]
957
0
    pub fn file(&mut self, file: Option<&'a str>) -> &mut RecordBuilder<'a> {
958
0
        self.record.file = file.map(MaybeStaticStr::Borrowed);
959
0
        self
960
0
    }
961
962
    /// Set [`file`](struct.Record.html#method.file) to a `'static` string.
963
    #[inline]
964
0
    pub fn file_static(&mut self, file: Option<&'static str>) -> &mut RecordBuilder<'a> {
965
0
        self.record.file = file.map(MaybeStaticStr::Static);
966
0
        self
967
0
    }
968
969
    /// Set [`line`](struct.Record.html#method.line)
970
    #[inline]
971
0
    pub fn line(&mut self, line: Option<u32>) -> &mut RecordBuilder<'a> {
972
0
        self.record.line = line;
973
0
        self
974
0
    }
975
976
    /// Set [`key_values`](struct.Record.html#method.key_values)
977
    #[cfg(feature = "kv")]
978
    #[inline]
979
    pub fn key_values(&mut self, kvs: &'a dyn kv::Source) -> &mut RecordBuilder<'a> {
980
        self.record.key_values = KeyValues(kvs);
981
        self
982
    }
983
984
    /// Invoke the builder and return a `Record`
985
    #[inline]
986
0
    pub fn build(&self) -> Record<'a> {
987
0
        self.record.clone()
988
0
    }
989
}
990
991
impl<'a> Default for RecordBuilder<'a> {
992
0
    fn default() -> Self {
993
0
        Self::new()
994
0
    }
995
}
996
997
/// Metadata about a log message.
998
///
999
/// # Use
1000
///
1001
/// `Metadata` structs are created when users of the library use
1002
/// logging macros.
1003
///
1004
/// They are consumed by implementations of the `Log` trait in the
1005
/// `enabled` method.
1006
///
1007
/// `Record`s use `Metadata` to determine the log message's severity
1008
/// and target.
1009
///
1010
/// Users should use the `log_enabled!` macro in their code to avoid
1011
/// constructing expensive log messages.
1012
///
1013
/// # Examples
1014
///
1015
/// ```
1016
/// use log::{Record, Level, Metadata};
1017
///
1018
/// struct MyLogger;
1019
///
1020
/// impl log::Log for MyLogger {
1021
///     fn enabled(&self, metadata: &Metadata) -> bool {
1022
///         metadata.level() <= Level::Info
1023
///     }
1024
///
1025
///     fn log(&self, record: &Record) {
1026
///         if self.enabled(record.metadata()) {
1027
///             println!("{} - {}", record.level(), record.args());
1028
///         }
1029
///     }
1030
///     fn flush(&self) {}
1031
/// }
1032
///
1033
/// # fn main(){}
1034
/// ```
1035
0
#[derive(Clone, Eq, PartialEq, Ord, PartialOrd, Hash, Debug)]
1036
pub struct Metadata<'a> {
1037
    level: Level,
1038
    target: &'a str,
1039
}
1040
1041
impl<'a> Metadata<'a> {
1042
    /// Returns a new builder.
1043
    #[inline]
1044
0
    pub fn builder() -> MetadataBuilder<'a> {
1045
0
        MetadataBuilder::new()
1046
0
    }
1047
1048
    /// The verbosity level of the message.
1049
    #[inline]
1050
0
    pub fn level(&self) -> Level {
1051
0
        self.level
1052
0
    }
1053
1054
    /// The name of the target of the directive.
1055
    #[inline]
1056
0
    pub fn target(&self) -> &'a str {
1057
0
        self.target
1058
0
    }
1059
}
1060
1061
/// Builder for [`Metadata`](struct.Metadata.html).
1062
///
1063
/// Typically should only be used by log library creators or for testing and "shim loggers".
1064
/// The `MetadataBuilder` can set the different parameters of a `Metadata` object, and returns
1065
/// the created object when `build` is called.
1066
///
1067
/// # Example
1068
///
1069
/// ```
1070
/// let target = "myApp";
1071
/// use log::{Level, MetadataBuilder};
1072
/// let metadata = MetadataBuilder::new()
1073
///                     .level(Level::Debug)
1074
///                     .target(target)
1075
///                     .build();
1076
/// ```
1077
0
#[derive(Eq, PartialEq, Ord, PartialOrd, Hash, Debug)]
1078
pub struct MetadataBuilder<'a> {
1079
    metadata: Metadata<'a>,
1080
}
1081
1082
impl<'a> MetadataBuilder<'a> {
1083
    /// Construct a new `MetadataBuilder`.
1084
    ///
1085
    /// The default options are:
1086
    ///
1087
    /// - `level`: `Level::Info`
1088
    /// - `target`: `""`
1089
    #[inline]
1090
0
    pub fn new() -> MetadataBuilder<'a> {
1091
0
        MetadataBuilder {
1092
0
            metadata: Metadata {
1093
0
                level: Level::Info,
1094
0
                target: "",
1095
0
            },
1096
0
        }
1097
0
    }
1098
1099
    /// Setter for [`level`](struct.Metadata.html#method.level).
1100
    #[inline]
1101
0
    pub fn level(&mut self, arg: Level) -> &mut MetadataBuilder<'a> {
1102
0
        self.metadata.level = arg;
1103
0
        self
1104
0
    }
1105
1106
    /// Setter for [`target`](struct.Metadata.html#method.target).
1107
    #[inline]
1108
0
    pub fn target(&mut self, target: &'a str) -> &mut MetadataBuilder<'a> {
1109
0
        self.metadata.target = target;
1110
0
        self
1111
0
    }
1112
1113
    /// Returns a `Metadata` object.
1114
    #[inline]
1115
0
    pub fn build(&self) -> Metadata<'a> {
1116
0
        self.metadata.clone()
1117
0
    }
1118
}
1119
1120
impl<'a> Default for MetadataBuilder<'a> {
1121
0
    fn default() -> Self {
1122
0
        Self::new()
1123
0
    }
1124
}
1125
1126
/// A trait encapsulating the operations required of a logger.
1127
pub trait Log: Sync + Send {
1128
    /// Determines if a log message with the specified metadata would be
1129
    /// logged.
1130
    ///
1131
    /// This is used by the `log_enabled!` macro to allow callers to avoid
1132
    /// expensive computation of log message arguments if the message would be
1133
    /// discarded anyway.
1134
    ///
1135
    /// # For implementors
1136
    ///
1137
    /// This method isn't called automatically by the `log!` macros.
1138
    /// It's up to an implementation of the `Log` trait to call `enabled` in its own
1139
    /// `log` method implementation to guarantee that filtering is applied.
1140
    fn enabled(&self, metadata: &Metadata) -> bool;
1141
1142
    /// Logs the `Record`.
1143
    ///
1144
    /// # For implementors
1145
    ///
1146
    /// Note that `enabled` is *not* necessarily called before this method.
1147
    /// Implementations of `log` should perform all necessary filtering
1148
    /// internally.
1149
    fn log(&self, record: &Record);
1150
1151
    /// Flushes any buffered records.
1152
    fn flush(&self);
1153
}
1154
1155
// Just used as a dummy initial value for LOGGER
1156
struct NopLogger;
1157
1158
impl Log for NopLogger {
1159
0
    fn enabled(&self, _: &Metadata) -> bool {
1160
0
        false
1161
0
    }
1162
1163
0
    fn log(&self, _: &Record) {}
1164
0
    fn flush(&self) {}
1165
}
1166
1167
impl<T> Log for &'_ T
1168
where
1169
    T: ?Sized + Log,
1170
{
1171
0
    fn enabled(&self, metadata: &Metadata) -> bool {
1172
0
        (**self).enabled(metadata)
1173
0
    }
1174
1175
0
    fn log(&self, record: &Record) {
1176
0
        (**self).log(record);
1177
0
    }
1178
0
    fn flush(&self) {
1179
0
        (**self).flush();
1180
0
    }
1181
}
1182
1183
#[cfg(feature = "std")]
1184
impl<T> Log for std::boxed::Box<T>
1185
where
1186
    T: ?Sized + Log,
1187
{
1188
0
    fn enabled(&self, metadata: &Metadata) -> bool {
1189
0
        self.as_ref().enabled(metadata)
1190
0
    }
1191
1192
0
    fn log(&self, record: &Record) {
1193
0
        self.as_ref().log(record);
1194
0
    }
1195
0
    fn flush(&self) {
1196
0
        self.as_ref().flush();
1197
0
    }
1198
}
1199
1200
#[cfg(feature = "std")]
1201
impl<T> Log for std::sync::Arc<T>
1202
where
1203
    T: ?Sized + Log,
1204
{
1205
0
    fn enabled(&self, metadata: &Metadata) -> bool {
1206
0
        self.as_ref().enabled(metadata)
1207
0
    }
1208
1209
0
    fn log(&self, record: &Record) {
1210
0
        self.as_ref().log(record);
1211
0
    }
1212
0
    fn flush(&self) {
1213
0
        self.as_ref().flush();
1214
0
    }
1215
}
1216
1217
/// Sets the global maximum log level.
1218
///
1219
/// Generally, this should only be called by the active logging implementation.
1220
///
1221
/// Note that `Trace` is the maximum level, because it provides the maximum amount of detail in the emitted logs.
1222
#[inline]
1223
#[cfg(target_has_atomic = "ptr")]
1224
0
pub fn set_max_level(level: LevelFilter) {
1225
0
    MAX_LOG_LEVEL_FILTER.store(level as usize, Ordering::Relaxed);
1226
0
}
1227
1228
/// A thread-unsafe version of [`set_max_level`].
1229
///
1230
/// This function is available on all platforms, even those that do not have
1231
/// support for atomics that is needed by [`set_max_level`].
1232
///
1233
/// In almost all cases, [`set_max_level`] should be preferred.
1234
///
1235
/// # Safety
1236
///
1237
/// This function is only safe to call when no other level setting function is
1238
/// called while this function still executes.
1239
///
1240
/// This can be upheld by (for example) making sure that **there are no other
1241
/// threads**, and (on embedded) that **interrupts are disabled**.
1242
///
1243
/// Is is safe to use all other logging functions while this function runs
1244
/// (including all logging macros).
1245
///
1246
/// [`set_max_level`]: fn.set_max_level.html
1247
#[inline]
1248
0
pub unsafe fn set_max_level_racy(level: LevelFilter) {
1249
0
    // `MAX_LOG_LEVEL_FILTER` uses a `Cell` as the underlying primitive when a
1250
0
    // platform doesn't support `target_has_atomic = "ptr"`, so even though this looks the same
1251
0
    // as `set_max_level` it may have different safety properties.
1252
0
    MAX_LOG_LEVEL_FILTER.store(level as usize, Ordering::Relaxed);
1253
0
}
1254
1255
/// Returns the current maximum log level.
1256
///
1257
/// The [`log!`], [`error!`], [`warn!`], [`info!`], [`debug!`], and [`trace!`] macros check
1258
/// this value and discard any message logged at a higher level. The maximum
1259
/// log level is set by the [`set_max_level`] function.
1260
///
1261
/// [`log!`]: macro.log.html
1262
/// [`error!`]: macro.error.html
1263
/// [`warn!`]: macro.warn.html
1264
/// [`info!`]: macro.info.html
1265
/// [`debug!`]: macro.debug.html
1266
/// [`trace!`]: macro.trace.html
1267
/// [`set_max_level`]: fn.set_max_level.html
1268
#[inline(always)]
1269
88.6k
pub fn max_level() -> LevelFilter {
1270
88.6k
    // Since `LevelFilter` is `repr(usize)`,
1271
88.6k
    // this transmute is sound if and only if `MAX_LOG_LEVEL_FILTER`
1272
88.6k
    // is set to a usize that is a valid discriminant for `LevelFilter`.
1273
88.6k
    // Since `MAX_LOG_LEVEL_FILTER` is private, the only time it's set
1274
88.6k
    // is by `set_max_level` above, i.e. by casting a `LevelFilter` to `usize`.
1275
88.6k
    // So any usize stored in `MAX_LOG_LEVEL_FILTER` is a valid discriminant.
1276
88.6k
    unsafe { mem::transmute(MAX_LOG_LEVEL_FILTER.load(Ordering::Relaxed)) }
1277
88.6k
}
1278
1279
/// Sets the global logger to a `Box<Log>`.
1280
///
1281
/// This is a simple convenience wrapper over `set_logger`, which takes a
1282
/// `Box<Log>` rather than a `&'static Log`. See the documentation for
1283
/// [`set_logger`] for more details.
1284
///
1285
/// Requires the `std` feature.
1286
///
1287
/// # Errors
1288
///
1289
/// An error is returned if a logger has already been set.
1290
///
1291
/// [`set_logger`]: fn.set_logger.html
1292
#[cfg(all(feature = "std", target_has_atomic = "ptr"))]
1293
0
pub fn set_boxed_logger(logger: Box<dyn Log>) -> Result<(), SetLoggerError> {
1294
0
    set_logger_inner(|| Box::leak(logger))
1295
0
}
1296
1297
/// Sets the global logger to a `&'static Log`.
1298
///
1299
/// This function may only be called once in the lifetime of a program. Any log
1300
/// events that occur before the call to `set_logger` completes will be ignored.
1301
///
1302
/// This function does not typically need to be called manually. Logger
1303
/// implementations should provide an initialization method that installs the
1304
/// logger internally.
1305
///
1306
/// # Availability
1307
///
1308
/// This method is available even when the `std` feature is disabled. However,
1309
/// it is currently unavailable on `thumbv6` targets, which lack support for
1310
/// some atomic operations which are used by this function. Even on those
1311
/// targets, [`set_logger_racy`] will be available.
1312
///
1313
/// # Errors
1314
///
1315
/// An error is returned if a logger has already been set.
1316
///
1317
/// # Examples
1318
///
1319
/// ```
1320
/// use log::{error, info, warn, Record, Level, Metadata, LevelFilter};
1321
///
1322
/// static MY_LOGGER: MyLogger = MyLogger;
1323
///
1324
/// struct MyLogger;
1325
///
1326
/// impl log::Log for MyLogger {
1327
///     fn enabled(&self, metadata: &Metadata) -> bool {
1328
///         metadata.level() <= Level::Info
1329
///     }
1330
///
1331
///     fn log(&self, record: &Record) {
1332
///         if self.enabled(record.metadata()) {
1333
///             println!("{} - {}", record.level(), record.args());
1334
///         }
1335
///     }
1336
///     fn flush(&self) {}
1337
/// }
1338
///
1339
/// # fn main(){
1340
/// log::set_logger(&MY_LOGGER).unwrap();
1341
/// log::set_max_level(LevelFilter::Info);
1342
///
1343
/// info!("hello log");
1344
/// warn!("warning");
1345
/// error!("oops");
1346
/// # }
1347
/// ```
1348
///
1349
/// [`set_logger_racy`]: fn.set_logger_racy.html
1350
#[cfg(target_has_atomic = "ptr")]
1351
0
pub fn set_logger(logger: &'static dyn Log) -> Result<(), SetLoggerError> {
1352
0
    set_logger_inner(|| logger)
1353
0
}
1354
1355
#[cfg(target_has_atomic = "ptr")]
1356
0
fn set_logger_inner<F>(make_logger: F) -> Result<(), SetLoggerError>
1357
0
where
1358
0
    F: FnOnce() -> &'static dyn Log,
1359
0
{
1360
0
    let old_state = match STATE.compare_exchange(
1361
0
        UNINITIALIZED,
1362
0
        INITIALIZING,
1363
0
        Ordering::SeqCst,
1364
0
        Ordering::SeqCst,
1365
0
    ) {
1366
0
        Ok(s) | Err(s) => s,
1367
0
    };
1368
0
    match old_state {
1369
        UNINITIALIZED => {
1370
0
            unsafe {
1371
0
                LOGGER = make_logger();
1372
0
            }
1373
0
            STATE.store(INITIALIZED, Ordering::SeqCst);
1374
0
            Ok(())
1375
        }
1376
        INITIALIZING => {
1377
0
            while STATE.load(Ordering::SeqCst) == INITIALIZING {
1378
0
                // TODO: replace with `hint::spin_loop` once MSRV is 1.49.0.
1379
0
                #[allow(deprecated)]
1380
0
                std::sync::atomic::spin_loop_hint();
1381
0
            }
1382
0
            Err(SetLoggerError(()))
1383
        }
1384
0
        _ => Err(SetLoggerError(())),
1385
    }
1386
0
}
Unexecuted instantiation: log::set_logger_inner::<log::set_boxed_logger::{closure#0}>
Unexecuted instantiation: log::set_logger_inner::<log::set_logger::{closure#0}>
1387
1388
/// A thread-unsafe version of [`set_logger`].
1389
///
1390
/// This function is available on all platforms, even those that do not have
1391
/// support for atomics that is needed by [`set_logger`].
1392
///
1393
/// In almost all cases, [`set_logger`] should be preferred.
1394
///
1395
/// # Safety
1396
///
1397
/// This function is only safe to call when no other logger initialization
1398
/// function is called while this function still executes.
1399
///
1400
/// This can be upheld by (for example) making sure that **there are no other
1401
/// threads**, and (on embedded) that **interrupts are disabled**.
1402
///
1403
/// It is safe to use other logging functions while this function runs
1404
/// (including all logging macros).
1405
///
1406
/// [`set_logger`]: fn.set_logger.html
1407
0
pub unsafe fn set_logger_racy(logger: &'static dyn Log) -> Result<(), SetLoggerError> {
1408
0
    match STATE.load(Ordering::SeqCst) {
1409
        UNINITIALIZED => {
1410
0
            LOGGER = logger;
1411
0
            STATE.store(INITIALIZED, Ordering::SeqCst);
1412
0
            Ok(())
1413
        }
1414
        INITIALIZING => {
1415
            // This is just plain UB, since we were racing another initialization function
1416
0
            unreachable!("set_logger_racy must not be used with other initialization functions")
1417
        }
1418
0
        _ => Err(SetLoggerError(())),
1419
    }
1420
0
}
1421
1422
/// The type returned by [`set_logger`] if [`set_logger`] has already been called.
1423
///
1424
/// [`set_logger`]: fn.set_logger.html
1425
#[allow(missing_copy_implementations)]
1426
0
#[derive(Debug)]
1427
pub struct SetLoggerError(());
1428
1429
impl fmt::Display for SetLoggerError {
1430
0
    fn fmt(&self, fmt: &mut fmt::Formatter) -> fmt::Result {
1431
0
        fmt.write_str(SET_LOGGER_ERROR)
1432
0
    }
1433
}
1434
1435
// The Error trait is not available in libcore
1436
#[cfg(feature = "std")]
1437
impl error::Error for SetLoggerError {}
1438
1439
/// The type returned by [`from_str`] when the string doesn't match any of the log levels.
1440
///
1441
/// [`from_str`]: https://doc.rust-lang.org/std/str/trait.FromStr.html#tymethod.from_str
1442
#[allow(missing_copy_implementations)]
1443
0
#[derive(Debug, PartialEq, Eq)]
1444
pub struct ParseLevelError(());
1445
1446
impl fmt::Display for ParseLevelError {
1447
0
    fn fmt(&self, fmt: &mut fmt::Formatter) -> fmt::Result {
1448
0
        fmt.write_str(LEVEL_PARSE_ERROR)
1449
0
    }
1450
}
1451
1452
// The Error trait is not available in libcore
1453
#[cfg(feature = "std")]
1454
impl error::Error for ParseLevelError {}
1455
1456
/// Returns a reference to the logger.
1457
///
1458
/// If a logger has not been set, a no-op implementation is returned.
1459
0
pub fn logger() -> &'static dyn Log {
1460
0
    // Acquire memory ordering guarantees that current thread would see any
1461
0
    // memory writes that happened before store of the value
1462
0
    // into `STATE` with memory ordering `Release` or stronger.
1463
0
    //
1464
0
    // Since the value `INITIALIZED` is written only after `LOGGER` was
1465
0
    // initialized, observing it after `Acquire` load here makes both
1466
0
    // write to the `LOGGER` static and initialization of the logger
1467
0
    // internal state synchronized with current thread.
1468
0
    if STATE.load(Ordering::Acquire) != INITIALIZED {
1469
        static NOP: NopLogger = NopLogger;
1470
0
        &NOP
1471
    } else {
1472
0
        unsafe { LOGGER }
1473
    }
1474
0
}
1475
1476
// WARNING: this is not part of the crate's public API and is subject to change at any time
1477
#[doc(hidden)]
1478
pub mod __private_api;
1479
1480
/// The statically resolved maximum log level.
1481
///
1482
/// See the crate level documentation for information on how to configure this.
1483
///
1484
/// This value is checked by the log macros, but not by the `Log`ger returned by
1485
/// the [`logger`] function. Code that manually calls functions on that value
1486
/// should compare the level against this value.
1487
///
1488
/// [`logger`]: fn.logger.html
1489
pub const STATIC_MAX_LEVEL: LevelFilter = match cfg!(debug_assertions) {
1490
    false if cfg!(feature = "release_max_level_off") => LevelFilter::Off,
1491
    false if cfg!(feature = "release_max_level_error") => LevelFilter::Error,
1492
    false if cfg!(feature = "release_max_level_warn") => LevelFilter::Warn,
1493
    false if cfg!(feature = "release_max_level_info") => LevelFilter::Info,
1494
    false if cfg!(feature = "release_max_level_debug") => LevelFilter::Debug,
1495
    false if cfg!(feature = "release_max_level_trace") => LevelFilter::Trace,
1496
    _ if cfg!(feature = "max_level_off") => LevelFilter::Off,
1497
    _ if cfg!(feature = "max_level_error") => LevelFilter::Error,
1498
    _ if cfg!(feature = "max_level_warn") => LevelFilter::Warn,
1499
    _ if cfg!(feature = "max_level_info") => LevelFilter::Info,
1500
    _ if cfg!(feature = "max_level_debug") => LevelFilter::Debug,
1501
    _ => LevelFilter::Trace,
1502
};
1503
1504
#[cfg(test)]
1505
mod tests {
1506
    use super::{Level, LevelFilter, ParseLevelError, STATIC_MAX_LEVEL};
1507
1508
    #[test]
1509
    fn test_levelfilter_from_str() {
1510
        let tests = [
1511
            ("off", Ok(LevelFilter::Off)),
1512
            ("error", Ok(LevelFilter::Error)),
1513
            ("warn", Ok(LevelFilter::Warn)),
1514
            ("info", Ok(LevelFilter::Info)),
1515
            ("debug", Ok(LevelFilter::Debug)),
1516
            ("trace", Ok(LevelFilter::Trace)),
1517
            ("OFF", Ok(LevelFilter::Off)),
1518
            ("ERROR", Ok(LevelFilter::Error)),
1519
            ("WARN", Ok(LevelFilter::Warn)),
1520
            ("INFO", Ok(LevelFilter::Info)),
1521
            ("DEBUG", Ok(LevelFilter::Debug)),
1522
            ("TRACE", Ok(LevelFilter::Trace)),
1523
            ("asdf", Err(ParseLevelError(()))),
1524
        ];
1525
        for &(s, ref expected) in &tests {
1526
            assert_eq!(expected, &s.parse());
1527
        }
1528
    }
1529
1530
    #[test]
1531
    fn test_level_from_str() {
1532
        let tests = [
1533
            ("OFF", Err(ParseLevelError(()))),
1534
            ("error", Ok(Level::Error)),
1535
            ("warn", Ok(Level::Warn)),
1536
            ("info", Ok(Level::Info)),
1537
            ("debug", Ok(Level::Debug)),
1538
            ("trace", Ok(Level::Trace)),
1539
            ("ERROR", Ok(Level::Error)),
1540
            ("WARN", Ok(Level::Warn)),
1541
            ("INFO", Ok(Level::Info)),
1542
            ("DEBUG", Ok(Level::Debug)),
1543
            ("TRACE", Ok(Level::Trace)),
1544
            ("asdf", Err(ParseLevelError(()))),
1545
        ];
1546
        for &(s, ref expected) in &tests {
1547
            assert_eq!(expected, &s.parse());
1548
        }
1549
    }
1550
1551
    #[test]
1552
    fn test_level_as_str() {
1553
        let tests = &[
1554
            (Level::Error, "ERROR"),
1555
            (Level::Warn, "WARN"),
1556
            (Level::Info, "INFO"),
1557
            (Level::Debug, "DEBUG"),
1558
            (Level::Trace, "TRACE"),
1559
        ];
1560
        for (input, expected) in tests {
1561
            assert_eq!(*expected, input.as_str());
1562
        }
1563
    }
1564
1565
    #[test]
1566
    fn test_level_show() {
1567
        assert_eq!("INFO", Level::Info.to_string());
1568
        assert_eq!("ERROR", Level::Error.to_string());
1569
    }
1570
1571
    #[test]
1572
    fn test_levelfilter_show() {
1573
        assert_eq!("OFF", LevelFilter::Off.to_string());
1574
        assert_eq!("ERROR", LevelFilter::Error.to_string());
1575
    }
1576
1577
    #[test]
1578
    fn test_cross_cmp() {
1579
        assert!(Level::Debug > LevelFilter::Error);
1580
        assert!(LevelFilter::Warn < Level::Trace);
1581
        assert!(LevelFilter::Off < Level::Error);
1582
    }
1583
1584
    #[test]
1585
    fn test_cross_eq() {
1586
        assert!(Level::Error == LevelFilter::Error);
1587
        assert!(LevelFilter::Off != Level::Error);
1588
        assert!(Level::Trace == LevelFilter::Trace);
1589
    }
1590
1591
    #[test]
1592
    fn test_to_level() {
1593
        assert_eq!(Some(Level::Error), LevelFilter::Error.to_level());
1594
        assert_eq!(None, LevelFilter::Off.to_level());
1595
        assert_eq!(Some(Level::Debug), LevelFilter::Debug.to_level());
1596
    }
1597
1598
    #[test]
1599
    fn test_to_level_filter() {
1600
        assert_eq!(LevelFilter::Error, Level::Error.to_level_filter());
1601
        assert_eq!(LevelFilter::Trace, Level::Trace.to_level_filter());
1602
    }
1603
1604
    #[test]
1605
    fn test_level_filter_as_str() {
1606
        let tests = &[
1607
            (LevelFilter::Off, "OFF"),
1608
            (LevelFilter::Error, "ERROR"),
1609
            (LevelFilter::Warn, "WARN"),
1610
            (LevelFilter::Info, "INFO"),
1611
            (LevelFilter::Debug, "DEBUG"),
1612
            (LevelFilter::Trace, "TRACE"),
1613
        ];
1614
        for (input, expected) in tests {
1615
            assert_eq!(*expected, input.as_str());
1616
        }
1617
    }
1618
1619
    #[test]
1620
    #[cfg_attr(not(debug_assertions), ignore)]
1621
    fn test_static_max_level_debug() {
1622
        if cfg!(feature = "max_level_off") {
1623
            assert_eq!(STATIC_MAX_LEVEL, LevelFilter::Off);
1624
        } else if cfg!(feature = "max_level_error") {
1625
            assert_eq!(STATIC_MAX_LEVEL, LevelFilter::Error);
1626
        } else if cfg!(feature = "max_level_warn") {
1627
            assert_eq!(STATIC_MAX_LEVEL, LevelFilter::Warn);
1628
        } else if cfg!(feature = "max_level_info") {
1629
            assert_eq!(STATIC_MAX_LEVEL, LevelFilter::Info);
1630
        } else if cfg!(feature = "max_level_debug") {
1631
            assert_eq!(STATIC_MAX_LEVEL, LevelFilter::Debug);
1632
        } else {
1633
            assert_eq!(STATIC_MAX_LEVEL, LevelFilter::Trace);
1634
        }
1635
    }
1636
1637
    #[test]
1638
    #[cfg_attr(debug_assertions, ignore)]
1639
    fn test_static_max_level_release() {
1640
        if cfg!(feature = "release_max_level_off") {
1641
            assert_eq!(STATIC_MAX_LEVEL, LevelFilter::Off);
1642
        } else if cfg!(feature = "release_max_level_error") {
1643
            assert_eq!(STATIC_MAX_LEVEL, LevelFilter::Error);
1644
        } else if cfg!(feature = "release_max_level_warn") {
1645
            assert_eq!(STATIC_MAX_LEVEL, LevelFilter::Warn);
1646
        } else if cfg!(feature = "release_max_level_info") {
1647
            assert_eq!(STATIC_MAX_LEVEL, LevelFilter::Info);
1648
        } else if cfg!(feature = "release_max_level_debug") {
1649
            assert_eq!(STATIC_MAX_LEVEL, LevelFilter::Debug);
1650
        } else if cfg!(feature = "release_max_level_trace") {
1651
            assert_eq!(STATIC_MAX_LEVEL, LevelFilter::Trace);
1652
        } else if cfg!(feature = "max_level_off") {
1653
            assert_eq!(STATIC_MAX_LEVEL, LevelFilter::Off);
1654
        } else if cfg!(feature = "max_level_error") {
1655
            assert_eq!(STATIC_MAX_LEVEL, LevelFilter::Error);
1656
        } else if cfg!(feature = "max_level_warn") {
1657
            assert_eq!(STATIC_MAX_LEVEL, LevelFilter::Warn);
1658
        } else if cfg!(feature = "max_level_info") {
1659
            assert_eq!(STATIC_MAX_LEVEL, LevelFilter::Info);
1660
        } else if cfg!(feature = "max_level_debug") {
1661
            assert_eq!(STATIC_MAX_LEVEL, LevelFilter::Debug);
1662
        } else {
1663
            assert_eq!(STATIC_MAX_LEVEL, LevelFilter::Trace);
1664
        }
1665
    }
1666
1667
    #[test]
1668
    #[cfg(feature = "std")]
1669
    fn test_error_trait() {
1670
        use super::SetLoggerError;
1671
        let e = SetLoggerError(());
1672
        assert_eq!(
1673
            &e.to_string(),
1674
            "attempted to set a logger after the logging system \
1675
             was already initialized"
1676
        );
1677
    }
1678
1679
    #[test]
1680
    fn test_metadata_builder() {
1681
        use super::MetadataBuilder;
1682
        let target = "myApp";
1683
        let metadata_test = MetadataBuilder::new()
1684
            .level(Level::Debug)
1685
            .target(target)
1686
            .build();
1687
        assert_eq!(metadata_test.level(), Level::Debug);
1688
        assert_eq!(metadata_test.target(), "myApp");
1689
    }
1690
1691
    #[test]
1692
    fn test_metadata_convenience_builder() {
1693
        use super::Metadata;
1694
        let target = "myApp";
1695
        let metadata_test = Metadata::builder()
1696
            .level(Level::Debug)
1697
            .target(target)
1698
            .build();
1699
        assert_eq!(metadata_test.level(), Level::Debug);
1700
        assert_eq!(metadata_test.target(), "myApp");
1701
    }
1702
1703
    #[test]
1704
    fn test_record_builder() {
1705
        use super::{MetadataBuilder, RecordBuilder};
1706
        let target = "myApp";
1707
        let metadata = MetadataBuilder::new().target(target).build();
1708
        let fmt_args = format_args!("hello");
1709
        let record_test = RecordBuilder::new()
1710
            .args(fmt_args)
1711
            .metadata(metadata)
1712
            .module_path(Some("foo"))
1713
            .file(Some("bar"))
1714
            .line(Some(30))
1715
            .build();
1716
        assert_eq!(record_test.metadata().target(), "myApp");
1717
        assert_eq!(record_test.module_path(), Some("foo"));
1718
        assert_eq!(record_test.file(), Some("bar"));
1719
        assert_eq!(record_test.line(), Some(30));
1720
    }
1721
1722
    #[test]
1723
    fn test_record_convenience_builder() {
1724
        use super::{Metadata, Record};
1725
        let target = "myApp";
1726
        let metadata = Metadata::builder().target(target).build();
1727
        let fmt_args = format_args!("hello");
1728
        let record_test = Record::builder()
1729
            .args(fmt_args)
1730
            .metadata(metadata)
1731
            .module_path(Some("foo"))
1732
            .file(Some("bar"))
1733
            .line(Some(30))
1734
            .build();
1735
        assert_eq!(record_test.target(), "myApp");
1736
        assert_eq!(record_test.module_path(), Some("foo"));
1737
        assert_eq!(record_test.file(), Some("bar"));
1738
        assert_eq!(record_test.line(), Some(30));
1739
    }
1740
1741
    #[test]
1742
    fn test_record_complete_builder() {
1743
        use super::{Level, Record};
1744
        let target = "myApp";
1745
        let record_test = Record::builder()
1746
            .module_path(Some("foo"))
1747
            .file(Some("bar"))
1748
            .line(Some(30))
1749
            .target(target)
1750
            .level(Level::Error)
1751
            .build();
1752
        assert_eq!(record_test.target(), "myApp");
1753
        assert_eq!(record_test.level(), Level::Error);
1754
        assert_eq!(record_test.module_path(), Some("foo"));
1755
        assert_eq!(record_test.file(), Some("bar"));
1756
        assert_eq!(record_test.line(), Some(30));
1757
    }
1758
1759
    #[test]
1760
    #[cfg(feature = "kv")]
1761
    fn test_record_key_values_builder() {
1762
        use super::Record;
1763
        use crate::kv::{self, VisitSource};
1764
1765
        struct TestVisitSource {
1766
            seen_pairs: usize,
1767
        }
1768
1769
        impl<'kvs> VisitSource<'kvs> for TestVisitSource {
1770
            fn visit_pair(
1771
                &mut self,
1772
                _: kv::Key<'kvs>,
1773
                _: kv::Value<'kvs>,
1774
            ) -> Result<(), kv::Error> {
1775
                self.seen_pairs += 1;
1776
                Ok(())
1777
            }
1778
        }
1779
1780
        let kvs: &[(&str, i32)] = &[("a", 1), ("b", 2)];
1781
        let record_test = Record::builder().key_values(&kvs).build();
1782
1783
        let mut visitor = TestVisitSource { seen_pairs: 0 };
1784
1785
        record_test.key_values().visit(&mut visitor).unwrap();
1786
1787
        assert_eq!(2, visitor.seen_pairs);
1788
    }
1789
1790
    #[test]
1791
    #[cfg(feature = "kv")]
1792
    fn test_record_key_values_get_coerce() {
1793
        use super::Record;
1794
1795
        let kvs: &[(&str, &str)] = &[("a", "1"), ("b", "2")];
1796
        let record = Record::builder().key_values(&kvs).build();
1797
1798
        assert_eq!(
1799
            "2",
1800
            record
1801
                .key_values()
1802
                .get("b".into())
1803
                .expect("missing key")
1804
                .to_borrowed_str()
1805
                .expect("invalid value")
1806
        );
1807
    }
1808
1809
    // Test that the `impl Log for Foo` blocks work
1810
    // This test mostly operates on a type level, so failures will be compile errors
1811
    #[test]
1812
    fn test_foreign_impl() {
1813
        use super::Log;
1814
        #[cfg(feature = "std")]
1815
        use std::sync::Arc;
1816
1817
        fn assert_is_log<T: Log + ?Sized>() {}
1818
1819
        assert_is_log::<&dyn Log>();
1820
1821
        #[cfg(feature = "std")]
1822
        assert_is_log::<Box<dyn Log>>();
1823
1824
        #[cfg(feature = "std")]
1825
        assert_is_log::<Arc<dyn Log>>();
1826
1827
        // Assert these statements for all T: Log + ?Sized
1828
        #[allow(unused)]
1829
        fn forall<T: Log + ?Sized>() {
1830
            #[cfg(feature = "std")]
1831
            assert_is_log::<Box<T>>();
1832
1833
            assert_is_log::<&T>();
1834
1835
            #[cfg(feature = "std")]
1836
            assert_is_log::<Arc<T>>();
1837
        }
1838
    }
1839
}