Tracing Subscriber

https://docs.rs/tracing-subscriber/latest/
Admin
Tracing Subscriber provides utilities for implementing and composing `tracing` subscribers, offering...
Tokens:453,694
Snippets:3,159
Trust Score:9.7
Update:1 week ago
Show doc for...
Tokens:
Raw
### Example output of fmt-pretty

Source: https://docs.rs/tracing-subscriber/latest/tracing_subscriber/fmt/format/struct.Pretty.html

Example output from running `cargo run --example fmt-pretty`, showing the multi-line, pretty-printed log output with timestamps, levels, spans, and fields.

```text
**:;** cargo run --example fmt-pretty
**    Finished** dev [unoptimized + debuginfo] target(s) in 0.08s
**     Running** `target/debug/examples/fmt-pretty`
  2022-02-15T18:44:24.535324Z  INFO **fmt_pretty**: preparing to shave yaks, **number_of_yaks**: 3
     _at_ examples/examples/fmt-pretty.rs:16 _on_ main

  2022-02-15T18:44:24.535403Z  INFO **fmt_pretty::yak_shave**: shaving yaks
    _at_ examples/examples/fmt/yak_shave.rs:41 _on_ main
    _in_ fmt_pretty::yak_shave::**shaving_yaks** _with_ **yaks**: 3

  2022-02-15T18:44:24.535442Z TRACE **fmt_pretty::yak_shave**: hello! I'm gonna shave a yak, **excitement**: "yay!"
    _at_ examples/examples/fmt/yak_shave.rs:16 _on_ main
    _in_ fmt_pretty::yak_shave::**shave** _with_ **yak**: 1
    _in_ fmt_pretty::yak_shave::**shaving_yaks** _with_ **yaks**: 3

  2022-02-15T18:44:24.535469Z TRACE **fmt_pretty::yak_shave**: yak shaved successfully
    _at_ examples/examples/fmt/yak_shave.rs:25 _on_ main
    _in_ fmt_pretty::yak_shave::**shave** _with_ **yak**: 1
    _in_ fmt_pretty::yak_shave::**shaving_yaks** _with_ **yaks**: 3

  2022-02-15T18:44:24.535502Z DEBUG **yak_events**: **yak**: 1, **shaved**: true
    _at_ examples/examples/fmt/yak_shave.rs:46 _on_ main
    _in_ fmt_pretty::yak_shave::**shaving_yaks** _with_ **yaks**: 3

  2022-02-15T18:44:24.535524Z TRACE **fmt_pretty::yak_shave**: **yaks_shaved**: 1
    _at_ examples/examples/fmt/yak_shave.rs:55 _on_ main
    _in_ fmt_pretty::yak_shave::**shaving_yaks** _with_ **yaks**: 3

  2022-02-15T18:44:24.535551Z TRACE **fmt_pretty::yak_shave**: hello! I'm gonna shave a yak, **excitement**: "yay!"
    _at_ examples/examples/fmt/yak_shave.rs:16 _on_ main
    _in_ fmt_pretty::yak_shave::**shave** _with_ **yak**: 2
    _in_ fmt_pretty::yak_shave::**shaving_yaks** _with_ **yaks**: 3

  2022-02-15T18:44:24.535573Z TRACE **fmt_pretty::yak_shave**: yak shaved successfully
    _at_ examples/examples/fmt/yak_shave.rs:25 _on_ main
    _in_ fmt_pretty::yak_shave::**shave** _with_ **yak**: 2
    _in_ fmt_pretty::yak_shave::**shaving_yaks** _with_ **yaks**: 3

  2022-02-15T18:44:24.535600Z DEBUG **yak_events**: **yak**: 2, **shaved**: true
    _at_ examples/examples/fmt/yak_shave.rs:46 _on_ main
    _in_ fmt_pretty::yak_shave::**shaving_yaks** _with_ **yaks**: 3

  2022-02-15T18:44:24.535618Z TRACE **fmt_pretty::yak_shave**: **yaks_shaved**: 2
    _at_ examples/examples/fmt/yak_shave.rs:55 _on_ main
    _in_ fmt_pretty::yak_shave::**shaving_yaks** _with_ **yaks**: 3

  2022-02-15T18:44:24.535644Z TRACE **fmt_pretty::yak_shave**: hello! I'm gonna shave a yak, **excitement**: "yay!"
    _at_ examples/examples/fmt/yak_shave.rs:16 _on_ main
    _in_ fmt_pretty::yak_shave::**shave** _with_ **yak**: 3
    _in_ fmt_pretty::yak_shave::**shaving_yaks** _with_ **yaks**: 3

  2022-02-15T18:44:24.535670Z  WARN **fmt_pretty::yak_shave**: could not locate yak
    _at_ examples/examples/fmt/yak_shave.rs:18 _on_ main
    _in_ fmt_pretty::yak_shave::**shave** _with_ **yak**: 3
    _in_ fmt_pretty::yak_shave::**shaving_yaks** _with_ **yaks**: 3

  2022-02-15T18:44:24.535698Z DEBUG **yak_events**: **yak**: 3, **shaved**: false
    _at_ examples/examples/fmt/yak_shave.rs:46 _on_ main
    _in_ fmt_pretty::yak_shave::**shaving_yaks** _with_ **yaks**: 3

  2022-02-15T18:44:24.535720Z ERROR **fmt_pretty::yak_shave**: failed to shave yak, **yak**: 3, **error**: missing yak, **error.sources**: [out of space, out of cash]
    _at_ examples/examples/fmt/yak_shave.rs:51 _on_ main
    _in_ fmt_pretty::yak_shave::**shaving_yaks** _with_ **yaks**: 3

  2022-02-15T18:44:24.535742Z TRACE **fmt_pretty::yak_shave**: **yaks_shaved**: 2
    _at_ examples/examples/fmt/yak_shave.rs:55 _on_ main
    _in_ fmt_pretty::yak_shave::**shaving_yaks** _with_ **yaks**: 3

  2022-02-15T18:44:24.535765Z  INFO **fmt_pretty**: yak shaving completed, **all_yaks_shaved**: false
    _at_ examples/examples/fmt-pretty.rs:19 _on_ main

```

