Struct Layer

pub struct Layer<S: for<'lookup> LookupSpan<'lookup> = Registry, W = fn() -> Stdout> { /* private fields */ }

A Layer that logs JSON formatted representations of tracing events.

This is just a wrapper around JsonLayer which exists for compatibility with tracing_subscriber.

Examples

Constructing a layer with the default configuration:

use tracing_subscriber::Registry;
use tracing_subscriber::layer::SubscriberExt as _;
use json_subscriber::fmt;

let subscriber = Registry::default()
    .with(fmt::Layer::default());

tracing::subscriber::set_global_default(subscriber).unwrap();

Overriding the layer’s behavior:

use tracing_subscriber::Registry;
use tracing_subscriber::layer::SubscriberExt as _;
use json_subscriber::fmt;

let fmt_layer = fmt::layer()
   .with_target(false) // don't include event targets when logging
   .with_level(false); // don't include event levels when logging

let subscriber = Registry::default().with(fmt_layer);

Implementations

impl<S, W> Layer<S, W>

where S: Subscriber + for<'lookup> LookupSpan<'lookup>,

pub fn with_writer<W2>(self, make_writer: W2) -> Layer<S, W2>

where W2: for<'writer> MakeWriter<'writer> + 'static,

Sets the MakeWriter that the JsonLayer being built will use to write events.

Examples

Using stderr rather than stdout:

let layer = json_subscriber::fmt::layer()
    .with_writer(std::io::stderr);

pub fn map_writer<W2>(self, f: impl FnOnce(W) -> W2) -> Layer<S, W2>

where W2: for<'writer> MakeWriter<'writer> + 'static,

Updates the MakeWriter by applying a function to the existing MakeWriter.

This sets the MakeWriter that the layer being built will use to write events.

Examples

Redirect output to stderr if level is <= WARN:

use tracing_subscriber::fmt::writer::MakeWriterExt;

let stderr = std::io::stderr.with_max_level(tracing::Level::WARN);
let layer = json_subscriber::fmt::layer()
    .map_writer(move |w| stderr.or_else(w));

pub fn with_test_writer(self) -> Layer<S, TestWriter>

Configures the layer to support libtest’s output capturing when used in unit tests.

See TestWriter for additional details.

Examples

Using TestWriter to let cargo test capture test output:

use tracing_subscriber::fmt::writer::MakeWriterExt;

let layer = json_subscriber::fmt::layer()
    .with_test_writer();

pub fn writer(&self) -> &W

Borrows the writer for this layer.

pub fn writer_mut(&mut self) -> &mut W

Mutably borrows the writer for this layer.

This method is primarily expected to be used with the reload::Handle::modify method.

Examples

let layer = json_subscriber::fmt::layer().with_writer(non_blocking(std::io::stderr()));
let (layer, reload_handle) = reload::Layer::new(layer);

tracing_subscriber::registry().with(layer).init();

info!("This will be logged to stderr");
reload_handle.modify(|subscriber| *subscriber.writer_mut() = non_blocking(std::io::stdout()));
info!("This will be logged to stdout");

pub fn inner_layer_mut(&mut self) -> &mut JsonLayer<S, W>

Mutably borrows the JsonLayer inside of this layer. This can be useful to add more information to the output or to change the output with the reload::Handle::modify method.

Examples

let mut layer = json_subscriber::layer();
let mut inner = layer.inner_layer_mut();

inner.add_static_field(
    "hostname",
    serde_json::json!({
        "hostname": get_hostname(),
    }),
);

pub fn log_internal_errors(self, log_internal_errors: bool) -> Self

Sets whether to write errors from FormatEvent to the writer. Defaults to true.

By default, fmt::JsonLayer will write any FormatEvent-internal errors to the writer. These errors are unlikely and will only occur if there is a bug in the FormatEvent implementation or its dependencies.

If writing to the writer fails, the error message is printed to stderr as a fallback.

pub fn flatten_current_span_on_top_level(self, flatten_span: bool) -> Self

Sets the JSON subscriber being built to flatten the current span’s fields to the top level of the output.

It is the user’s responsibility to make sure that the span field names do not clash with any other fields logged on the span. This should not be used with Self::flatten_span_list_on_top_level as that will log the current span’s fields twice which would make the resulting JSON invalid.

pub fn flatten_span_list_on_top_level(self, flatten_span_list: bool) -> Self

Sets the JSON subscriber being built to flatten all parent spans’ fields to the top level of the output. Values of fields in spans closer to the event will take precedence over spans closer to the root span.

If you’re looking to have all parent spans’ fields flattened but do not need them at the top level, use Self::with_flat_span_list instead.

It is the user’s responsibility to make sure that the span field names do not clash with any other fields logged on the span. This should not be used with Self::flatten_current_span_on_top_level as that will log the current span’s fields twice which would make the resulting JSON invalid.

pub fn flatten_event(self, flatten_event: bool) -> Self

Sets the JSON subscriber being built to flatten event metadata.

pub fn with_current_span(self, display_current_span: bool) -> Self

Sets whether or not the formatter will include the current span in formatted events.

pub fn with_span_list(self, display_span_list: bool) -> Self

