@@ -33,15 +33,55 @@ pub use pretty::*;
3333
3434/// A type that can format a tracing [`Event`] to a [`Writer`].
3535///
36- /// `FormatEvent` is primarily used in the context of [`fmt::Subscriber`] or [`fmt::Layer`]. Each time an event is
37- /// dispatched to [`fmt::Subscriber`] or [`fmt::Layer`], the subscriber or layer forwards it to
38- /// its associated `FormatEvent` to emit a log message.
36+ /// `FormatEvent` is primarily used in the context of [`fmt::Subscriber`] or
37+ /// [`fmt::Layer`]. Each time an event is dispatched to [`fmt::Subscriber`] or
38+ /// [`fmt::Layer`], the subscriber or layer
39+ /// forwards it to its associated `FormatEvent` to emit a log message.
3940///
4041/// This trait is already implemented for function pointers with the same
4142/// signature as `format_event`.
4243///
44+ /// # Arguments
45+ ///
46+ /// The following arguments are passed to `FormatEvent::format_event`:
47+ ///
48+ /// * A [`FmtContext`]. This is an extension of the [`layer::Context`] type,
49+ /// which can be used for accessing stored information such as the current
50+ /// span context an event occurred in.
51+ ///
52+ /// In addition, [`FmtContext`] exposes access to the [`FormatFields`]
53+ /// implementation that the subscriber was configured to use via the
54+ /// [`FmtContext::field_format`] method. This can be used when the
55+ /// [`FormatEvent`] implementation needs to format the event's fields.
56+ ///
57+ /// For convenience, [`FmtContext`] also [implements `FormatFields`],
58+ /// forwarding to the configured [`FormatFields`] type.
59+ ///
60+ /// * A [`Writer`] to which the formatted representation of the event is
61+ /// written. This type implements the [`std::fmt::Write`] trait, and therefore
62+ /// can be used with the [`std::write!`] and [`std::writeln!`] macros, as well
63+ /// as calling [`std::fmt::Write`] methods directly.
64+ ///
65+ /// The [`Writer`] type also implements additional methods that provide
66+ /// information about how the event should be formatted. The
67+ /// [`Writer::has_ansi_escapes`] method indicates whether [ANSI terminal
68+ /// escape codes] are supported by the underlying I/O writer that the event
69+ /// will be written to. If this returns `true`, the formatter is permitted to
70+ /// use ANSI escape codes to add colors and other text formatting to its
71+ /// output. If it returns `false`, the event will be written to an output that
72+ /// does not support ANSI escape codes (such as a log file), and they should
73+ /// not be emitted.
74+ ///
75+ /// Crates like [`ansi_term`] and [`owo-colors`] can be used to add ANSI
76+ /// escape codes to formatted output.
77+ ///
78+ /// * The actual [`Event`] to be formatted.
79+ ///
4380/// # Examples
4481///
82+ /// This example re-implements a simiplified version of this crate's [default
83+ /// formatter]:
84+ ///
4585/// ```rust
4686/// use std::fmt;
4787/// use tracing_core::{Subscriber, Event};
@@ -65,31 +105,25 @@ pub use pretty::*;
65105/// mut writer: format::Writer<'_>,
66106/// event: &Event<'_>,
67107/// ) -> fmt::Result {
68- /// // Write level and target
69- /// let level = *event.metadata().level();
70- /// let target = event.metadata().target();
71- /// write!(
72- /// writer,
73- /// "{} {}: ",
74- /// level,
75- /// target,
76- /// )?;
108+ /// // Format values from the event's's metadata:
109+ /// let metadata = event.metadata();
110+ /// write!(&mut writer, "{} {}: ", metadata.level(), metadata.target())?;
77111///
78- /// // Write spans and fields of each span
112+ /// // Format all the spans in the event's span context.
79113/// ctx.visit_spans(|span| {
80114/// write!(writer, "{}", span.name())?;
81115///
82- /// let ext = span.extensions();
83- ///
84- /// // `FormattedFields` is a a formatted representation of the span's
116+ /// // `FormattedFields` is a formatted representation of the span's
85117/// // fields, which is stored in its extensions by the `fmt` layer's
86118/// // `new_span` method. The fields will have been formatted
87119/// // by the same field formatter that's provided to the event
88120/// // formatter in the `FmtContext`.
121+ /// let ext = span.extensions();
89122/// let fields = &ext
90123/// .get::<FormattedFields<N>>()
91124/// .expect("will never be `None`");
92125///
126+ /// // Skip formatting the fields if the span had no fields.
93127/// if !fields.is_empty() {
94128/// write!(writer, "{{{}}}", fields)?;
95129/// }
@@ -104,6 +138,13 @@ pub use pretty::*;
104138/// writeln!(writer)
105139/// }
106140/// }
141+ ///
142+ /// let _subscriber = tracing_subscriber::fmt()
143+ /// .event_format(MyFormatter)
144+ /// .init();
145+ ///
146+ /// let _span = tracing::info_span!("my_span", answer = 42).entered();
147+ /// tracing::info!(question = "life, the universe, and everything", "hello world");
107148/// ```
108149///
109150/// This formatter will print events like this:
@@ -114,7 +155,13 @@ pub use pretty::*;
114155///
115156/// [`fmt::Layer`]: super::Layer
116157/// [`fmt::Subscriber`]: super::Subscriber
117- /// [`Event`]: tracing::Event
158+ /// [`layer::Context`]: crate::layer::Context
159+ /// [implements `FormatFields`]: super::FmtContext#impl-FormatFields<'writer>
160+ /// [ANSI terminal escape codes]: https://en.wikipedia.org/wiki/ANSI_escape_code
161+ /// [`Writer::has_ansi_escapes`]: Writer::has_ansi_escapes
162+ /// [`ansi_term`]: https://crates.io/crates/ansi_term
163+ /// [`owo-colors`]: https://crates.io/crates/owo-colors
164+ /// [default formatter]: Full
118165pub trait FormatEvent < S , N >
119166where
120167 S : Subscriber + for < ' a > LookupSpan < ' a > ,
@@ -369,10 +416,12 @@ impl<'writer> Writer<'writer> {
369416 self . writer . write_fmt ( args)
370417 }
371418
372- /// Returns `true` if ANSI escape codes may be used to add colors
419+ /// Returns `true` if [ ANSI escape codes] may be used to add colors
373420/// and other formatting when writing to this `Writer`.
374421///
375422/// If this returns `false`, formatters should not emit ANSI escape codes.
423+ ///
424+ /// [ANSI escape codes]: https://en.wikipedia.org/wiki/ANSI_escape_code
376425pub fn has_ansi_escapes ( & self ) -> bool {
377426 self . is_ansi
378427 }
0 commit comments