--------------------------------

### Default format example output

Source: https://docs.rs/tracing-subscriber/latest/src/tracing_subscriber/fmt/format/mod.rs.html

Example output from running `cargo run --example fmt` with the default format. It shows span context (e.g., `shaving_yaks{yaks=3}`) and event fields, demonstrating how spans and events are displayed.

```text
cargo run --example fmt
    Finished dev [unoptimized + debuginfo] target(s) in 0.08s
     Running `target/debug/examples/fmt`
2022-02-15T18:40:14.289898Z  INFO fmt: preparing to shave yaks number_of_yaks=3
2022-02-15T18:40:14.289974Z  INFO shaving_yaks{yaks=3}: fmt::yak_shave: shaving yaks
2022-02-15T18:40:14.290011Z TRACE shaving_yaks{yaks=3}:shave{yak=1}: fmt::yak_shave: hello! I'm gonna shave a yak excitement="yay!"
2022-02-15T18:40:14.290038Z TRACE shaving_yaks{yaks=3}:shave{yak=1}: fmt::yak_shave: yak shaved successfully
2022-02-15T18:40:14.290070Z DEBUG shaving_yaks{yaks=3}: yak_events: yak=1 shaved=true
2022-02-15T18:40:14.290089Z TRACE shaving_yaks{yaks=3}: fmt::yak_shave: yaks_shaved=1
2022-02-15T18:40:14.290114Z TRACE shaving_yaks{yaks=3}:shave{yak=2}: fmt::yak_shave: hello! I'm gonna shave a yak excitement="yay!"
2022-02-15T18:40:14.290134Z TRACE shaving_yaks{yaks=3}:shave{yak=2}: fmt::yak_shave: yak shaved successfully
2022-02-15T18:40:14.290157Z DEBUG shaving_yaks{yaks=3}: yak_events: yak=2 shaved=true
2022-02-15T18:40:14.290174Z TRACE shaving_yaks{yaks=3}: fmt::yak_shave: yaks_shaved=2
2022-02-15T18:40:14.290198Z TRACE shaving_yaks{yaks=3}:shave{yak=3}: fmt::yak_shave: hello! I'm gonna shave a yak excitement="yay!"
2022-02-15T18:40:14.290222Z  WARN shaving_yaks{yaks=3}:shave{yak=3}: fmt::yak_shave: could not locate yak
2022-02-15T18:40:14.290247Z DEBUG shaving_yaks{yaks=3}: yak_events: yak=3 shaved=false
```

--------------------------------

### String::capacity example

Source: https://docs.rs/tracing-subscriber/latest/tracing_subscriber/fmt/struct.FormattedFields.html

Example for the `capacity` method inherited from `String`, showing how to check the capacity of a string.

```rust
let s = String::with_capacity(10);

assert!(s.capacity() >= 10);
```

--------------------------------

### Example output of Full format

Source: https://docs.rs/tracing-subscriber/latest/tracing_subscriber/fmt/format/struct.Full.html

Shows the output of running `cargo run --example fmt` with the `Full` formatter, displaying span context and event data.