Sets whether or not the formatter will include a list (from root to leaf) of all currently entered spans in formatted events.

This overrides any previous calls to with_flat_span_list.

pub fn with_flat_span_list(self, flatten_span_list: bool) -> Self

Sets whether or not the formatter will include an object containing all parent spans’ fields. If multiple ancestor spans recorded the same field, the span closer to the leaf span overrides the values of spans that are closer to the root spans.

This overrides any previous calls to with_span_list.

pub fn with_timer<T: FormatTime + Send + Sync + 'static>(self, timer: T) -> Self

Use the given timer for log message timestamps.

See the time module for the provided timer implementations.

Note that using the "time“” feature flag enables the additional time formatters UtcTime and LocalTime, which use the time crate to provide more sophisticated timestamp formatting options.

pub fn without_time(self) -> Self

Do not emit timestamps with log messages.

pub fn with_target(self, display_target: bool) -> Self

Sets whether or not an event’s target is displayed.

pub fn with_file(self, display_filename: bool) -> Self

Sets whether or not an event’s source code file path is displayed.

pub fn with_line_number(self, display_line_number: bool) -> Self

Sets whether or not an event’s source code line number is displayed.

pub fn with_level(self, display_level: bool) -> Self

Sets whether or not an event’s level is displayed.

pub fn with_thread_names(self, display_thread_name: bool) -> Self

Sets whether or not the name of the current thread is displayed when formatting events.

pub fn with_thread_ids(self, display_thread_id: bool) -> Self

Sets whether or not the thread ID of the current thread is displayed when formatting events.

pub fn with_opentelemetry_ids(self, display_opentelemetry_ids: bool) -> Self

Available on crate features opentelemetry or tracing-opentelemetry-0-28 or tracing-opentelemetry-0-29 or tracing-opentelemetry-0-30 or tracing-opentelemetry-0-31 only.

Sets whether or not OpenTelemetry trace ID and span ID is displayed when formatting events.

Trait Implementations

impl<S: Subscriber + for<'lookup> LookupSpan<'lookup>> Default for Layer<S>

fn default() -> Self

Returns the “default value” for a type.

impl<S, W> Layer<S> for Layer<S, W>

where JsonLayer<S, W>: Subscribe<S>, S: Subscriber + for<'lookup> LookupSpan<'lookup>,

fn on_register_dispatch(&self, subscriber: &Dispatch)

Performs late initialization when installing this layer as a Subscriber.

fn on_layer(&mut self, subscriber: &mut S)

Performs late initialization when attaching a Layer to a Subscriber.

fn register_callsite(&self, metadata: &'static Metadata<'static>) -> Interest

Registers a new callsite with this layer, returning whether or not the layer is interested in being notified about the callsite, similarly to Subscriber::register_callsite.

fn enabled(&self, metadata: &Metadata<'_>, ctx: Context<'_, S>) -> bool

Returns true if this layer is interested in a span or event with the given metadata in the current Context, similarly to Subscriber::enabled.

fn on_new_span(&self, attrs: &Attributes<'_>, id: &Id, ctx: Context<'_, S>)

Notifies this layer that a new span was constructed with the given Attributes and Id.

fn on_record(&self, span: &Id, values: &Record<'_>, ctx: Context<'_, S>)

Notifies this layer that a span with the given Id recorded the given values.

fn on_follows_from(&self, span: &Id, follows: &Id, ctx: Context<'_, S>)

Notifies this layer that a span with the ID span recorded that it follows from the span with the ID follows.

fn event_enabled(&self, event: &Event<'_>, ctx: Context<'_, S>) -> bool

Called before on_event, to determine if on_event should be called.

fn on_event(&self, event: &Event<'_>, ctx: Context<'_, S>)

Notifies this layer that an event has occurred.

fn on_enter(&self, id: &Id, ctx: Context<'_, S>)

Notifies this layer that a span with the given ID was entered.

fn on_exit(&self, id: &Id, ctx: Context<'_, S>)

Notifies this layer that the span with the given ID was exited.

fn on_close(&self, id: Id, ctx: Context<'_, S>)

Notifies this layer that the span with the given ID has been closed.

fn on_id_change(&self, old: &Id, new: &Id, ctx: Context<'_, S>)

Notifies this layer that a span ID has been cloned, and that the subscriber returned a different ID.

fn and_then<L>(self, layer: L) -> Layered<L, Self, S>

where L: Layer<S>, Self: Sized,

Composes this layer around the given Layer, returning a Layered struct implementing Layer.

fn with_subscriber(self, inner: S) -> Layered<Self, S>

where Self: Sized,

Composes this Layer with the given Subscriber, returning a Layered struct that implements Subscriber.

fn with_filter<F>(self, filter: F) -> Filtered<Self, F, S>

where Self: Sized, F: Filter<S>,

Combines self with a Filter, returning a Filtered layer.

fn boxed(self) -> Box<dyn Layer<S> + Send + Sync>

where Self: Sized + Layer<S> + Send + Sync + 'static, S: Subscriber,

Erases the type of this Layer, returning a Boxed dyn Layer trait object.