/rust/registry/src/index.crates.io-6f17d22bba15001f/tracing-0.1.41/src/field.rs

Source (jump to first uncovered line)
//! `Span` and `Event` key-value data.
//!
//! Spans and events may be annotated with key-value data, referred to as _fields_.
//! These fields consist of a mapping from a key (corresponding to
//! a `&str` but represented internally as an array index) to a [`Value`].
//!
//! # `Value`s and `Subscriber`s
//!
//! `Subscriber`s consume `Value`s as fields attached to [span]s or [`Event`]s.
//! The set of field keys on a given span or event is defined on its [`Metadata`].
//! When a span is created, it provides [`Attributes`] to the `Subscriber`'s
//! [`new_span`] method, containing any fields whose values were provided when
//! the span was created; and may call the `Subscriber`'s [`record`] method
//! with additional [`Record`]s if values are added for more of its fields.
//! Similarly, the [`Event`] type passed to the subscriber's [`event`] method
//! will contain any fields attached to each event.
//!
//! `tracing` represents values as either one of a set of Rust primitives
//! (`i64`, `u64`, `f64`, `bool`, and `&str`) or using a `fmt::Display` or
//! `fmt::Debug` implementation. `Subscriber`s are provided these primitive
//! value types as `dyn Value` trait objects.
//!
//! These trait objects can be formatted using `fmt::Debug`, but may also be
//! recorded as typed data by calling the [`Value::record`] method on these
//! trait objects with a _visitor_ implementing the [`Visit`] trait. This trait
//! represents the behavior used to record values of various types. For example,
//! an implementation of `Visit` might record integers by incrementing counters
//! for their field names rather than printing them.
//!
//!
//! # Using `valuable`
//!
//! `tracing`'s [`Value`] trait is intentionally minimalist: it supports only a small
//! number of Rust primitives as typed values, and only permits recording
//! user-defined types with their [`fmt::Debug`] or [`fmt::Display`]
//! implementations. However, there are some cases where it may be useful to record
//! nested values (such as arrays, `Vec`s, or `HashMap`s containing values), or
//! user-defined `struct` and `enum` types without having to format them as
//! unstructured text.
//!
//! To address `Value`'s limitations, `tracing` offers experimental support for
//! the [`valuable`] crate, which provides object-safe inspection of structured
//! values. User-defined types can implement the [`valuable::Valuable`] trait,
//! and be recorded as a `tracing` field by calling their [`as_value`] method.
//! If the [`Subscriber`] also supports the `valuable` crate, it can
//! then visit those types fields as structured values using `valuable`.
//!
//! <pre class="ignore" style="white-space:normal;font:inherit;">
//!     <strong>Note</strong>: <code>valuable</code> support is an
//!     <a href = "../index.html#unstable-features">unstable feature</a>. See
//!     the documentation on unstable features for details on how to enable it.
//! </pre>
//!
//! For example:
//! ```ignore
//! // Derive `Valuable` for our types:
//! use valuable::Valuable;
//!
//! #[derive(Clone, Debug, Valuable)]
//! struct User {
//!     name: String,
//!     age: u32,
//!     address: Address,
//! }
//!
//! #[derive(Clone, Debug, Valuable)]
//! struct Address {
//!     country: String,
//!     city: String,
//!     street: String,
//! }
//!
//! let user = User {
//!     name: "Arwen Undomiel".to_string(),
//!     age: 3000,
//!     address: Address {
//!         country: "Middle Earth".to_string(),
//!         city: "Rivendell".to_string(),
//!         street: "leafy lane".to_string(),
//!     },
//! };
//!
//! // Recording `user` as a `valuable::Value` will allow the `tracing` subscriber
//! // to traverse its fields as a nested, typed structure:
//! tracing::info!(current_user = user.as_value());
//! ```
//!
//! Alternatively, the [`valuable()`] function may be used to convert a type
//! implementing [`Valuable`] into a `tracing` field value.
//!
//! When the `valuable` feature is enabled, the [`Visit`] trait will include an
//! optional [`record_value`] method. `Visit` implementations that wish to
//! record `valuable` values can implement this method with custom behavior.
//! If a visitor does not implement `record_value`, the [`valuable::Value`] will
//! be forwarded to the visitor's [`record_debug`] method.
//!
//! [`fmt::Debug`]: std::fmt::Debug
//! [`fmt::Display`]: std::fmt::Debug
//! [`valuable`]: https://crates.io/crates/valuable
//! [`valuable::Valuable`]: https://docs.rs/valuable/latest/valuable/trait.Valuable.html
//! [`as_value`]: https://docs.rs/valuable/latest/valuable/trait.Valuable.html#tymethod.as_value
//! [`valuable::Value`]: https://docs.rs/valuable/latest/valuable/enum.Value.html
//! [`Subscriber`]: crate::Subscriber
//! [`record_value`]: Visit::record_value
//! [`record_debug`]: Visit::record_debug
//! [span]: mod@crate::span
//! [`Event`]: crate::event::Event
//! [`Metadata`]: crate::Metadata
//! [`Attributes`]: crate::span::Attributes
//! [`Record`]: crate::span::Record
//! [`new_span`]: crate::Subscriber::new_span
//! [`record`]: crate::Subscriber::record
//! [`event`]: crate::Subscriber::event
pub use tracing_core::field::*;