```text
**:;** cargo run --example fmt
**    Finished** dev [unoptimized + debuginfo] target(s) in 0.08s
**     Running** `target/debug/examples/fmt`
2022-02-15T18:40:14.289898Z  INFO fmt: preparing to shave yaks  _number_of_yaks_=3
2022-02-15T18:40:14.289974Z  INFO **shaving_yaks{**_yaks_=3**}**: fmt::yak_shave: shaving yaks
2022-02-15T18:40:14.290011Z TRACE **shaving_yaks{**_yaks_=3**}**:**shave{**_yak_=1**}**: fmt::yak_shave: hello! I'm gonna shave a yak _excitement_="yay!"
2022-02-15T18:40:14.290038Z TRACE **shaving_yaks{**_yaks_=3**}**:**shave{**_yak_=1**}**: fmt::yak_shave: yak shaved successfully
2022-02-15T18:40:14.290070Z DEBUG **shaving_yaks{**_yaks_=3**}**: yak_events: _yak_=1 _shaved_=true
2022-02-15T18:40:14.290089Z TRACE **shaving_yaks{**_yaks_=3**}**: fmt::yak_shave: _yaks_shaved_=1
2022-02-15T18:40:14.290114Z TRACE **shaving_yaks{**_yaks_=3**}**:**shave{**_yak_=2**}**: fmt::yak_shave: hello! I'm gonna shave a yak _excitement_="yay!"
2022-02-15T18:40:14.290134Z TRACE **shaving_yaks{**_yaks_=3**}**:**shave{**_yak_=2**}**: fmt::yak_shave: yak shaved successfully
2022-02-15T18:40:14.290157Z DEBUG **shaving_yaks{**_yaks_=3**}**: yak_events: _yak_=2 _shaved_=true
2022-02-15T18:40:14.290174Z TRACE **shaving_yaks{**_yaks_=3**}**: fmt::yak_shave: _yaks_shaved_=2
2022-02-15T18:40:14.290198Z TRACE **shaving_yaks{**_yaks_=3**}**:**shave{**_yak_=3**}**: fmt::yak_shave: hello! I'm gonna shave a yak _excitement_="yay!"
2022-02-15T18:40:14.290222Z  WARN **shaving_yaks{**_yaks_=3**}**:**shave{**_yak_=3**}**: fmt::yak_shave: could not locate yak
2022-02-15T18:40:14.290247Z DEBUG **shaving_yaks{**_yaks_=3**}**: yak_events: _yak_=3 _shaved_=false
2022-02-15T18:40:14.290268Z ERROR **shaving_yaks{**_yaks_=3**}**: fmt::yak_shave: failed to shave yak _yak_=3 _error_=missing yak _error.sources_=[out of space, out of cash]
2022-02-15T18:40:14.290287Z TRACE **shaving_yaks{**_yaks_=3**}**: fmt::yak_shave: _yaks_shaved_=2
2022-02-15T18:40:14.290309Z  INFO fmt: yak shaving completed. _all_yaks_shaved_=false

```

--------------------------------

### Example output of fmt-pretty

Source: https://docs.rs/tracing-subscriber/latest/src/tracing_subscriber/fmt/format/pretty.rs.html

Shows the multi-line output produced by the pretty formatter when running the fmt-pretty example, including colored levels, timestamps, and context lines.

```text
:; cargo run --example fmt-pretty
    Finished dev [unoptimized + debuginfo] target(s) in 0.08s
     Running `target/debug/examples/fmt-pretty`
  2022-02-15T18:44:24.535324Z  INFO fmt_pretty: preparing to shave yaks, number_of_yaks: 3
     at examples/examples/fmt-pretty.rs:16 on main

  2022-02-15T18:44:24.535403Z  INFO fmt_pretty::yak_shave: shaving yaks
     at examples/examples/fmt/yak_shave.rs:41 on main
     in fmt_pretty::yak_shave::shaving_yaks with yaks: 3

  2022-02-15T18:44:24.535442Z TRACE fmt_pretty::yak_shave: hello! I'm gonna shave a yak, excitement: "yay!"
     at examples/examples/fmt/yak_shave.rs:16 on main
     in fmt_pretty::yak_shave::shave with yak: 1
     in fmt_pretty::yak_shave::shaving_yaks with yaks: 3

  2022-02-15T18:44:24.535469Z TRACE fmt_pretty::yak_shave: yak shaved successfully
     at examples/examples/fmt/yak_shave.rs:25 on main
     in fmt_pretty::yak_shave::shave with yak: 1
     in fmt_pretty::yak_shave::shaving_yaks with yaks: 3

  2022-02-15T18:44:24.535502Z DEBUG yak_events: yak: 1, shaved: true
     at examples/examples/fmt/yak_shave.rs:46 on main
     in fmt_pretty::yak_shave::shaving_yaks with yaks: 3

  2022-02-15T18:44:24.535524Z TRACE fmt_pretty::yak_shave: yaks_shaved: 1
     at examples/examples/fmt/yak_shave.rs:55 on main
     in fmt_pretty::yak_shave::shaving_yaks with yaks: 3

  2022-02-15T18:44:24.535551Z TRACE fmt_pretty::yak_shave: hello! I'm gonna shave a yak, excitement: "yay!"
     at examples/examples/fmt/yak_shave.rs:16 on main
     in fmt_pretty::yak_shave::shave with yak: 2
     in fmt_pretty::yak_shave::shaving_yaks with yaks: 3
```

--------------------------------

### String::as_bytes example

Source: https://docs.rs/tracing-subscriber/latest/tracing_subscriber/fmt/struct.FormattedFields.html

Example for the `as_bytes` method inherited from `String`, showing how to get a byte slice of the string's contents.

```rust
let s = String::from("hello");

assert_eq!(&[104, 101, 108, 108, 111], s.as_bytes());
```

--------------------------------

### try_init: Install global subscriber with RUST_LOG filtering

Source: https://docs.rs/tracing-subscriber/latest/src/tracing_subscriber/fmt/mod.rs.html

Shorthand for initializing a global subscriber with fmt().try_init(). Returns an error if a global subscriber is already installed.

```rust
# fn doc() -> Result<(), Box<dyn std::error::Error + Send + Sync + 'static>> {
tracing_subscriber::fmt().try_init()
# }
```

--------------------------------

### pub fn init()

Source: https://docs.rs/tracing-subscriber/latest/src/tracing_subscriber/fmt/mod.rs.html

Installs a global tracing subscriber that listens for events and filters based on the RUST_LOG environment variable. Panics if initialization fails because a global subscriber is already installed.

```APIDOC
## pub fn init()

### Description
Installs a global tracing subscriber that listens for events and filters based on the value of the `RUST_LOG` environment variable. The configuration depends on enabled feature flags. If the `tracing-log` feature is enabled, it also installs the LogTracer to convert `Log` records into `tracing` `Event`s. If the `env-filter` feature is enabled, this is shorthand for `tracing_subscriber::fmt().with_env_filter(EnvFilter::from_default_env()).init()`.

### Method
Function call

### Signature
```rust
pub fn init()
```

### Parameters
None

### Panics
Panics if the initialization was unsuccessful, likely because a global subscriber was already installed by another call to `try_init`.

### Example
```rust
tracing_subscriber::fmt::init();
```
```

--------------------------------

### Example: Using And combinator

Source: https://docs.rs/tracing-subscriber/latest/src/tracing_subscriber/filter/layer_filters/combinator.rs.html

Example from the And::new documentation showing how to combine a target filter and a level filter so that spans and events are enabled only when both filters pass. The example is marked with `ignore` in the source, so it is not compiled or run.

```rust
use tracing_subscriber::{
    filter::{filter_fn, LevelFilter, combinator::And},
    prelude::*,
};

// Enables spans and events with targets starting with `interesting_target`:
let target_filter = filter_fn(|meta| {
    meta.target().starts_with("interesting_target")
});

// Enables spans and events with levels `INFO` and below:
let level_filter = LevelFilter::INFO;

// Combine the two filters together so that a span or event is only enabled
// if *both* filters would enable it:
let filter = And::new(level_filter, target_filter);

tracing_subscriber::registry()
    .with(tracing_subscriber::fmt::layer().with_filter(filter))
    .init();

// This event will *not* be enabled:
tracing::info!("an event with an uninteresting target");

// This event *will* be enabled:
tracing::info!(target: "interesting_target", "a very interesting event");

// This event will *not* be enabled:
tracing::debug!(target: "interesting_target", "interesting debug event...");
```

--------------------------------

### Example output of fmt-json example

Source: https://docs.rs/tracing-subscriber/latest/src/tracing_subscriber/fmt/format/json.rs.html

Shows the output of running `cargo run --example fmt-json`, which produces newline-delimited JSON log lines. The output includes timestamp, level, fields, target, and spans information.

```text
:; cargo run --example fmt-json
    Finished dev [unoptimized + debuginfo] target(s) in 0.08s
     Running `target/debug/examples/fmt-json`
{"timestamp":"2022-02-15T18:47:10.821315Z","level":"INFO","fields":{"message":"preparing to shave yaks","number_of_yaks":3},"target":"fmt_json"}
{"timestamp":"2022-02-15T18:47:10.821422Z","level":"INFO","fields":{"message":"shaving yaks"},"target":"fmt_json::yak_shave","spans":[{"yaks":3,"name":"shaving_yaks"}]}
{"timestamp":"2022-02-15T18:47:10.821495Z","level":"TRACE","fields":{"message":"hello! I'm gonna shave a yak","excitement":"yay!"},"target":"fmt_json::yak_shave","spans":[{"yaks":3,"name":"shaving_yaks"},{"yak":1,"name":"shave"}]}
{"timestamp":"2022-02-15T18:47:10.821546Z","level":"TRACE","fields":{"message":"yak shaved successfully"},"target":"fmt_json::yak_shave","spans":[{"yaks":3,"name":"shaving_yaks"},{"yak":1,"name":"shave"}]}
{"timestamp":"2022-02-15T18:47:10.821598Z","level":"DEBUG","fields":{"yak":1,"shaved":true},"target":"yak_events","spans":[{"yaks":3,"name":"shaving_yaks"}]}
{"timestamp":"2022-02-15T18:47:10.821637Z","level":"TRACE","fields":{"yaks_shaved":1},"target":"fmt_json::yak_shave","spans":[{"yaks":3,"name":"shaving_yaks"}]}
{"timestamp":"2022-02-15T18:47:10.821684Z","level":"TRACE","fields":{"message":"hello! I'm gonna shave a yak","excitement":"yay!"},"target":"fmt_json::yak_shave","spans":[{"yaks":3,"name":"shaving_yaks"},{"yak":2,"name":"shave"}]}
{"timestamp":"2022-02-15T18:47:10.821727Z","level":"TRACE","fields":{"message":"yak shaved successfully"},"target":"fmt_json::yak_shave","spans":[{"yaks":3,"name":"shaving_yaks"},{"yak":2,"name":"shave"}]}
{"timestamp":"2022-02-15T18:47:10.821773Z","level":"DEBUG","fields":{"yak":2,"shaved":true},"target":"yak_events","spans":[{"yaks":3,"name":"shaving_yaks"}]}
{"timestamp":"2022-02-15T18:47:10.821806Z","level":"TRACE","fields":{"yaks_shaved":2},"target":"fmt_json::yak_shave","spans":[{"yaks":3,"name":"shaving_yaks"}]}
```