use crate::Metadata;

/// Trait implemented to allow a type to be used as a field key.
///
/// <pre class="ignore" style="white-space:normal;font:inherit;">
/// <strong>Note</strong>: Although this is implemented for both the
/// <a href="./struct.Field.html"><code>Field</code></a> type <em>and</em> any
/// type that can be borrowed as an <code>&str</code>, only <code>Field</code>
/// allows <em>O</em>(1) access.
/// Indexing a field with a string results in an iterative search that performs
/// string comparisons. Thus, if possible, once the key for a field is known, it
/// should be used whenever possible.
/// </pre>
pub trait AsField: crate::sealed::Sealed {
    /// Attempts to convert `&self` into a `Field` with the specified `metadata`.
    ///
    /// If `metadata` defines this field, then the field is returned. Otherwise,
    /// this returns `None`.
    fn as_field(&self, metadata: &Metadata<'_>) -> Option<Field>;
}

// ===== impl AsField =====

impl AsField for Field {
    #[inline]
    fn as_field(&self, metadata: &Metadata<'_>) -> Option<Field> {
        if self.callsite() == metadata.callsite() {
            Some(self.clone())
        } else {
            None
        }
    }
}

impl<'a> AsField for &'a Field {
    #[inline]
    fn as_field(&self, metadata: &Metadata<'_>) -> Option<Field> {
        if self.callsite() == metadata.callsite() {
            Some((*self).clone())
        } else {
            None
        }
    }
}

impl AsField for str {
    #[inline]
    fn as_field(&self, metadata: &Metadata<'_>) -> Option<Field> {
        metadata.fields().field(&self)
    }
}

impl crate::sealed::Sealed for Field {}
impl<'a> crate::sealed::Sealed for &'a Field {}
impl crate::sealed::Sealed for str {}

Coverage Report

Created: 2024-12-17 06:15

Line	Count	Source (jump to first uncovered line)
1		//! `Span` and `Event` key-value data.
2		//!
3		//! Spans and events may be annotated with key-value data, referred to as _fields_.
4		//! These fields consist of a mapping from a key (corresponding to
5		//! a `&str` but represented internally as an array index) to a [`Value`].
6		//!
7		//! # `Value`s and `Subscriber`s
8		//!
9		//! `Subscriber`s consume `Value`s as fields attached to [span]s or [`Event`]s.
10		//! The set of field keys on a given span or event is defined on its [`Metadata`].
11		//! When a span is created, it provides [`Attributes`] to the `Subscriber`'s
12		//! [`new_span`] method, containing any fields whose values were provided when
13		//! the span was created; and may call the `Subscriber`'s [`record`] method
14		//! with additional [`Record`]s if values are added for more of its fields.
15		//! Similarly, the [`Event`] type passed to the subscriber's [`event`] method
16		//! will contain any fields attached to each event.
17		//!
18		//! `tracing` represents values as either one of a set of Rust primitives
19		//! (`i64`, `u64`, `f64`, `bool`, and `&str`) or using a `fmt::Display` or
20		//! `fmt::Debug` implementation. `Subscriber`s are provided these primitive
21		//! value types as `dyn Value` trait objects.
22		//!
23		//! These trait objects can be formatted using `fmt::Debug`, but may also be
24		//! recorded as typed data by calling the [`Value::record`] method on these
25		//! trait objects with a _visitor_ implementing the [`Visit`] trait. This trait
26		//! represents the behavior used to record values of various types. For example,
27		//! an implementation of `Visit` might record integers by incrementing counters
28		//! for their field names rather than printing them.
29		//!
30		//!
31		//! # Using `valuable`
32		//!
33		//! `tracing`'s [`Value`] trait is intentionally minimalist: it supports only a small
34		//! number of Rust primitives as typed values, and only permits recording
35		//! user-defined types with their [`fmt::Debug`] or [`fmt::Display`]
36		//! implementations. However, there are some cases where it may be useful to record
37		//! nested values (such as arrays, `Vec`s, or `HashMap`s containing values), or
38		//! user-defined `struct` and `enum` types without having to format them as
39		//! unstructured text.
40		//!
41		//! To address `Value`'s limitations, `tracing` offers experimental support for
42		//! the [`valuable`] crate, which provides object-safe inspection of structured
43		//! values. User-defined types can implement the [`valuable::Valuable`] trait,
44		//! and be recorded as a `tracing` field by calling their [`as_value`] method.
45		//! If the [`Subscriber`] also supports the `valuable` crate, it can
46		//! then visit those types fields as structured values using `valuable`.
47		//!
48		//! <pre class="ignore" style="white-space:normal;font:inherit;">
49		//! <strong>Note</strong>: <code>valuable</code> support is an
50		//! <a href = "../index.html#unstable-features">unstable feature</a>. See
51		//! the documentation on unstable features for details on how to enable it.
52		//! </pre>
53		//!
54		//! For example:
55		//! ```ignore
56		//! // Derive `Valuable` for our types:
57		//! use valuable::Valuable;
58		//!
59		//! #[derive(Clone, Debug, Valuable)]
60		//! struct User {
61		//! name: String,
62		//! age: u32,
63		//! address: Address,
64		//! }
65		//!
66		//! #[derive(Clone, Debug, Valuable)]
67		//! struct Address {
68		//! country: String,
69		//! city: String,
70		//! street: String,
71		//! }
72		//!
73		//! let user = User {
74		//! name: "Arwen Undomiel".to_string(),
75		//! age: 3000,
76		//! address: Address {
77		//! country: "Middle Earth".to_string(),
78		//! city: "Rivendell".to_string(),
79		//! street: "leafy lane".to_string(),
80		//! },
81		//! };
82		//!
83		//! // Recording `user` as a `valuable::Value` will allow the `tracing` subscriber
84		//! // to traverse its fields as a nested, typed structure:
85		//! tracing::info!(current_user = user.as_value());
86		//! ```
87		//!
88		//! Alternatively, the [`valuable()`] function may be used to convert a type
89		//! implementing [`Valuable`] into a `tracing` field value.
90		//!
91		//! When the `valuable` feature is enabled, the [`Visit`] trait will include an
92		//! optional [`record_value`] method. `Visit` implementations that wish to
93		//! record `valuable` values can implement this method with custom behavior.
94		//! If a visitor does not implement `record_value`, the [`valuable::Value`] will
95		//! be forwarded to the visitor's [`record_debug`] method.
96		//!
97		//! [`fmt::Debug`]: std::fmt::Debug
98		//! [`fmt::Display`]: std::fmt::Debug
99		//! [`valuable`]: https://crates.io/crates/valuable
100		//! [`valuable::Valuable`]: https://docs.rs/valuable/latest/valuable/trait.Valuable.html
101		//! [`as_value`]: https://docs.rs/valuable/latest/valuable/trait.Valuable.html#tymethod.as_value
102		//! [`valuable::Value`]: https://docs.rs/valuable/latest/valuable/enum.Value.html
103		//! [`Subscriber`]: crate::Subscriber
104		//! [`record_value`]: Visit::record_value
105		//! [`record_debug`]: Visit::record_debug
106		//! [span]: mod@crate::span
107		//! [`Event`]: crate::event::Event
108		//! [`Metadata`]: crate::Metadata
109		//! [`Attributes`]: crate::span::Attributes
110		//! [`Record`]: crate::span::Record
111		//! [`new_span`]: crate::Subscriber::new_span
112		//! [`record`]: crate::Subscriber::record
113		//! [`event`]: crate::Subscriber::event
114		pub use tracing_core::field::*;
115
116		use crate::Metadata;
117
118		/// Trait implemented to allow a type to be used as a field key.
119		///
120		/// <pre class="ignore" style="white-space:normal;font:inherit;">
121		/// <strong>Note</strong>: Although this is implemented for both the
122		/// <a href="./struct.Field.html"><code>Field</code></a> type <em>and</em> any
123		/// type that can be borrowed as an <code>&str</code>, only <code>Field</code>
124		/// allows <em>O</em>(1) access.
125		/// Indexing a field with a string results in an iterative search that performs
126		/// string comparisons. Thus, if possible, once the key for a field is known, it
127		/// should be used whenever possible.
128		/// </pre>
129		pub trait AsField: crate::sealed::Sealed {
130		/// Attempts to convert `&self` into a `Field` with the specified `metadata`.
131		///
132		/// If `metadata` defines this field, then the field is returned. Otherwise,
133		/// this returns `None`.
134		fn as_field(&self, metadata: &Metadata<'_>) -> Option<Field>;
135		}
136
137		// ===== impl AsField =====
138
139		impl AsField for Field {
140		#[inline]
141	0	fn as_field(&self, metadata: &Metadata<'_>) -> Option<Field> {
142	0	if self.callsite() == metadata.callsite() {
143	0	Some(self.clone())
144		} else {
145	0	None
146		}
147	0	} Unexecuted instantiation: <tracing_core::field::Field as tracing::field::AsField>::as_field Unexecuted instantiation: <tracing_core::field::Field as tracing::field::AsField>::as_field Unexecuted instantiation: <tracing_core::field::Field as tracing::field::AsField>::as_field Unexecuted instantiation: <tracing_core::field::Field as tracing::field::AsField>::as_field
148		}
149
150		impl<'a> AsField for &'a Field {
151		#[inline]
152	0	fn as_field(&self, metadata: &Metadata<'_>) -> Option<Field> {
153	0	if self.callsite() == metadata.callsite() {
154	0	Some((*self).clone())
155		} else {
156	0	None
157		}
158	0	} Unexecuted instantiation: <&tracing_core::field::Field as tracing::field::AsField>::as_field Unexecuted instantiation: <&tracing_core::field::Field as tracing::field::AsField>::as_field Unexecuted instantiation: <&tracing_core::field::Field as tracing::field::AsField>::as_field Unexecuted instantiation: <&tracing_core::field::Field as tracing::field::AsField>::as_field
159		}
160
161		impl AsField for str {
162		#[inline]
163	0	fn as_field(&self, metadata: &Metadata<'_>) -> Option<Field> {
164	0	metadata.fields().field(&self)
165	0	} Unexecuted instantiation: <str as tracing::field::AsField>::as_field Unexecuted instantiation: <str as tracing::field::AsField>::as_field Unexecuted instantiation: <str as tracing::field::AsField>::as_field Unexecuted instantiation: <str as tracing::field::AsField>::as_field Unexecuted instantiation: <str as tracing::field::AsField>::as_field
166		}
167
168		impl crate::sealed::Sealed for Field {}
169		impl<'a> crate::sealed::Sealed for &'a Field {}
170		impl crate::sealed::Sealed for str {}