--------------------------------

### Layer Usage Examples

Source: https://docs.rs/tracing-subscriber/latest/tracing_subscriber/layer/trait.Layer.html

Examples of using the fmt layer with different configurations and type erasure via boxing.

```APIDOC
## Layer Usage Examples

### Description
Examples of using the `fmt` layer with different configurations and type erasure via boxing.

### Example: Non-compiling code (type mismatch)
```rust
let log_layer = match config {
    LogConfig::File(path) => {
        let file = File::create(path)?;
        tracing_subscriber::fmt::layer()
            .with_thread_ids(true)
            .with_thread_names(true)
            .json()
            .with_span_list(true)
            .with_writer(file)
    },

    LogConfig::Stdout => tracing_subscriber::fmt::layer()
        .pretty()
        .with_writer(io::stdout)
        .and_then(tracing_subscriber::EnvFilter::from_default_env()),

    LogConfig::Stderr => tracing_subscriber::fmt::layer()
        .with_writer(io::stderr)
        .with_filter(LevelFilter::WARN),
};

tracing_subscriber::registry()
    .with(log_layer)
    .init();
```

### Example: Compiling code with boxing
```rust
let log_layer = match config {
    LogConfig::File(path) => {
        let file = File::create(path)?;
        tracing_subscriber::fmt::layer()
            .with_thread_ids(true)
            .with_thread_names(true)
            .json()
            .with_span_list(true)
            .with_writer(file)
            .boxed()
    },

    LogConfig::Stdout => tracing_subscriber::fmt::layer()
        .pretty()
        .with_writer(io::stdout)
        .and_then(tracing_subscriber::EnvFilter::from_default_env())
        .boxed(),

    LogConfig::Stderr => tracing_subscriber::fmt::layer()
        .with_writer(io::stderr)
        .with_filter(LevelFilter::WARN)
        .boxed(),
};

tracing_subscriber::registry()
    .with(log_layer)
    .init();
```

```

--------------------------------

### String::as_str example

Source: https://docs.rs/tracing-subscriber/latest/tracing_subscriber/fmt/struct.FormattedFields.html

Example for the `as_str` method inherited from `String`, showing how to extract a string slice.

```rust
let s = String::from("foo");

assert_eq!("foo", s.as_str());
```

--------------------------------

### Example output of fmt-compact

Source: https://docs.rs/tracing-subscriber/latest/tracing_subscriber/fmt/format/struct.Compact.html

Shows the compact log format output from running `cargo run --example fmt-compact`. The output includes timestamps, levels, span paths, and fields.

```text
**:;** cargo run --example fmt-compact
**    Finished** dev [unoptimized + debuginfo] target(s) in 0.08s
**     Running** `target/debug/examples/fmt-compact`
2022-02-17T19:51:05.809287Z  INFO **fmt_compact**: preparing to shave yaks  _number_of_yaks_=3
2022-02-17T19:51:05.809367Z  INFO **shaving_yaks**: **fmt_compact::yak_shave**: shaving yaks _yaks_=3
2022-02-17T19:51:05.809414Z TRACE **shaving_yaks**:**shave**: **fmt_compact::yak_shave**: hello! I'm gonna shave a yak _excitement_="yay!" _yaks_=3 _yak_=1
2022-02-17T19:51:05.809443Z TRACE **shaving_yaks**:**shave**: **fmt_compact::yak_shave**: yak shaved successfully _yaks_=3 _yak_=1
2022-02-17T19:51:05.809477Z DEBUG **shaving_yaks**: **yak_events**: _yak_=1 _shaved_=true _yaks_=3
2022-02-17T19:51:05.809500Z TRACE **shaving_yaks**: **fmt_compact::yak_shave**: _yaks_shaved_=1 _yaks_=3
2022-02-17T19:51:05.809531Z TRACE **shaving_yaks**:**shave**: **fmt_compact::yak_shave**: hello! I'm gonna shave a yak _excitement_="yay!" _yaks_=3 _yak_=2
2022-02-17T19:51:05.809554Z TRACE **shaving_yaks**:**shave**: **fmt_compact::yak_shave**: yak shaved successfully _yaks_=3 _yak_=2
2022-02-17T19:51:05.809581Z DEBUG **shaving_yaks**: **yak_events**: _yak_=2 _shaved_=true _yaks_=3
2022-02-17T19:51:05.809606Z TRACE **shaving_yaks**: **fmt_compact::yak_shave**: _yaks_shaved_=2 _yaks_=3
2022-02-17T19:51:05.809635Z TRACE **shaving_yaks**:**shave**: **fmt_compact::yak_shave**: hello! I'm gonna shave a yak _excitement_="yay!" _yaks_=3 _yak_=3
2022-02-17T19:51:05.809664Z  WARN **shaving_yaks**:**shave**: **fmt_compact::yak_shave**: could not locate yak _yaks_=3 _yak_=3
2022-02-17T19:51:05.809693Z DEBUG **shaving_yaks**: **yak_events**: _yak_=3 _shaved_=false _yaks_=3
2022-02-17T19:51:05.809717Z ERROR **shaving_yaks**: **fmt_compact::yak_shave**: failed to shave yak _yak_=3 _error_=missing yak _error.sources_=[out of space, out of cash] _yaks_=3
2022-02-17T19:51:05.809743Z TRACE **shaving_yaks**: **fmt_compact::yak_shave**: _yaks_shaved_=2 _yaks_=3
2022-02-17T19:51:05.809768Z  INFO **fmt_compact**: yak shaving completed _all_yaks_shaved_=false

```

--------------------------------

### Example output of custom formatter

Source: https://docs.rs/tracing-subscriber/latest/src/tracing_subscriber/fmt/format/mod.rs.html

Shows the expected output format produced by the custom formatter example. The output includes the log level, target, span name with fields, and event message.

```text
DEBUG yak_shaving::shaver: some-span{field-on-span=foo}: started shaving yak
```

--------------------------------

### trim_start basic usage example

Source: https://docs.rs/tracing-subscriber/latest/tracing_subscriber/fmt/struct.FormattedFields.html

Shows how to use trim_start to remove leading whitespace from a string, including Unicode whitespace. The example asserts that the first character after trimming is 'ע'.

```rust
let s = "  עברית  ";
assert!(Some('ע') == s.trim_start().chars().next());
```

--------------------------------

### Or combinator: example combining And and Or for higher level per target

Source: https://docs.rs/tracing-subscriber/latest/src/tracing_subscriber/filter/layer_filters/combinator.rs.html

Shows how to use `Or` with `And` to enable a higher level for a specific target. The example is marked `ignore` in the source.

```rust
use tracing_subscriber::{
    filter::{filter_fn, LevelFilter, combinator},
    prelude::*,
};

// This filter will enable spans and events with targets beginning with
// `my_crate`:
let my_crate = filter_fn(|meta| {
    meta.target().starts_with("my_crate")
});

// Combine the `my_crate` filter with a `LevelFilter` to produce a filter
// that will enable the `INFO` level and lower for spans and events with
// `my_crate` targets:
let filter = combinator::And::new(my_crate, LevelFilter::INFO);

// If a span or event *doesn't* have a target beginning with
// `my_crate`, enable it if it has the `WARN` level or lower:
// let filter = combinator::Or::new(filter, LevelFilter::WARN);

tracing_subscriber::registry()
    .with(tracing_subscriber::fmt::layer().with_filter(filter))
    .init();
```

--------------------------------

### init()

Source: https://docs.rs/tracing-subscriber/latest/tracing_subscriber/fmt/fn.init.html

Installs a global tracing subscriber that listens for events and filters based on the `RUST_LOG` environment variable. The configuration depends on feature flags; with `tracing-log` it also installs a LogTracer, and with `env-filter` it uses `EnvFilter::from_default_env()`.

```APIDOC
## init()

### Description
Installs a global tracing subscriber that listens for events and filters based on the value of the `RUST_LOG` environment variable. The configuration depends on feature flags: if `tracing-log` is enabled, it also installs a LogTracer; if `env-filter` is enabled, it is shorthand for `tracing_subscriber::fmt().with_env_filter(EnvFilter::from_default_env()).init()`.

### Function Signature
```rust
pub fn init()
```

### Availability
Available on crate features `fmt` and `std` only.

### Panics
Panics if the initialization was unsuccessful, likely because a global subscriber was already installed by another call to `try_init`.

```

--------------------------------

### Or combinator: example combining LevelFilter and filter_fn

Source: https://docs.rs/tracing-subscriber/latest/src/tracing_subscriber/filter/layer_filters/combinator.rs.html

Shows how to combine a `LevelFilter` and a `filter_fn` with `Or` to enable events at INFO or lower, or with a target starting with `interesting_target`. The example is marked `ignore` in the source.

```rust
use tracing_subscriber::{
    filter::{filter_fn, LevelFilter, combinator::Or},
    prelude::*,
};

// Enables spans and events with targets starting with `interesting_target`:
let target_filter = filter_fn(|meta| {
    meta.target().starts_with("interesting_target")
});

// Enables spans and events with levels `INFO` and below:
let level_filter = LevelFilter::INFO;

// Combine the two filters together so that a span or event is enabled
// if it is at INFO or lower, or if it has a target starting with
// `interesting_target`.
let filter = Or::new(level_filter, target_filter);

tracing_subscriber::registry()
    .with(tracing_subscriber::fmt::layer().with_filter(filter))
    .init();

// This event will *not* be enabled:
tracing::debug!("an uninteresting event");

// This event *will* be enabled:
tracing::info!("an uninteresting INFO event");

// This event *will* be enabled:
tracing::info!(target: "interesting_target", "a very interesting event");

// This event *will* be enabled:
tracing::debug!(target: "interesting_target", "interesting debug event...");
```

--------------------------------

### SubscriberBuilder::init

Source: https://docs.rs/tracing-subscriber/latest/tracing_subscriber/fmt/struct.SubscriberBuilder.html

Installs this Subscriber as the global default. Panics if initialization fails.

```APIDOC
## SubscriberBuilder::init

### Description
Installs this Subscriber as the global default. If the `tracing-log` feature is enabled, this will also install the LogTracer to convert `Log` records into `tracing` `Event`s.

### Method
init

### Signature
pub fn init(self)

### Parameters
None

### Returns
None

### Panics
Panics if the initialization was unsuccessful, likely because a global subscriber was already installed by another call to `try_init`.

```

--------------------------------

### trim_start directionality example

Source: https://docs.rs/tracing-subscriber/latest/tracing_subscriber/fmt/struct.FormattedFields.html

Shows that trim_start removes leading whitespace from the start of the byte string, which is the left side for left-to-right languages.

```rust
let s = "  English  ";
assert!(Some('E') == s.trim_start().chars().next());
```

--------------------------------

### word_to_titlecase: no word segmentation

Source: https://docs.rs/tracing-subscriber/latest/tracing_subscriber/fmt/struct.FormattedFields.html

No word segmentation is performed, so only the first cased letter in the whole string gets uppercased. This example shows that only the first word is capitalized.

```rust
#![feature(titlecase)]
let blazingly_fast = "ferris and I";

assert_eq!("Ferris and i", blazingly_fast.word_to_titlecase());
```

--------------------------------

### FilterFn::with_max_level_hint example: filter by target prefix and level

Source: https://docs.rs/tracing-subscriber/latest/src/tracing_subscriber/filter/filter_fn.rs.html

Shows how to use `filter_fn` with `with_max_level_hint` to set the maximum level hint. The filter enables spans or events with targets starting with `my_crate` and levels at or below `INFO`. The hint is set to `LevelFilter::INFO`.

```rust
use tracing_subscriber::{
    layer::{Layer, SubscriberExt},
    filter::{filter_fn, LevelFilter},
    util::SubscriberInitExt,
};
use tracing_core::Level;

let my_filter = filter_fn(|metadata| {
    // Only enable spans or events with targets starting with `my_crate`
    // and levels at or below `INFO`.
    metadata.level() <= &Level::INFO && metadata.target().starts_with("my_crate")
})
    // Since the filter closure will only enable the `INFO` level and
    // below, set the max level hint
    .with_max_level_hint(LevelFilter::INFO);

let my_layer = tracing_subscriber::fmt::layer();

tracing_subscriber::registry()
    .with(my_layer.with_filter(my_filter))
    .init();
```

--------------------------------

### pub fn try_init() -> Result<(), ...>

Source: https://docs.rs/tracing-subscriber/latest/src/tracing_subscriber/fmt/mod.rs.html

Attempts to install a global tracing subscriber that listens for events and filters based on the RUST_LOG environment variable. Returns an error if initialization fails, such as when a global subscriber is already installed.

```APIDOC
## pub fn try_init() -> Result<(), ...>

### Description
Attempts to install a global tracing subscriber that listens for events and filters based on the value of the `RUST_LOG` environment variable. The configuration depends on enabled feature flags. If the `tracing-log` feature is enabled, it also installs the LogTracer to convert `Log` records into `tracing` `Event`s. If the `env-filter` feature is enabled, this is shorthand for `tracing_subscriber::fmt().with_env_filter(EnvFilter::from_default_env()).try_init()`.

### Method
Function call

### Signature
```rust
pub fn try_init() -> Result<(), ...>
```

### Parameters
None

### Return Value
- `Ok(())` on success.
- `Err(e)` if initialization fails, e.g., because a global subscriber is already installed.

### Example
```rust
match tracing_subscriber::fmt::try_init() {
    Ok(()) => {}
    Err(e) => eprintln!("Failed to initialize subscriber: {}", e),
}
```
```

--------------------------------

### len() example

Source: https://docs.rs/tracing-subscriber/latest/tracing_subscriber/fmt/struct.FormattedFields.html

Shows how to use the `len` method from `Deref<Target = str>` to get the byte length of a string. Note that the length is in bytes, not characters or graphemes, as demonstrated by the difference between `"ƒoo".len()` and `"ƒoo".chars().count()`.

```rust
let len = "foo".len();
assert_eq!(3, len);

assert_eq!("ƒoo".len(), 4); // fancy f!
assert_eq!("ƒoo".chars().count(), 3);
```

--------------------------------

### Combine filters with `or` to enable events at INFO or lower or with a target prefix

Source: https://docs.rs/tracing-subscriber/latest/src/tracing_subscriber/filter/layer_filters/mod.rs.html

Shows how to use `FilterExt::or` to combine a target-based filter with a `LevelFilter::INFO` so that events are enabled if they are at INFO or lower, or if their target starts with `interesting_target`. The example initializes a tracing subscriber with the combined filter and demonstrates which events are enabled.

```rust
/// // Enables spans and events with targets starting with `interesting_target`:
/// let target_filter = filter_fn(|meta| {
///     meta.target().starts_with("interesting_target")
/// });
///
/// // Enables spans and events with levels `INFO` and below:
/// let level_filter = LevelFilter::INFO;
///
/// // Combine the two filters together so that a span or event is enabled
/// // if it is at INFO or lower, or if it has a target starting with
/// // `interesting_target`.
/// let filter = level_filter.or(target_filter);
///
/// tracing_subscriber::registry()
///     .with(tracing_subscriber::fmt::layer().with_filter(filter))
///     .init();
///
/// // This event will *not* be enabled:
/// tracing::debug!("an uninteresting event");
///
/// // This event *will* be enabled:
/// tracing::info!("an uninteresting INFO event");
///
/// // This event *will* be enabled:
/// tracing::info!(target: "interesting_target", "a very interesting event");
///
/// // This event *will* be enabled:
/// tracing::debug!(target: "interesting_target", "interesting debug event...");
/// ```
```

--------------------------------

### Configure subscriber with layers and filters

Source: https://docs.rs/tracing-subscriber/latest/tracing_subscriber/layer/index.html

Shows how to build a subscriber with multiple layers and filters using tracing_subscriber::registry().with().init(). The example adds a layer with a DEBUG filter and another layer.

```rust
tracing_subscriber::registry()
    // Add `layer_c` with a `DEBUG` filter.
    .with(layer_c.with_filter(LevelFilter::DEBUG))
    .with(info_layers)
    .init();
```

--------------------------------

### Create a Registry with multiple Layers

Source: https://docs.rs/tracing-subscriber/latest/tracing_subscriber/registry/index.html

Shows how to create a `Registry` and add multiple `Layer`s using the `with` method. Requires the `registry` and `std` features.

```rust
use tracing_subscriber::{registry::Registry, Layer, prelude::*};

let subscriber = Registry::default()
    .with(FooLayer::new())
    .with(BarLayer::new());
```

--------------------------------

### Initialize default subscriber with tracing_subscriber::fmt().init()

Source: https://docs.rs/tracing-subscriber/latest/src/tracing_subscriber/fmt/mod.rs.html

Shorthand for creating a default formatting subscriber and setting it as the global default. Use this when you want the simplest setup with default configuration.

```rust
tracing_subscriber::fmt().init();
```

--------------------------------

### split: Separators at start or end

Source: https://docs.rs/tracing-subscriber/latest/tracing_subscriber/fmt/struct.FormattedFields.html

Shows that separators at the start or end of a string are neighbored by empty strings.

```rust
let d: Vec<_> = "010".split("0").collect();
assert_eq!(d, &["", "1", ""]);
```

--------------------------------

### SubscriberBuilder::try_init

Source: https://docs.rs/tracing-subscriber/latest/tracing_subscriber/fmt/struct.SubscriberBuilder.html

Installs this Subscriber as the global default if one is not already set. Returns an error if initialization fails.

```APIDOC
## SubscriberBuilder::try_init

### Description
Installs this Subscriber as the global default if one is not already set. If the `tracing-log` feature is enabled, this will also install the LogTracer to convert `Log` records into `tracing` `Event`s.

### Method
try_init

### Signature
pub fn try_init(self) -> Result<(), Box<dyn Error + Send + Sync + 'static>>

### Parameters
None

### Returns
- **Result<(), Box<dyn Error + Send + Sync + 'static>>** - Ok if initialization succeeded, Err if a global subscriber was already installed.

### Errors
Returns an Error if the initialization was unsuccessful, likely because a global subscriber was already installed by another call to `try_init`.

```

--------------------------------

### Configure formatting settings with with_target, with_timer, with_level

Source: https://docs.rs/tracing-subscriber/latest/src/tracing_subscriber/fmt/mod.rs.html

Configures the subscriber to disable target, use uptime timer, and enable level, then sets it as the default. Demonstrates chaining builder methods.

```rust
tracing_subscriber::fmt()
    // Configure formatting settings.
    .with_target(false)
    .with_timer(tracing_subscriber::fmt::time::uptime())
    .with_level(true)
    // Set the subscriber as the default.
    .init();
```

--------------------------------

### String::is_empty example

Source: https://docs.rs/tracing-subscriber/latest/tracing_subscriber/fmt/struct.FormattedFields.html

Example for the `is_empty` method inherited from `String`, showing how to check if a string has zero length.

```rust
let mut v = String::new();
assert!(v.is_empty());

v.push('a');
assert!(!v.is_empty());
```

--------------------------------

### split_at example

Source: https://docs.rs/tracing-subscriber/latest/tracing_subscriber/fmt/struct.FormattedFields.html

Shows how to divide a string slice into two parts at a byte offset. Panics if the offset is not on a UTF-8 boundary or past the end.

```rust
let s = "Per Martin-Löf";

let (first, last) = s.split_at(3);

assert_eq!("Per", first);
assert_eq!(" Martin-Löf", last);
```

--------------------------------

### String::len example

Source: https://docs.rs/tracing-subscriber/latest/tracing_subscriber/fmt/struct.FormattedFields.html

Example for the `len` method inherited from `String`, showing that length is in bytes, not characters or graphemes.

```rust
let a = String::from("foo");
assert_eq!(a.len(), 3);

let fancy_f = String::from("ƒoo");
assert_eq!(fancy_f.len(), 4);
assert_eq!(fancy_f.chars().count(), 3);
```

--------------------------------

### matches example

Source: https://docs.rs/tracing-subscriber/latest/tracing_subscriber/fmt/struct.FormattedFields.html

Returns an iterator over disjoint matches of a pattern. The example collects all occurrences of "abc" in the string.

```rust
let v: Vec<&str> = "abcXXXabcYYYabc".matches("abc").collect();
assert_eq!(v, ["abc", "abc", "abc"]);
```
Tokens:
Raw