diff options
| author | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-04-28 14:29:10 +0000 |
|---|---|---|
| committer | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-04-28 14:29:10 +0000 |
| commit | 2aa4a82499d4becd2284cdb482213d541b8804dd (patch) | |
| tree | b80bf8bf13c3766139fbacc530efd0dd9d54394c /third_party/rust/tracing | |
| parent | Initial commit. (diff) | |
| download | firefox-upstream.tar.xz firefox-upstream.zip | |
Adding upstream version 86.0.1.upstream/86.0.1upstream
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to '')
59 files changed, 15512 insertions, 0 deletions
diff --git a/third_party/rust/tracing-core/.cargo-checksum.json b/third_party/rust/tracing-core/.cargo-checksum.json new file mode 100644 index 0000000000..d86c97be07 --- /dev/null +++ b/third_party/rust/tracing-core/.cargo-checksum.json @@ -0,0 +1 @@ +{"files":{"CHANGELOG.md":"c0e17b9a0e4f134b8507ba8f6ac2d4800eb1a4024c42f8888c24525cfbf0c1ae","Cargo.toml":"5d803dae41ee1b5f564ee9321d14bd7f5b25b8b237c9f2e9e9a4a0d6bc24238b","LICENSE":"898b1ae9821e98daf8964c8d6c7f61641f5f5aa78ad500020771c0939ee0dea1","README.md":"cefe3a66d7cdf9d71089d5104a4997a93ed231232f1024799b240bb436721288","src/callsite.rs":"2c0ef84a22d2c93aa6c70220c38f40ac1416de427b0d2d3169541e05eac901bf","src/dispatcher.rs":"386fb35ec3a2ebd37c96b50a52eca8232e8c55756681815963d8050ecbc3a417","src/event.rs":"afac8c061d1c450799fdab8512df6792b64ea11456703a4b3589bc4e696f099e","src/field.rs":"560179f2399d52ed37bda79939ce1b29a60da03baa7068d5613a7ecac5814e50","src/lazy_static/LICENSE":"1e2391052f82d7b0111f512680dcbecf01b06842f5295833e7bd435be2b09a9b","src/lazy_static/core_lazy.rs":"b4c1aaec440177f0de3148fd7b5b60f052890267035966069e9d6a167a72af6a","src/lazy_static/mod.rs":"31abed65708c02b36ec4c72d0788b3fc18c684274ba943dc80fc9f2347f5fb2f","src/lib.rs":"c5ec7961ecb51ad0f30e077edd310d69be09446692c81cf19edf04d03a87e97e","src/metadata.rs":"ef18a9de74a7e8891e33585269d58b2f62613f80d450195cb50c44cde7805d9c","src/parent.rs":"5d5ad733343280a64a1feb6a008e186c39305ec554f14279012b8d7915821471","src/span.rs":"18d9000b35469ea91c56d3e0023e18a982ef625232c617c2827a417793b02c4a","src/spin/LICENSE":"58545fed1565e42d687aecec6897d35c6d37ccb71479a137c0deb2203e125c79","src/spin/mod.rs":"c458ce5e875acb7fbfb279f23254f4924d7c6d6fee419b740800d2e8087d1524","src/spin/mutex.rs":"eaf592b586a5ed73735d6442009b16b0350cb1f71013dafcc95a512c1a49f187","src/spin/once.rs":"c611328c4287adf5c63ae768e2923f34228cad6e019263c98dd33f96a3357edf","src/stdlib.rs":"491c9e37321798c86124c0690f7c5f29054bc444cc51406c36b6fdb106392303","src/subscriber.rs":"66edfcad19821e4d8d92c9ad44b4717c97a89ea5e5172a4c6d6301bdd5a76025","tests/common/mod.rs":"0bbb217baa17df0f96cc1ff57dfa74ccc5a959e7f66b15bb7d25d5f43358a278","tests/dispatch.rs":"c99a9ee042b2a9185d090ffc1a042e1bced0626ce95608c610dd8f7867022f3d","tests/global_dispatch.rs":"cdc05d77e448ee8b50bfb930abafa3f19b4c6f922b7bebc7797fa1dbdaa1d398","tests/macros.rs":"b1603d888b349c8d103794deceec3b1ae4538b8d3eba805f3f561899e8ad0dd2"},"package":"f50de3927f93d202783f4513cda820ab47ef17f624b03c096e86ef00c67e6b5f"}
\ No newline at end of file diff --git a/third_party/rust/tracing-core/CHANGELOG.md b/third_party/rust/tracing-core/CHANGELOG.md new file mode 100644 index 0000000000..4d04e65229 --- /dev/null +++ b/third_party/rust/tracing-core/CHANGELOG.md @@ -0,0 +1,216 @@ +# 0.1.17 (September 28, 2020) + +### Fixed + +- Incorrect inlining of `Event::dispatch` and `Event::child_of`, which could + result in `dispatcher::get_default` being inlined at the callsite ([#994]) + +### Added + +- `Copy` implementations for `Level` and `LevelFilter` ([#992]) + +Thanks to new contributors @jyn514 and @TaKO8Ki for contributing to this +release! + +[#994]: https://github.com/tokio-rs/tracing/pull/994 +[#992]: https://github.com/tokio-rs/tracing/pull/992 + +# 0.1.16 (September 8, 2020) + +### Fixed + +- Added a conversion from `Option<Level>` to `LevelFilter`. This resolves a + previously unreported regression where `Option<Level>` was no longer + a valid LevelFilter. ([#966](https://github.com/tokio-rs/tracing/pull/966)) + +# 0.1.15 (August 22, 2020) + +### Fixed + +- When combining `Interest` from multiple subscribers, if the interests differ, + the current subscriber is now always asked if a callsite should be enabled + (#927) + +## Added + +- Internal API changes to support optimizations in the `tracing` crate (#943) +- **docs**: Multiple fixes and improvements (#913, #941) + +# 0.1.14 (August 10, 2020) + +### Fixed + +- Incorrect calculation of global max level filter which could result in fast + filtering paths not being taken (#908) + +# 0.1.13 (August 4, 2020) + +### Fixed + +- Missing `fmt::Display` impl for `field::DisplayValue` causing a compilation + failure when the "log" feature is enabled (#887) + +Thanks to @d-e-s-o for contributing to this release! + +# 0.1.12 (July 31, 2020) + +### Added + +- `LevelFilter` type and `LevelFilter::current()` for returning the highest level + that any subscriber will enable (#853) +- `Subscriber::max_level_hint` optional trait method, for setting the value + returned by `LevelFilter::current()` (#853) + +### Fixed + +- **docs**: Removed outdated reference to a Tokio API that no longer exists + (#857) + +Thanks to new contributor @dignati for contributing to this release! + +# 0.1.11 (June 8, 2020) + +### Changed + +- Replaced use of `inner_local_macros` with `$crate::` (#729) + +### Added + +- `must_use` warning to guards returned by `dispatcher::set_default` (#686) +- `fmt::Debug` impl to `dyn Value`s (#696) +- Functions to convert between `span::Id` and `NonZeroU64` (#770) +- More obvious warnings in documentation (#769) + +### Fixed + +- Compiler error when `tracing-core/std` feature is enabled but `tracing/std` is + not (#760) +- Clippy warning on vtable address comparison in `callsite::Identifier` (#749) +- Documentation formatting issues (#715, #771) + +Thanks to @bkchr, @majecty, @taiki-e, @nagisa, and @nvzqz for contributing to +this release! + +# 0.1.10 (January 24, 2020) + +### Added + +- `field::Empty` type for declaring empty fields whose values will be recorded + later (#548) +- `field::Value` implementations for `Wrapping` and `NonZero*` numbers (#538) + +### Fixed + +- Broken and unresolvable links in RustDoc (#595) + +Thanks to @oli-cosmian for contributing to this release! + +# 0.1.9 (January 10, 2020) + +### Added + +- API docs now show what feature flags are required to enable each item (#523) + +### Fixed + +- A panic when the current default subscriber subscriber calls + `dispatcher::with_default` as it is being dropped (#522) +- Incorrect documentation for `Subscriber::drop_span` (#524) + +# 0.1.8 (December 20, 2019) + +### Added + +- `Default` impl for `Dispatch` (#411) + +### Fixed + +- Removed duplicate `lazy_static` dependencies (#424) +- Fixed no-std dependencies being enabled even when `std` feature flag is set + (#424) +- Broken link to `Metadata` in `Event` docs (#461) + +# 0.1.7 (October 18, 2019) + +### Added + +- Added `dispatcher::set_default` API which returns a drop guard (#388) + +### Fixed + +- Added missing `Value` impl for `u8` (#392) +- Broken links in docs. + +# 0.1.7 (October 18, 2019) + +### Added + +- Added `dispatcher::set_default` API which returns a drop guard (#388) + +### Fixed + +- Added missing `Value` impl for `u8` (#392) +- Broken links in docs. + +# 0.1.6 (September 12, 2019) + +### Added + +- Internal APIs to support performance optimizations (#326) + +### Fixed + +- Clarified wording in `field::display` documentation (#340) + +# 0.1.6 (August 16, 2019) + +### Added + +- `std::error::Error` as a new primitive `Value` type (#277) +- `Event::new` and `Event::new_child_of` to manually construct `Event`s (#281) + +# 0.1.4 (August 9, 2019) + +### Added + +- Support for `no-std` + `liballoc` (#256) + +### Fixed + +- Broken links in RustDoc (#259) + +# 0.1.3 (August 8, 2019) + +### Added + +- `std::fmt::Display` implementation for `Level` (#194) +- `std::str::FromStr` implementation for `Level` (#195) + +# 0.1.2 (July 10, 2019) + +### Deprecated + +- `Subscriber::drop_span` in favor of new `Subscriber::try_close` (#168) + +### Added + +- `Into<Option<&Id>>`, `Into<Option<Id>>`, and + `Into<Option<&'static Metadata<'static>>>` impls for `span::Current` (#170) +- `Subscriber::try_close` method (#153) +- Improved documentation for `dispatcher` (#171) + +# 0.1.1 (July 6, 2019) + +### Added + +- `Subscriber::current_span` API to return the current span (#148). +- `span::Current` type, representing the `Subscriber`'s view of the current + span (#148). + +### Fixed + +- Typos and broken links in documentation (#123, #124, #128, #154) + +# 0.1.0 (June 27, 2019) + +- Initial release diff --git a/third_party/rust/tracing-core/Cargo.toml b/third_party/rust/tracing-core/Cargo.toml new file mode 100644 index 0000000000..f305004bbf --- /dev/null +++ b/third_party/rust/tracing-core/Cargo.toml @@ -0,0 +1,36 @@ +# THIS FILE IS AUTOMATICALLY GENERATED BY CARGO +# +# When uploading crates to the registry Cargo will automatically +# "normalize" Cargo.toml files for maximal compatibility +# with all versions of Cargo and also rewrite `path` dependencies +# to registry (e.g., crates.io) dependencies +# +# If you believe there's an error in this file please file an +# issue against the rust-lang/cargo repository. If you're +# editing this file be aware that the upstream Cargo.toml +# will likely look very different (and much more reasonable) + +[package] +edition = "2018" +name = "tracing-core" +version = "0.1.17" +authors = ["Tokio Contributors <team@tokio.rs>"] +description = "Core primitives for application-level tracing.\n" +homepage = "https://tokio.rs" +readme = "README.md" +keywords = ["logging", "tracing", "profiling"] +categories = ["development-tools::debugging", "development-tools::profiling", "asynchronous"] +license = "MIT" +repository = "https://github.com/tokio-rs/tracing" +[package.metadata.docs.rs] +all-features = true +rustdoc-args = ["--cfg", "docsrs"] +[dependencies.lazy_static] +version = "1" +optional = true + +[features] +default = ["std"] +std = ["lazy_static"] +[badges.maintenance] +status = "actively-developed" diff --git a/third_party/rust/tracing-core/LICENSE b/third_party/rust/tracing-core/LICENSE new file mode 100644 index 0000000000..cdb28b4b56 --- /dev/null +++ b/third_party/rust/tracing-core/LICENSE @@ -0,0 +1,25 @@ +Copyright (c) 2019 Tokio Contributors + +Permission is hereby granted, free of charge, to any +person obtaining a copy of this software and associated +documentation files (the "Software"), to deal in the +Software without restriction, including without +limitation the rights to use, copy, modify, merge, +publish, distribute, sublicense, and/or sell copies of +the Software, and to permit persons to whom the Software +is furnished to do so, subject to the following +conditions: + +The above copyright notice and this permission notice +shall be included in all copies or substantial portions +of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF +ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED +TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A +PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT +SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY +CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION +OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR +IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER +DEALINGS IN THE SOFTWARE. diff --git a/third_party/rust/tracing-core/README.md b/third_party/rust/tracing-core/README.md new file mode 100644 index 0000000000..5b33f8ca81 --- /dev/null +++ b/third_party/rust/tracing-core/README.md @@ -0,0 +1,121 @@ +![Tracing — Structured, application-level diagnostics][splash] + +[splash]: https://raw.githubusercontent.com/tokio-rs/tracing/master/assets/splash.svg + +# tracing-core + +Core primitives for application-level tracing. + +[![Crates.io][crates-badge]][crates-url] +[![Documentation][docs-badge]][docs-url] +[![Documentation (master)][docs-master-badge]][docs-master-url] +[![MIT licensed][mit-badge]][mit-url] +[![Build Status][actions-badge]][actions-url] +[![Discord chat][discord-badge]][discord-url] + +[Documentation][docs-url] | [Chat][discord-url] + +[crates-badge]: https://img.shields.io/crates/v/tracing-core.svg +[crates-url]: https://crates.io/crates/tracing-core/0.1.17 +[docs-badge]: https://docs.rs/tracing-core/badge.svg +[docs-url]: https://docs.rs/tracing-core/0.1.17 +[docs-master-badge]: https://img.shields.io/badge/docs-master-blue +[docs-master-url]: https://tracing-rs.netlify.com/tracing_core +[mit-badge]: https://img.shields.io/badge/license-MIT-blue.svg +[mit-url]: LICENSE +[actions-badge]: https://github.com/tokio-rs/tracing/workflows/CI/badge.svg +[actions-url]:https://github.com/tokio-rs/tracing/actions?query=workflow%3ACI +[discord-badge]: https://img.shields.io/discord/500028886025895936?logo=discord&label=discord&logoColor=white +[discord-url]: https://discord.gg/EeF3cQw + +## Overview + +[`tracing`] is a framework for instrumenting Rust programs to collect +structured, event-based diagnostic information. This crate defines the core +primitives of `tracing`. + +The crate provides: + +* [`span::Id`] identifies a span within the execution of a program. + +* [`Event`] represents a single event within a trace. + +* [`Subscriber`], the trait implemented to collect trace data. + +* [`Metadata`] and [`Callsite`] provide information describing spans and + events. + +* [`Field`], [`FieldSet`], [`Value`], and [`ValueSet`] represent the + structured data attached to spans and events. + +* [`Dispatch`] allows spans and events to be dispatched to `Subscriber`s. + +In addition, it defines the global callsite registry and per-thread current +dispatcher which other components of the tracing system rely on. + +*Compiler support: [requires `rustc` 1.40+][msrv]* + +[msrv]: #supported-rust-versions + +## Usage + +Application authors will typically not use this crate directly. Instead, they +will use the [`tracing`] crate, which provides a much more fully-featured +API. However, this crate's API will change very infrequently, so it may be used +when dependencies must be very stable. + +`Subscriber` implementations may depend on `tracing-core` rather than `tracing`, +as the additional APIs provided by `tracing` are primarily useful for +instrumenting libraries and applications, and are generally not necessary for +`Subscriber` implementations. + +### Crate Feature Flags + +The following crate feature flags are available: + +* `std`: Depend on the Rust standard library (enabled by default). + + `no_std` users may disable this feature with `default-features = false`: + + ```toml + [dependencies] + tracing-core = { version = "0.1.17", default-features = false } + ``` + + **Note**:`tracing-core`'s `no_std` support requires `liballoc`. + +[`tracing`]: ../tracing +[`span::Id`]: https://docs.rs/tracing-core/0.1.17/tracing_core/span/struct.Id.html +[`Event`]: https://docs.rs/tracing-core/0.1.17/tracing_core/event/struct.Event.html +[`Subscriber`]: https://docs.rs/tracing-core/0.1.17/tracing_core/subscriber/trait.Subscriber.html +[`Metadata`]: https://docs.rs/tracing-core/0.1.17/tracing_core/metadata/struct.Metadata.html +[`Callsite`]: https://docs.rs/tracing-core/0.1.17/tracing_core/callsite/trait.Callsite.html +[`Field`]: https://docs.rs/tracing-core/0.1.17/tracing_core/field/struct.Field.html +[`FieldSet`]: https://docs.rs/tracing-core/0.1.17/tracing_core/field/struct.FieldSet.html +[`Value`]: https://docs.rs/tracing-core/0.1.17/tracing_core/field/trait.Value.html +[`ValueSet`]: https://docs.rs/tracing-core/0.1.17/tracing_core/field/struct.ValueSet.html +[`Dispatch`]: https://docs.rs/tracing-core/0.1.17/tracing_core/dispatcher/struct.Dispatch.html + +## Supported Rust Versions + +Tracing is built against the latest stable release. The minimum supported +version is 1.40. The current Tracing version is not guaranteed to build on Rust +versions earlier than the minimum supported version. + +Tracing follows the same compiler support policies as the rest of the Tokio +project. The current stable Rust compiler and the three most recent minor +versions before it will always be supported. For example, if the current stable +compiler version is 1.45, the minimum supported version will not be increased +past 1.42, three minor versions prior. Increasing the minimum supported compiler +version is not considered a semver breaking change as long as doing so complies +with this policy. + +## License + +This project is licensed under the [MIT license](LICENSE). + +### Contribution + +Unless you explicitly state otherwise, any contribution intentionally submitted +for inclusion in Tokio by you, shall be licensed as MIT, without any additional +terms or conditions. diff --git a/third_party/rust/tracing-core/src/callsite.rs b/third_party/rust/tracing-core/src/callsite.rs new file mode 100644 index 0000000000..5e48473e15 --- /dev/null +++ b/third_party/rust/tracing-core/src/callsite.rs @@ -0,0 +1,171 @@ +//! Callsites represent the source locations from which spans or events +//! originate. +use crate::stdlib::{ + fmt, + hash::{Hash, Hasher}, + sync::Mutex, + vec::Vec, +}; +use crate::{ + dispatcher::{self, Dispatch}, + metadata::{LevelFilter, Metadata}, + subscriber::Interest, +}; + +lazy_static! { + static ref REGISTRY: Mutex<Registry> = Mutex::new(Registry { + callsites: Vec::new(), + dispatchers: Vec::new(), + }); +} + +struct Registry { + callsites: Vec<&'static dyn Callsite>, + dispatchers: Vec<dispatcher::Registrar>, +} + +impl Registry { + fn rebuild_callsite_interest(&self, callsite: &'static dyn Callsite) { + let meta = callsite.metadata(); + + // Iterate over the subscribers in the registry, and — if they are + // active — register the callsite with them. + let mut interests = self + .dispatchers + .iter() + .filter_map(|registrar| registrar.try_register(meta)); + + // Use the first subscriber's `Interest` as the base value. + let interest = if let Some(interest) = interests.next() { + // Combine all remaining `Interest`s. + interests.fold(interest, Interest::and) + } else { + // If nobody was interested in this thing, just return `never`. + Interest::never() + }; + + callsite.set_interest(interest) + } + + fn rebuild_interest(&mut self) { + let mut max_level = LevelFilter::OFF; + self.dispatchers.retain(|registrar| { + if let Some(dispatch) = registrar.upgrade() { + // If the subscriber did not provide a max level hint, assume + // that it may enable every level. + let level_hint = dispatch.max_level_hint().unwrap_or(LevelFilter::TRACE); + if level_hint > max_level { + max_level = level_hint; + } + true + } else { + false + } + }); + + self.callsites.iter().for_each(|&callsite| { + self.rebuild_callsite_interest(callsite); + }); + LevelFilter::set_max(max_level); + } +} + +/// Trait implemented by callsites. +/// +/// These functions are only intended to be called by the callsite registry, which +/// correctly handles determining the common interest between all subscribers. +pub trait Callsite: Sync { + /// Sets the [`Interest`] for this callsite. + /// + /// [`Interest`]: ../subscriber/struct.Interest.html + fn set_interest(&self, interest: Interest); + + /// Returns the [metadata] associated with the callsite. + /// + /// [metadata]: ../metadata/struct.Metadata.html + fn metadata(&self) -> &Metadata<'_>; +} + +/// Uniquely identifies a [`Callsite`] +/// +/// Two `Identifier`s are equal if they both refer to the same callsite. +/// +/// [`Callsite`]: ../callsite/trait.Callsite.html +#[derive(Clone)] +pub struct Identifier( + /// **Warning**: The fields on this type are currently `pub` because it must + /// be able to be constructed statically by macros. However, when `const + /// fn`s are available on stable Rust, this will no longer be necessary. + /// Thus, these fields are *not* considered stable public API, and they may + /// change warning. Do not rely on any fields on `Identifier`. When + /// constructing new `Identifier`s, use the `identify_callsite!` macro or + /// the `Callsite::id` function instead. + // TODO: When `Callsite::id` is a const fn, this need no longer be `pub`. + #[doc(hidden)] + pub &'static dyn Callsite, +); + +/// Clear and reregister interest on every [`Callsite`] +/// +/// This function is intended for runtime reconfiguration of filters on traces +/// when the filter recalculation is much less frequent than trace events are. +/// The alternative is to have the [`Subscriber`] that supports runtime +/// reconfiguration of filters always return [`Interest::sometimes()`] so that +/// [`enabled`] is evaluated for every event. +/// +/// This function will also re-compute the global maximum level as determined by +/// the [`max_level_hint`] method. If a [`Subscriber`] +/// implementation changes the value returned by its `max_level_hint` +/// implementation at runtime, then it **must** call this function after that +/// value changes, in order for the change to be reflected. +/// +/// [`max_level_hint`]: ../subscriber/trait.Subscriber.html#method.max_level_hint +/// [`Callsite`]: ../callsite/trait.Callsite.html +/// [`enabled`]: ../subscriber/trait.Subscriber.html#tymethod.enabled +/// [`Interest::sometimes()`]: ../subscriber/struct.Interest.html#method.sometimes +/// [`Subscriber`]: ../subscriber/trait.Subscriber.html +pub fn rebuild_interest_cache() { + let mut registry = REGISTRY.lock().unwrap(); + registry.rebuild_interest(); +} + +/// Register a new `Callsite` with the global registry. +/// +/// This should be called once per callsite after the callsite has been +/// constructed. +pub fn register(callsite: &'static dyn Callsite) { + let mut registry = REGISTRY.lock().unwrap(); + registry.rebuild_callsite_interest(callsite); + registry.callsites.push(callsite); +} + +pub(crate) fn register_dispatch(dispatch: &Dispatch) { + let mut registry = REGISTRY.lock().unwrap(); + registry.dispatchers.push(dispatch.registrar()); + registry.rebuild_interest(); +} + +// ===== impl Identifier ===== + +impl PartialEq for Identifier { + fn eq(&self, other: &Identifier) -> bool { + self.0 as *const _ as *const () == other.0 as *const _ as *const () + } +} + +impl Eq for Identifier {} + +impl fmt::Debug for Identifier { + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + write!(f, "Identifier({:p})", self.0) + } +} + +impl Hash for Identifier { + fn hash<H>(&self, state: &mut H) + where + H: Hasher, + { + (self.0 as *const dyn Callsite).hash(state) + } +} diff --git a/third_party/rust/tracing-core/src/dispatcher.rs b/third_party/rust/tracing-core/src/dispatcher.rs new file mode 100644 index 0000000000..658463584e --- /dev/null +++ b/third_party/rust/tracing-core/src/dispatcher.rs @@ -0,0 +1,947 @@ +//! Dispatches trace events to [`Subscriber`]s. +//! +//! The _dispatcher_ is the component of the tracing system which is responsible +//! for forwarding trace data from the instrumentation points that generate it +//! to the subscriber that collects it. +//! +//! # Using the Trace Dispatcher +//! +//! Every thread in a program using `tracing` has a _default subscriber_. When +//! events occur, or spans are created, they are dispatched to the thread's +//! current subscriber. +//! +//! ## Setting the Default Subscriber +//! +//! By default, the current subscriber is an empty implementation that does +//! nothing. To use a subscriber implementation, it must be set as the default. +//! There are two methods for doing so: [`with_default`] and +//! [`set_global_default`]. `with_default` sets the default subscriber for the +//! duration of a scope, while `set_global_default` sets a default subscriber +//! for the entire process. +//! +//! To use either of these functions, we must first wrap our subscriber in a +//! [`Dispatch`], a cloneable, type-erased reference to a subscriber. For +//! example: +//! ```rust +//! # pub struct FooSubscriber; +//! # use tracing_core::{ +//! # dispatcher, Event, Metadata, +//! # span::{Attributes, Id, Record} +//! # }; +//! # impl tracing_core::Subscriber for FooSubscriber { +//! # fn new_span(&self, _: &Attributes) -> Id { Id::from_u64(0) } +//! # fn record(&self, _: &Id, _: &Record) {} +//! # fn event(&self, _: &Event) {} +//! # fn record_follows_from(&self, _: &Id, _: &Id) {} +//! # fn enabled(&self, _: &Metadata) -> bool { false } +//! # fn enter(&self, _: &Id) {} +//! # fn exit(&self, _: &Id) {} +//! # } +//! # impl FooSubscriber { fn new() -> Self { FooSubscriber } } +//! use dispatcher::Dispatch; +//! +//! let my_subscriber = FooSubscriber::new(); +//! let my_dispatch = Dispatch::new(my_subscriber); +//! ``` +//! Then, we can use [`with_default`] to set our `Dispatch` as the default for +//! the duration of a block: +//! ```rust +//! # pub struct FooSubscriber; +//! # use tracing_core::{ +//! # dispatcher, Event, Metadata, +//! # span::{Attributes, Id, Record} +//! # }; +//! # impl tracing_core::Subscriber for FooSubscriber { +//! # fn new_span(&self, _: &Attributes) -> Id { Id::from_u64(0) } +//! # fn record(&self, _: &Id, _: &Record) {} +//! # fn event(&self, _: &Event) {} +//! # fn record_follows_from(&self, _: &Id, _: &Id) {} +//! # fn enabled(&self, _: &Metadata) -> bool { false } +//! # fn enter(&self, _: &Id) {} +//! # fn exit(&self, _: &Id) {} +//! # } +//! # impl FooSubscriber { fn new() -> Self { FooSubscriber } } +//! # let my_subscriber = FooSubscriber::new(); +//! # let my_dispatch = dispatcher::Dispatch::new(my_subscriber); +//! // no default subscriber +//! +//! # #[cfg(feature = "std")] +//! dispatcher::with_default(&my_dispatch, || { +//! // my_subscriber is the default +//! }); +//! +//! // no default subscriber again +//! ``` +//! It's important to note that `with_default` will not propagate the current +//! thread's default subscriber to any threads spawned within the `with_default` +//! block. To propagate the default subscriber to new threads, either use +//! `with_default` from the new thread, or use `set_global_default`. +//! +//! As an alternative to `with_default`, we can use [`set_global_default`] to +//! set a `Dispatch` as the default for all threads, for the lifetime of the +//! program. For example: +//! ```rust +//! # pub struct FooSubscriber; +//! # use tracing_core::{ +//! # dispatcher, Event, Metadata, +//! # span::{Attributes, Id, Record} +//! # }; +//! # impl tracing_core::Subscriber for FooSubscriber { +//! # fn new_span(&self, _: &Attributes) -> Id { Id::from_u64(0) } +//! # fn record(&self, _: &Id, _: &Record) {} +//! # fn event(&self, _: &Event) {} +//! # fn record_follows_from(&self, _: &Id, _: &Id) {} +//! # fn enabled(&self, _: &Metadata) -> bool { false } +//! # fn enter(&self, _: &Id) {} +//! # fn exit(&self, _: &Id) {} +//! # } +//! # impl FooSubscriber { fn new() -> Self { FooSubscriber } } +//! # let my_subscriber = FooSubscriber::new(); +//! # let my_dispatch = dispatcher::Dispatch::new(my_subscriber); +//! // no default subscriber +//! +//! dispatcher::set_global_default(my_dispatch) +//! // `set_global_default` will return an error if the global default +//! // subscriber has already been set. +//! .expect("global default was already set!"); +//! +//! // `my_subscriber` is now the default +//! ``` +//! +//! <div class="information"> +//! <div class="tooltip ignore" style="">ⓘ<span class="tooltiptext">Note</span></div> +//! </div> +//! <div class="example-wrap" style="display:inline-block"> +//! <pre class="ignore" style="white-space:normal;font:inherit;"> +//! <strong>Note</strong>:the thread-local scoped dispatcher +//! (<a href="#fn.with_default"><code>with_default</code></a>) requires the +//! Rust standard library. <code>no_std</code> users should use +//! <a href="#fn.set_global_default"><code>set_global_default</code></a> +//! instead. +//! </pre></div> +//! +//! ## Accessing the Default Subscriber +//! +//! A thread's current default subscriber can be accessed using the +//! [`get_default`] function, which executes a closure with a reference to the +//! currently default `Dispatch`. This is used primarily by `tracing` +//! instrumentation. +//! +//! [`Subscriber`]: struct.Subscriber.html +//! [`with_default`]: fn.with_default.html +//! [`set_global_default`]: fn.set_global_default.html +//! [`get_default`]: fn.get_default.html +//! [`Dispatch`]: struct.Dispatch.html +use crate::{ + callsite, span, + subscriber::{self, Subscriber}, + Event, LevelFilter, Metadata, +}; + +use crate::stdlib::{ + any::Any, + fmt, + sync::{ + atomic::{AtomicBool, AtomicUsize, Ordering}, + Arc, Weak, + }, +}; + +#[cfg(feature = "std")] +use crate::stdlib::{ + cell::{Cell, RefCell, RefMut}, + error, +}; + +/// `Dispatch` trace data to a [`Subscriber`]. +/// +/// [`Subscriber`]: trait.Subscriber.html +#[derive(Clone)] +pub struct Dispatch { + subscriber: Arc<dyn Subscriber + Send + Sync>, +} + +#[cfg(feature = "std")] +thread_local! { + static CURRENT_STATE: State = State { + default: RefCell::new(Dispatch::none()), + can_enter: Cell::new(true), + }; +} + +static EXISTS: AtomicBool = AtomicBool::new(false); +static GLOBAL_INIT: AtomicUsize = AtomicUsize::new(UNINITIALIZED); + +const UNINITIALIZED: usize = 0; +const INITIALIZING: usize = 1; +const INITIALIZED: usize = 2; + +static mut GLOBAL_DISPATCH: Option<Dispatch> = None; + +/// The dispatch state of a thread. +#[cfg(feature = "std")] +struct State { + /// This thread's current default dispatcher. + default: RefCell<Dispatch>, + /// Whether or not we can currently begin dispatching a trace event. + /// + /// This is set to `false` when functions such as `enter`, `exit`, `event`, + /// and `new_span` are called on this thread's default dispatcher, to + /// prevent further trace events triggered inside those functions from + /// creating an infinite recursion. When we finish handling a dispatch, this + /// is set back to `true`. + can_enter: Cell<bool>, +} + +/// While this guard is active, additional calls to subscriber functions on +/// the default dispatcher will not be able to access the dispatch context. +/// Dropping the guard will allow the dispatch context to be re-entered. +#[cfg(feature = "std")] +struct Entered<'a>(&'a State); + +/// A guard that resets the current default dispatcher to the prior +/// default dispatcher when dropped. +#[cfg(feature = "std")] +#[cfg_attr(docsrs, doc(cfg(feature = "std")))] +#[derive(Debug)] +pub struct DefaultGuard(Option<Dispatch>); + +/// Sets this dispatch as the default for the duration of a closure. +/// +/// The default dispatcher is used when creating a new [span] or +/// [`Event`]. +/// +/// <div class="information"> +/// <div class="tooltip ignore" style="">ⓘ<span class="tooltiptext">Note</span></div> +/// </div> +/// <div class="example-wrap" style="display:inline-block"> +/// <pre class="ignore" style="white-space:normal;font:inherit;"> +/// <strong>Note</strong>: This function required the Rust standard library. +/// <code>no_std</code> users should use <a href="../fn.set_global_default.html"> +/// <code>set_global_default</code></a> instead. +/// </pre></div> +/// +/// [span]: ../span/index.html +/// [`Subscriber`]: ../subscriber/trait.Subscriber.html +/// [`Event`]: ../event/struct.Event.html +/// [`set_global_default`]: ../fn.set_global_default.html +#[cfg(feature = "std")] +#[cfg_attr(docsrs, doc(cfg(feature = "std")))] +pub fn with_default<T>(dispatcher: &Dispatch, f: impl FnOnce() -> T) -> T { + // When this guard is dropped, the default dispatcher will be reset to the + // prior default. Using this (rather than simply resetting after calling + // `f`) ensures that we always reset to the prior dispatcher even if `f` + // panics. + let _guard = set_default(dispatcher); + f() +} + +/// Sets the dispatch as the default dispatch for the duration of the lifetime +/// of the returned DefaultGuard +/// +/// <div class="information"> +/// <div class="tooltip ignore" style="">ⓘ<span class="tooltiptext">Note</span></div> +/// </div> +/// <div class="example-wrap" style="display:inline-block"> +/// <pre class="ignore" style="white-space:normal;font:inherit;"> +/// <strong>Note</strong>: This function required the Rust standard library. +/// <code>no_std</code> users should use <a href="../fn.set_global_default.html"> +/// <code>set_global_default</code></a> instead. +/// </pre></div> +/// +/// [`set_global_default`]: ../fn.set_global_default.html +#[cfg(feature = "std")] +#[cfg_attr(docsrs, doc(cfg(feature = "std")))] +#[must_use = "Dropping the guard unregisters the dispatcher."] +pub fn set_default(dispatcher: &Dispatch) -> DefaultGuard { + // When this guard is dropped, the default dispatcher will be reset to the + // prior default. Using this ensures that we always reset to the prior + // dispatcher even if the thread calling this function panics. + State::set_default(dispatcher.clone()) +} + +/// Sets this dispatch as the global default for the duration of the entire program. +/// Will be used as a fallback if no thread-local dispatch has been set in a thread +/// (using `with_default`.) +/// +/// Can only be set once; subsequent attempts to set the global default will fail. +/// Returns `Err` if the global default has already been set. +/// +/// +/// <div class="information"> +/// <div class="tooltip compile_fail" style="">⚠ ️<span class="tooltiptext">Warning</span></div> +/// </div><div class="example-wrap" style="display:inline-block"><pre class="compile_fail" style="white-space:normal;font:inherit;"> +/// <strong>Warning</strong>: In general, libraries should <em>not</em> call +/// <code>set_global_default()</code>! Doing so will cause conflicts when +/// executables that depend on the library try to set the default later. +/// </pre></div> +/// +/// [span]: ../span/index.html +/// [`Subscriber`]: ../subscriber/trait.Subscriber.html +/// [`Event`]: ../event/struct.Event.html +pub fn set_global_default(dispatcher: Dispatch) -> Result<(), SetGlobalDefaultError> { + if GLOBAL_INIT.compare_and_swap(UNINITIALIZED, INITIALIZING, Ordering::SeqCst) == UNINITIALIZED + { + unsafe { + GLOBAL_DISPATCH = Some(dispatcher); + } + GLOBAL_INIT.store(INITIALIZED, Ordering::SeqCst); + EXISTS.store(true, Ordering::Release); + Ok(()) + } else { + Err(SetGlobalDefaultError { _no_construct: () }) + } +} + +/// Returns true if a `tracing` dispatcher has ever been set. +/// +/// This may be used to completely elide trace points if tracing is not in use +/// at all or has yet to be initialized. +#[doc(hidden)] +#[inline(always)] +pub fn has_been_set() -> bool { + EXISTS.load(Ordering::Relaxed) +} + +/// Returned if setting the global dispatcher fails. +#[derive(Debug)] +pub struct SetGlobalDefaultError { + _no_construct: (), +} + +impl fmt::Display for SetGlobalDefaultError { + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + f.pad("a global default trace dispatcher has already been set") + } +} + +#[cfg(feature = "std")] +#[cfg_attr(docsrs, doc(cfg(feature = "std")))] +impl error::Error for SetGlobalDefaultError {} + +/// Executes a closure with a reference to this thread's current [dispatcher]. +/// +/// Note that calls to `get_default` should not be nested; if this function is +/// called while inside of another `get_default`, that closure will be provided +/// with `Dispatch::none` rather than the previously set dispatcher. +/// +/// [dispatcher]: ../dispatcher/struct.Dispatch.html +#[cfg(feature = "std")] +pub fn get_default<T, F>(mut f: F) -> T +where + F: FnMut(&Dispatch) -> T, +{ + CURRENT_STATE + .try_with(|state| { + if let Some(entered) = state.enter() { + return f(&*entered.current()); + } + + f(&Dispatch::none()) + }) + .unwrap_or_else(|_| f(&Dispatch::none())) +} + +/// Executes a closure with a reference to this thread's current [dispatcher]. +/// +/// Note that calls to `get_default` should not be nested; if this function is +/// called while inside of another `get_default`, that closure will be provided +/// with `Dispatch::none` rather than the previously set dispatcher. +/// +/// [dispatcher]: ../dispatcher/struct.Dispatch.html +#[cfg(feature = "std")] +#[doc(hidden)] +#[inline(never)] +pub fn get_current<T>(f: impl FnOnce(&Dispatch) -> T) -> Option<T> { + CURRENT_STATE + .try_with(|state| { + let entered = state.enter()?; + Some(f(&*entered.current())) + }) + .ok()? +} + +/// Executes a closure with a reference to the current [dispatcher]. +/// +/// [dispatcher]: ../dispatcher/struct.Dispatch.html +#[cfg(not(feature = "std"))] +#[doc(hidden)] +pub fn get_current<T>(f: impl FnOnce(&Dispatch) -> T) -> Option<T> { + let dispatch = get_global()?; + Some(f(&dispatch)) +} + +/// Executes a closure with a reference to the current [dispatcher]. +/// +/// [dispatcher]: ../dispatcher/struct.Dispatch.html +#[cfg(not(feature = "std"))] +pub fn get_default<T, F>(mut f: F) -> T +where + F: FnMut(&Dispatch) -> T, +{ + if let Some(d) = get_global() { + f(d) + } else { + f(&Dispatch::none()) + } +} + +fn get_global() -> Option<&'static Dispatch> { + if GLOBAL_INIT.load(Ordering::SeqCst) != INITIALIZED { + return None; + } + unsafe { + // This is safe given the invariant that setting the global dispatcher + // also sets `GLOBAL_INIT` to `INITIALIZED`. + Some(GLOBAL_DISPATCH.as_ref().expect( + "invariant violated: GLOBAL_DISPATCH must be initialized before GLOBAL_INIT is set", + )) + } +} + +pub(crate) struct Registrar(Weak<dyn Subscriber + Send + Sync>); + +impl Dispatch { + /// Returns a new `Dispatch` that discards events and spans. + #[inline] + pub fn none() -> Self { + Dispatch { + subscriber: Arc::new(NoSubscriber), + } + } + + /// Returns a `Dispatch` that forwards to the given [`Subscriber`]. + /// + /// [`Subscriber`]: ../subscriber/trait.Subscriber.html + pub fn new<S>(subscriber: S) -> Self + where + S: Subscriber + Send + Sync + 'static, + { + let me = Dispatch { + subscriber: Arc::new(subscriber), + }; + callsite::register_dispatch(&me); + me + } + + pub(crate) fn registrar(&self) -> Registrar { + Registrar(Arc::downgrade(&self.subscriber)) + } + + /// Registers a new callsite with this subscriber, returning whether or not + /// the subscriber is interested in being notified about the callsite. + /// + /// This calls the [`register_callsite`] function on the [`Subscriber`] + /// that this `Dispatch` forwards to. + /// + /// [`Subscriber`]: ../subscriber/trait.Subscriber.html + /// [`register_callsite`]: ../subscriber/trait.Subscriber.html#method.register_callsite + #[inline] + pub fn register_callsite(&self, metadata: &'static Metadata<'static>) -> subscriber::Interest { + self.subscriber.register_callsite(metadata) + } + + /// Returns the highest [verbosity level][level] that this [`Subscriber`] will + /// enable, or `None`, if the subscriber does not implement level-based + /// filtering or chooses not to implement this method. + /// + /// This calls the [`max_level_hint`] function on the [`Subscriber`] + /// that this `Dispatch` forwards to. + /// + /// [level]: ../struct.Level.html + /// [`Subscriber`]: ../subscriber/trait.Subscriber.html + /// [`register_callsite`]: ../subscriber/trait.Subscriber.html#method.max_level_hint + // TODO(eliza): consider making this a public API? + #[inline] + pub(crate) fn max_level_hint(&self) -> Option<LevelFilter> { + self.subscriber.max_level_hint() + } + + /// Record the construction of a new span, returning a new [ID] for the + /// span being constructed. + /// + /// This calls the [`new_span`] function on the [`Subscriber`] that this + /// `Dispatch` forwards to. + /// + /// [ID]: ../span/struct.Id.html + /// [`Subscriber`]: ../subscriber/trait.Subscriber.html + /// [`new_span`]: ../subscriber/trait.Subscriber.html#method.new_span + #[inline] + pub fn new_span(&self, span: &span::Attributes<'_>) -> span::Id { + self.subscriber.new_span(span) + } + + /// Record a set of values on a span. + /// + /// This calls the [`record`] function on the [`Subscriber`] that this + /// `Dispatch` forwards to. + /// + /// [`Subscriber`]: ../subscriber/trait.Subscriber.html + /// [`record`]: ../subscriber/trait.Subscriber.html#method.record + #[inline] + pub fn record(&self, span: &span::Id, values: &span::Record<'_>) { + self.subscriber.record(span, values) + } + + /// Adds an indication that `span` follows from the span with the id + /// `follows`. + /// + /// This calls the [`record_follows_from`] function on the [`Subscriber`] + /// that this `Dispatch` forwards to. + /// + /// [`Subscriber`]: ../subscriber/trait.Subscriber.html + /// [`record_follows_from`]: ../subscriber/trait.Subscriber.html#method.record_follows_from + #[inline] + pub fn record_follows_from(&self, span: &span::Id, follows: &span::Id) { + self.subscriber.record_follows_from(span, follows) + } + + /// Returns true if a span with the specified [metadata] would be + /// recorded. + /// + /// This calls the [`enabled`] function on the [`Subscriber`] that this + /// `Dispatch` forwards to. + /// + /// [metadata]: ../metadata/struct.Metadata.html + /// [`Subscriber`]: ../subscriber/trait.Subscriber.html + /// [`enabled`]: ../subscriber/trait.Subscriber.html#method.enabled + #[inline] + pub fn enabled(&self, metadata: &Metadata<'_>) -> bool { + self.subscriber.enabled(metadata) + } + + /// Records that an [`Event`] has occurred. + /// + /// This calls the [`event`] function on the [`Subscriber`] that this + /// `Dispatch` forwards to. + /// + /// [`Event`]: ../event/struct.Event.html + /// [`Subscriber`]: ../subscriber/trait.Subscriber.html + /// [`event`]: ../subscriber/trait.Subscriber.html#method.event + #[inline] + pub fn event(&self, event: &Event<'_>) { + self.subscriber.event(event) + } + + /// Records that a span has been can_enter. + /// + /// This calls the [`enter`] function on the [`Subscriber`] that this + /// `Dispatch` forwards to. + /// + /// [`Subscriber`]: ../subscriber/trait.Subscriber.html + /// [`enter`]: ../subscriber/trait.Subscriber.html#method.enter + #[inline] + pub fn enter(&self, span: &span::Id) { + self.subscriber.enter(span); + } + + /// Records that a span has been exited. + /// + /// This calls the [`exit`] function on the [`Subscriber`] that this + /// `Dispatch` forwards to. + /// + /// [`Subscriber`]: ../subscriber/trait.Subscriber.html + /// [`exit`]: ../subscriber/trait.Subscriber.html#method.exit + #[inline] + pub fn exit(&self, span: &span::Id) { + self.subscriber.exit(span); + } + + /// Notifies the subscriber that a [span ID] has been cloned. + /// + /// This function must only be called with span IDs that were returned by + /// this `Dispatch`'s [`new_span`] function. The `tracing` crate upholds + /// this guarantee and any other libraries implementing instrumentation APIs + /// must as well. + /// + /// This calls the [`clone_span`] function on the `Subscriber` that this + /// `Dispatch` forwards to. + /// + /// [span ID]: ../span/struct.Id.html + /// [`Subscriber`]: ../subscriber/trait.Subscriber.html + /// [`clone_span`]: ../subscriber/trait.Subscriber.html#method.clone_span + /// [`new_span`]: ../subscriber/trait.Subscriber.html#method.new_span + #[inline] + pub fn clone_span(&self, id: &span::Id) -> span::Id { + self.subscriber.clone_span(&id) + } + + /// Notifies the subscriber that a [span ID] has been dropped. + /// + /// This function must only be called with span IDs that were returned by + /// this `Dispatch`'s [`new_span`] function. The `tracing` crate upholds + /// this guarantee and any other libraries implementing instrumentation APIs + /// must as well. + /// + /// This calls the [`drop_span`] function on the [`Subscriber`] that this + /// `Dispatch` forwards to. + /// + /// <div class="information"> + /// <div class="tooltip compile_fail" style="">⚠ ️<span class="tooltiptext">Warning</span></div> + /// </div> + /// <div class="example-wrap" style="display:inline-block"><pre class="compile_fail" style="white-space:normal;font:inherit;"> + /// <strong>Deprecated</strong>: The <a href="#method.try_close"><code>try_close</code></a> + /// method is functionally identical, but returns <code>true</code> if the span is now closed. + /// It should be used instead of this method. + /// </pre></div> + /// + /// [span ID]: ../span/struct.Id.html + /// [`Subscriber`]: ../subscriber/trait.Subscriber.html + /// [`drop_span`]: ../subscriber/trait.Subscriber.html#method.drop_span + /// [`new_span`]: ../subscriber/trait.Subscriber.html#method.new_span + /// [`try_close`]: #method.try_close + #[inline] + #[deprecated(since = "0.1.2", note = "use `Dispatch::try_close` instead")] + pub fn drop_span(&self, id: span::Id) { + #[allow(deprecated)] + self.subscriber.drop_span(id); + } + + /// Notifies the subscriber that a [span ID] has been dropped, and returns + /// `true` if there are now 0 IDs referring to that span. + /// + /// This function must only be called with span IDs that were returned by + /// this `Dispatch`'s [`new_span`] function. The `tracing` crate upholds + /// this guarantee and any other libraries implementing instrumentation APIs + /// must as well. + /// + /// This calls the [`try_close`] function on the [`Subscriber`] that this + /// `Dispatch` forwards to. + /// + /// [span ID]: ../span/struct.Id.html + /// [`Subscriber`]: ../subscriber/trait.Subscriber.html + /// [`try_close`]: ../subscriber/trait.Subscriber.html#method.try_close + /// [`new_span`]: ../subscriber/trait.Subscriber.html#method.new_span + #[inline] + pub fn try_close(&self, id: span::Id) -> bool { + self.subscriber.try_close(id) + } + + /// Returns a type representing this subscriber's view of the current span. + /// + /// This calls the [`current`] function on the `Subscriber` that this + /// `Dispatch` forwards to. + /// + /// [`current`]: ../subscriber/trait.Subscriber.html#method.current + #[inline] + pub fn current_span(&self) -> span::Current { + self.subscriber.current_span() + } + + /// Returns `true` if this `Dispatch` forwards to a `Subscriber` of type + /// `T`. + #[inline] + pub fn is<T: Any>(&self) -> bool { + Subscriber::is::<T>(&*self.subscriber) + } + + /// Returns some reference to the `Subscriber` this `Dispatch` forwards to + /// if it is of type `T`, or `None` if it isn't. + #[inline] + pub fn downcast_ref<T: Any>(&self) -> Option<&T> { + Subscriber::downcast_ref(&*self.subscriber) + } +} + +impl Default for Dispatch { + /// Returns the current default dispatcher + fn default() -> Self { + get_default(|default| default.clone()) + } +} + +impl fmt::Debug for Dispatch { + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + f.pad("Dispatch(...)") + } +} + +impl<S> From<S> for Dispatch +where + S: Subscriber + Send + Sync + 'static, +{ + #[inline] + fn from(subscriber: S) -> Self { + Dispatch::new(subscriber) + } +} + +struct NoSubscriber; +impl Subscriber for NoSubscriber { + #[inline] + fn register_callsite(&self, _: &'static Metadata<'static>) -> subscriber::Interest { + subscriber::Interest::never() + } + + fn new_span(&self, _: &span::Attributes<'_>) -> span::Id { + span::Id::from_u64(0xDEAD) + } + + fn event(&self, _event: &Event<'_>) {} + + fn record(&self, _span: &span::Id, _values: &span::Record<'_>) {} + + fn record_follows_from(&self, _span: &span::Id, _follows: &span::Id) {} + + #[inline] + fn enabled(&self, _metadata: &Metadata<'_>) -> bool { + false + } + + fn enter(&self, _span: &span::Id) {} + fn exit(&self, _span: &span::Id) {} +} + +impl Registrar { + pub(crate) fn try_register( + &self, + metadata: &'static Metadata<'static>, + ) -> Option<subscriber::Interest> { + self.0.upgrade().map(|s| s.register_callsite(metadata)) + } + + pub(crate) fn upgrade(&self) -> Option<Dispatch> { + self.0.upgrade().map(|subscriber| Dispatch { subscriber }) + } +} + +// ===== impl State ===== + +#[cfg(feature = "std")] +impl State { + /// Replaces the current default dispatcher on this thread with the provided + /// dispatcher.Any + /// + /// Dropping the returned `ResetGuard` will reset the default dispatcher to + /// the previous value. + #[inline] + fn set_default(new_dispatch: Dispatch) -> DefaultGuard { + let prior = CURRENT_STATE + .try_with(|state| { + state.can_enter.set(true); + state.default.replace(new_dispatch) + }) + .ok(); + EXISTS.store(true, Ordering::Release); + DefaultGuard(prior) + } + + #[inline] + fn enter(&self) -> Option<Entered<'_>> { + if self.can_enter.replace(false) { + Some(Entered(&self)) + } else { + None + } + } +} + +// ===== impl Entered ===== + +#[cfg(feature = "std")] +impl<'a> Entered<'a> { + #[inline] + fn current(&self) -> RefMut<'a, Dispatch> { + let mut default = self.0.default.borrow_mut(); + + if default.is::<NoSubscriber>() { + if let Some(global) = get_global() { + // don't redo this call on the next check + *default = global.clone(); + } + } + + default + } +} + +#[cfg(feature = "std")] +impl<'a> Drop for Entered<'a> { + #[inline] + fn drop(&mut self) { + self.0.can_enter.set(true); + } +} + +// ===== impl DefaultGuard ===== + +#[cfg(feature = "std")] +impl Drop for DefaultGuard { + #[inline] + fn drop(&mut self) { + if let Some(dispatch) = self.0.take() { + // Replace the dispatcher and then drop the old one outside + // of the thread-local context. Dropping the dispatch may + // lead to the drop of a subscriber which, in the process, + // could then also attempt to access the same thread local + // state -- causing a clash. + let prev = CURRENT_STATE.try_with(|state| state.default.replace(dispatch)); + drop(prev) + } + } +} + +#[cfg(test)] +mod test { + use super::*; + #[cfg(feature = "std")] + use crate::stdlib::sync::atomic::{AtomicUsize, Ordering}; + use crate::{ + callsite::Callsite, + metadata::{Kind, Level, Metadata}, + subscriber::Interest, + }; + + #[test] + fn dispatch_is() { + let dispatcher = Dispatch::new(NoSubscriber); + assert!(dispatcher.is::<NoSubscriber>()); + } + + #[test] + fn dispatch_downcasts() { + let dispatcher = Dispatch::new(NoSubscriber); + assert!(dispatcher.downcast_ref::<NoSubscriber>().is_some()); + } + + struct TestCallsite; + static TEST_CALLSITE: TestCallsite = TestCallsite; + static TEST_META: Metadata<'static> = metadata! { + name: "test", + target: module_path!(), + level: Level::DEBUG, + fields: &[], + callsite: &TEST_CALLSITE, + kind: Kind::EVENT + }; + + impl Callsite for TestCallsite { + fn set_interest(&self, _: Interest) {} + fn metadata(&self) -> &Metadata<'_> { + &TEST_META + } + } + + #[test] + #[cfg(feature = "std")] + fn events_dont_infinite_loop() { + // This test ensures that an event triggered within a subscriber + // won't cause an infinite loop of events. + struct TestSubscriber; + impl Subscriber for TestSubscriber { + fn enabled(&self, _: &Metadata<'_>) -> bool { + true + } + + fn new_span(&self, _: &span::Attributes<'_>) -> span::Id { + span::Id::from_u64(0xAAAA) + } + + fn record(&self, _: &span::Id, _: &span::Record<'_>) {} + + fn record_follows_from(&self, _: &span::Id, _: &span::Id) {} + + fn event(&self, _: &Event<'_>) { + static EVENTS: AtomicUsize = AtomicUsize::new(0); + assert_eq!( + EVENTS.fetch_add(1, Ordering::Relaxed), + 0, + "event method called twice!" + ); + Event::dispatch(&TEST_META, &TEST_META.fields().value_set(&[])) + } + + fn enter(&self, _: &span::Id) {} + + fn exit(&self, _: &span::Id) {} + } + + with_default(&Dispatch::new(TestSubscriber), || { + Event::dispatch(&TEST_META, &TEST_META.fields().value_set(&[])) + }) + } + + #[test] + #[cfg(feature = "std")] + fn spans_dont_infinite_loop() { + // This test ensures that a span created within a subscriber + // won't cause an infinite loop of new spans. + + fn mk_span() { + get_default(|current| { + current.new_span(&span::Attributes::new( + &TEST_META, + &TEST_META.fields().value_set(&[]), + )) + }); + } + + struct TestSubscriber; + impl Subscriber for TestSubscriber { + fn enabled(&self, _: &Metadata<'_>) -> bool { + true + } + + fn new_span(&self, _: &span::Attributes<'_>) -> span::Id { + static NEW_SPANS: AtomicUsize = AtomicUsize::new(0); + assert_eq!( + NEW_SPANS.fetch_add(1, Ordering::Relaxed), + 0, + "new_span method called twice!" + ); + mk_span(); + span::Id::from_u64(0xAAAA) + } + + fn record(&self, _: &span::Id, _: &span::Record<'_>) {} + + fn record_follows_from(&self, _: &span::Id, _: &span::Id) {} + + fn event(&self, _: &Event<'_>) {} + + fn enter(&self, _: &span::Id) {} + + fn exit(&self, _: &span::Id) {} + } + + with_default(&Dispatch::new(TestSubscriber), mk_span) + } + + #[test] + fn default_no_subscriber() { + let default_dispatcher = Dispatch::default(); + assert!(default_dispatcher.is::<NoSubscriber>()); + } + + #[cfg(feature = "std")] + #[test] + fn default_dispatch() { + struct TestSubscriber; + impl Subscriber for TestSubscriber { + fn enabled(&self, _: &Metadata<'_>) -> bool { + true + } + + fn new_span(&self, _: &span::Attributes<'_>) -> span::Id { + span::Id::from_u64(0xAAAA) + } + + fn record(&self, _: &span::Id, _: &span::Record<'_>) {} + + fn record_follows_from(&self, _: &span::Id, _: &span::Id) {} + + fn event(&self, _: &Event<'_>) {} + + fn enter(&self, _: &span::Id) {} + + fn exit(&self, _: &span::Id) {} + } + let guard = set_default(&Dispatch::new(TestSubscriber)); + let default_dispatcher = Dispatch::default(); + assert!(default_dispatcher.is::<TestSubscriber>()); + + drop(guard); + let default_dispatcher = Dispatch::default(); + assert!(default_dispatcher.is::<NoSubscriber>()); + } +} diff --git a/third_party/rust/tracing-core/src/event.rs b/third_party/rust/tracing-core/src/event.rs new file mode 100644 index 0000000000..2c886ced47 --- /dev/null +++ b/third_party/rust/tracing-core/src/event.rs @@ -0,0 +1,134 @@ +//! Events represent single points in time during the execution of a program. +use crate::parent::Parent; +use crate::span::Id; +use crate::{field, Metadata}; + +/// `Event`s represent single points in time where something occurred during the +/// execution of a program. +/// +/// An `Event` can be compared to a log record in unstructured logging, but with +/// two key differences: +/// - `Event`s exist _within the context of a [span]_. Unlike log lines, they +/// may be located within the trace tree, allowing visibility into the +/// _temporal_ context in which the event occurred, as well as the source +/// code location. +/// - Like spans, `Event`s have structured key-value data known as _[fields]_, +/// which may include textual message. In general, a majority of the data +/// associated with an event should be in the event's fields rather than in +/// the textual message, as the fields are more structured. +/// +/// [span]: ../span +/// [fields]: ../field +#[derive(Debug)] +pub struct Event<'a> { + fields: &'a field::ValueSet<'a>, + metadata: &'static Metadata<'static>, + parent: Parent, +} + +impl<'a> Event<'a> { + /// Constructs a new `Event` with the specified metadata and set of values, + /// and observes it with the current subscriber. + pub fn dispatch(metadata: &'static Metadata<'static>, fields: &'a field::ValueSet<'_>) { + let event = Event::new(metadata, fields); + crate::dispatcher::get_default(|current| { + current.event(&event); + }); + } + + /// Returns a new `Event` in the current span, with the specified metadata + /// and set of values. + #[inline] + pub fn new(metadata: &'static Metadata<'static>, fields: &'a field::ValueSet<'a>) -> Self { + Event { + metadata, + fields, + parent: Parent::Current, + } + } + + /// Returns a new `Event` as a child of the specified span, with the + /// provided metadata and set of values. + #[inline] + pub fn new_child_of( + parent: impl Into<Option<Id>>, + metadata: &'static Metadata<'static>, + fields: &'a field::ValueSet<'a>, + ) -> Self { + let parent = match parent.into() { + Some(p) => Parent::Explicit(p), + None => Parent::Root, + }; + Event { + metadata, + fields, + parent, + } + } + + /// Constructs a new `Event` with the specified metadata and set of values, + /// and observes it with the current subscriber and an explicit parent. + pub fn child_of( + parent: impl Into<Option<Id>>, + metadata: &'static Metadata<'static>, + fields: &'a field::ValueSet<'_>, + ) { + let event = Self::new_child_of(parent, metadata, fields); + crate::dispatcher::get_default(|current| { + current.event(&event); + }); + } + + /// Visits all the fields on this `Event` with the specified [visitor]. + /// + /// [visitor]: ../field/trait.Visit.html + #[inline] + pub fn record(&self, visitor: &mut dyn field::Visit) { + self.fields.record(visitor); + } + + /// Returns an iterator over the set of values on this `Event`. + pub fn fields(&self) -> field::Iter { + self.fields.field_set().iter() + } + + /// Returns [metadata] describing this `Event`. + /// + /// [metadata]: ../struct.Metadata.html + pub fn metadata(&self) -> &'static Metadata<'static> { + self.metadata + } + + /// Returns true if the new event should be a root. + pub fn is_root(&self) -> bool { + match self.parent { + Parent::Root => true, + _ => false, + } + } + + /// Returns true if the new event's parent should be determined based on the + /// current context. + /// + /// If this is true and the current thread is currently inside a span, then + /// that span should be the new event's parent. Otherwise, if the current + /// thread is _not_ inside a span, then the new event will be the root of its + /// own trace tree. + pub fn is_contextual(&self) -> bool { + match self.parent { + Parent::Current => true, + _ => false, + } + } + + /// Returns the new event's explicitly-specified parent, if there is one. + /// + /// Otherwise (if the new event is a root or is a child of the current span), + /// returns false. + pub fn parent(&self) -> Option<&Id> { + match self.parent { + Parent::Explicit(ref p) => Some(p), + _ => None, + } + } +} diff --git a/third_party/rust/tracing-core/src/field.rs b/third_party/rust/tracing-core/src/field.rs new file mode 100644 index 0000000000..1cda8d9cb8 --- /dev/null +++ b/third_party/rust/tracing-core/src/field.rs @@ -0,0 +1,980 @@ +//! Span and `Event` key-value data. +//! +//! Spans and events may be annotated with key-value data, referred to as known +//! 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 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`, `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, +//! we might record integers by incrementing counters for their field names, +//! rather than printing them. +//! +//! [`Value`]: trait.Value.html +//! [span]: ../span/ +//! [`Event`]: ../event/struct.Event.html +//! [`Metadata`]: ../metadata/struct.Metadata.html +//! [`Attributes`]: ../span/struct.Attributes.html +//! [`Record`]: ../span/struct.Record.html +//! [`new_span`]: ../subscriber/trait.Subscriber.html#method.new_span +//! [`record`]: ../subscriber/trait.Subscriber.html#method.record +//! [`event`]: ../subscriber/trait.Subscriber.html#method.event +//! [`Value::record`]: trait.Value.html#method.record +//! [`Visit`]: trait.Visit.html +use crate::callsite; +use crate::stdlib::{ + borrow::Borrow, + fmt, + hash::{Hash, Hasher}, + num, + ops::Range, +}; + +use self::private::ValidLen; + +/// An opaque key allowing _O_(1) access to a field in a `Span`'s key-value +/// data. +/// +/// As keys are defined by the _metadata_ of a span, rather than by an +/// individual instance of a span, a key may be used to access the same field +/// across all instances of a given span with the same metadata. Thus, when a +/// subscriber observes a new span, it need only access a field by name _once_, +/// and use the key for that name for all other accesses. +#[derive(Debug)] +pub struct Field { + i: usize, + fields: FieldSet, +} + +/// An empty field. +/// +/// This can be used to indicate that the value of a field is not currently +/// present but will be recorded later. +/// +/// When a field's value is `Empty`. it will not be recorded. +#[derive(Debug, Eq, PartialEq)] +pub struct Empty; + +/// Describes the fields present on a span. +pub struct FieldSet { + /// The names of each field on the described span. + names: &'static [&'static str], + /// The callsite where the described span originates. + callsite: callsite::Identifier, +} + +/// A set of fields and values for a span. +pub struct ValueSet<'a> { + values: &'a [(&'a Field, Option<&'a (dyn Value + 'a)>)], + fields: &'a FieldSet, +} + +/// An iterator over a set of fields. +#[derive(Debug)] +pub struct Iter { + idxs: Range<usize>, + fields: FieldSet, +} + +/// Visits typed values. +/// +/// An instance of `Visit` ("a visitor") represents the logic necessary to +/// record field values of various types. When an implementor of [`Value`] is +/// [recorded], it calls the appropriate method on the provided visitor to +/// indicate the type that value should be recorded as. +/// +/// When a [`Subscriber`] implementation [records an `Event`] or a +/// [set of `Value`s added to a `Span`], it can pass an `&mut Visit` to the +/// `record` method on the provided [`ValueSet`] or [`Event`]. This visitor +/// will then be used to record all the field-value pairs present on that +/// `Event` or `ValueSet`. +/// +/// # Examples +/// +/// A simple visitor that writes to a string might be implemented like so: +/// ``` +/// # extern crate tracing_core as tracing; +/// use std::fmt::{self, Write}; +/// use tracing::field::{Value, Visit, Field}; +/// pub struct StringVisitor<'a> { +/// string: &'a mut String, +/// } +/// +/// impl<'a> Visit for StringVisitor<'a> { +/// fn record_debug(&mut self, field: &Field, value: &fmt::Debug) { +/// write!(self.string, "{} = {:?}; ", field.name(), value).unwrap(); +/// } +/// } +/// ``` +/// This visitor will format each recorded value using `fmt::Debug`, and +/// append the field name and formatted value to the provided string, +/// regardless of the type of the recorded value. When all the values have +/// been recorded, the `StringVisitor` may be dropped, allowing the string +/// to be printed or stored in some other data structure. +/// +/// The `Visit` trait provides default implementations for `record_i64`, +/// `record_u64`, `record_bool`, `record_str`, and `record_error`, which simply +/// forward the recorded value to `record_debug`. Thus, `record_debug` is the +/// only method which a `Visit` implementation *must* implement. However, +/// visitors may override the default implementations of these functions in +/// order to implement type-specific behavior. +/// +/// Additionally, when a visitor receives a value of a type it does not care +/// about, it is free to ignore those values completely. For example, a +/// visitor which only records numeric data might look like this: +/// +/// ``` +/// # extern crate tracing_core as tracing; +/// # use std::fmt::{self, Write}; +/// # use tracing::field::{Value, Visit, Field}; +/// pub struct SumVisitor { +/// sum: i64, +/// } +/// +/// impl Visit for SumVisitor { +/// fn record_i64(&mut self, _field: &Field, value: i64) { +/// self.sum += value; +/// } +/// +/// fn record_u64(&mut self, _field: &Field, value: u64) { +/// self.sum += value as i64; +/// } +/// +/// fn record_debug(&mut self, _field: &Field, _value: &fmt::Debug) { +/// // Do nothing +/// } +/// } +/// ``` +/// +/// This visitor (which is probably not particularly useful) keeps a running +/// sum of all the numeric values it records, and ignores all other values. A +/// more practical example of recording typed values is presented in +/// `examples/counters.rs`, which demonstrates a very simple metrics system +/// implemented using `tracing`. +/// +/// <div class="information"> +/// <div class="tooltip ignore" style="">ⓘ<span class="tooltiptext">Note</span></div> +/// </div> +/// <div class="example-wrap" style="display:inline-block"> +/// <pre class="ignore" style="white-space:normal;font:inherit;"> +/// <strong>Note</strong>: The <code>record_error</code> trait method is only +/// available when the Rust standard library is present, as it requires the +/// <code>std::error::Error</code> trait. +/// </pre></div> +/// +/// [`Value`]: trait.Value.html +/// [recorded]: trait.Value.html#method.record +/// [`Subscriber`]: ../subscriber/trait.Subscriber.html +/// [records an `Event`]: ../subscriber/trait.Subscriber.html#method.event +/// [set of `Value`s added to a `Span`]: ../subscriber/trait.Subscriber.html#method.record +/// [`Event`]: ../event/struct.Event.html +/// [`ValueSet`]: struct.ValueSet.html +pub trait Visit { + /// Visit a signed 64-bit integer value. + fn record_i64(&mut self, field: &Field, value: i64) { + self.record_debug(field, &value) + } + + /// Visit an unsigned 64-bit integer value. + fn record_u64(&mut self, field: &Field, value: u64) { + self.record_debug(field, &value) + } + + /// Visit a boolean value. + fn record_bool(&mut self, field: &Field, value: bool) { + self.record_debug(field, &value) + } + + /// Visit a string value. + fn record_str(&mut self, field: &Field, value: &str) { + self.record_debug(field, &value) + } + + /// Records a type implementing `Error`. + /// + /// <div class="information"> + /// <div class="tooltip ignore" style="">ⓘ<span class="tooltiptext">Note</span></div> + /// </div> + /// <div class="example-wrap" style="display:inline-block"> + /// <pre class="ignore" style="white-space:normal;font:inherit;"> + /// <strong>Note</strong>: This is only enabled when the Rust standard library is + /// present. + /// </pre> + #[cfg(feature = "std")] + #[cfg_attr(docsrs, doc(cfg(feature = "std")))] + fn record_error(&mut self, field: &Field, value: &(dyn std::error::Error + 'static)) { + self.record_debug(field, &format_args!("{}", value)) + } + + /// Visit a value implementing `fmt::Debug`. + fn record_debug(&mut self, field: &Field, value: &dyn fmt::Debug); +} + +/// A field value of an erased type. +/// +/// Implementors of `Value` may call the appropriate typed recording methods on +/// the [visitor] passed to their `record` method in order to indicate how +/// their data should be recorded. +/// +/// [visitor]: trait.Visit.html +pub trait Value: crate::sealed::Sealed { + /// Visits this value with the given `Visitor`. + fn record(&self, key: &Field, visitor: &mut dyn Visit); +} + +/// A `Value` which serializes using `fmt::Display`. +/// +/// Uses `record_debug` in the `Value` implementation to +/// avoid an unnecessary evaluation. +#[derive(Clone)] +pub struct DisplayValue<T: fmt::Display>(T); + +/// A `Value` which serializes as a string using `fmt::Debug`. +#[derive(Clone)] +pub struct DebugValue<T: fmt::Debug>(T); + +/// Wraps a type implementing `fmt::Display` as a `Value` that can be +/// recorded using its `Display` implementation. +pub fn display<T>(t: T) -> DisplayValue<T> +where + T: fmt::Display, +{ + DisplayValue(t) +} + +/// Wraps a type implementing `fmt::Debug` as a `Value` that can be +/// recorded using its `Debug` implementation. +pub fn debug<T>(t: T) -> DebugValue<T> +where + T: fmt::Debug, +{ + DebugValue(t) +} + +// ===== impl Visit ===== + +impl<'a, 'b> Visit for fmt::DebugStruct<'a, 'b> { + fn record_debug(&mut self, field: &Field, value: &dyn fmt::Debug) { + self.field(field.name(), value); + } +} + +impl<'a, 'b> Visit for fmt::DebugMap<'a, 'b> { + fn record_debug(&mut self, field: &Field, value: &dyn fmt::Debug) { + self.entry(&format_args!("{}", field), value); + } +} + +impl<F> Visit for F +where + F: FnMut(&Field, &dyn fmt::Debug), +{ + fn record_debug(&mut self, field: &Field, value: &dyn fmt::Debug) { + (self)(field, value) + } +} + +// ===== impl Value ===== + +macro_rules! impl_values { + ( $( $record:ident( $( $whatever:tt)+ ) ),+ ) => { + $( + impl_value!{ $record( $( $whatever )+ ) } + )+ + } +} + +macro_rules! ty_to_nonzero { + (u8) => { + NonZeroU8 + }; + (u16) => { + NonZeroU16 + }; + (u32) => { + NonZeroU32 + }; + (u64) => { + NonZeroU64 + }; + (u128) => { + NonZeroU128 + }; + (usize) => { + NonZeroUsize + }; + (i8) => { + NonZeroI8 + }; + (i16) => { + NonZeroI16 + }; + (i32) => { + NonZeroI32 + }; + (i64) => { + NonZeroI64 + }; + (i128) => { + NonZeroI128 + }; + (isize) => { + NonZeroIsize + }; +} + +macro_rules! impl_one_value { + (bool, $op:expr, $record:ident) => { + impl_one_value!(normal, bool, $op, $record); + }; + ($value_ty:tt, $op:expr, $record:ident) => { + impl_one_value!(normal, $value_ty, $op, $record); + impl_one_value!(nonzero, $value_ty, $op, $record); + }; + (normal, $value_ty:tt, $op:expr, $record:ident) => { + impl $crate::sealed::Sealed for $value_ty {} + impl $crate::field::Value for $value_ty { + fn record(&self, key: &$crate::field::Field, visitor: &mut dyn $crate::field::Visit) { + visitor.$record(key, $op(*self)) + } + } + }; + (nonzero, $value_ty:tt, $op:expr, $record:ident) => { + // This `use num::*;` is reported as unused because it gets emitted + // for every single invocation of this macro, so there are multiple `use`s. + // All but the first are useless indeed. + // We need this import because we can't write a path where one part is + // the `ty_to_nonzero!($value_ty)` invocation. + #[allow(clippy::useless_attribute, unused)] + use num::*; + impl $crate::sealed::Sealed for ty_to_nonzero!($value_ty) {} + impl $crate::field::Value for ty_to_nonzero!($value_ty) { + fn record(&self, key: &$crate::field::Field, visitor: &mut dyn $crate::field::Visit) { + visitor.$record(key, $op(self.get())) + } + } + }; +} + +macro_rules! impl_value { + ( $record:ident( $( $value_ty:tt ),+ ) ) => { + $( + impl_one_value!($value_ty, |this: $value_ty| this, $record); + )+ + }; + ( $record:ident( $( $value_ty:tt ),+ as $as_ty:ty) ) => { + $( + impl_one_value!($value_ty, |this: $value_ty| this as $as_ty, $record); + )+ + }; +} + +// ===== impl Value ===== + +impl_values! { + record_u64(u64), + record_u64(usize, u32, u16, u8 as u64), + record_i64(i64), + record_i64(isize, i32, i16, i8 as i64), + record_bool(bool) +} + +impl<T: crate::sealed::Sealed> crate::sealed::Sealed for Wrapping<T> {} +impl<T: crate::field::Value> crate::field::Value for Wrapping<T> { + fn record(&self, key: &crate::field::Field, visitor: &mut dyn crate::field::Visit) { + self.0.record(key, visitor) + } +} + +impl crate::sealed::Sealed for str {} + +impl Value for str { + fn record(&self, key: &Field, visitor: &mut dyn Visit) { + visitor.record_str(key, &self) + } +} + +#[cfg(feature = "std")] +impl crate::sealed::Sealed for dyn std::error::Error + 'static {} + +#[cfg(feature = "std")] +#[cfg_attr(docsrs, doc(cfg(feature = "std")))] +impl Value for dyn std::error::Error + 'static { + fn record(&self, key: &Field, visitor: &mut dyn Visit) { + visitor.record_error(key, self) + } +} + +impl<'a, T: ?Sized> crate::sealed::Sealed for &'a T where T: Value + crate::sealed::Sealed + 'a {} + +impl<'a, T: ?Sized> Value for &'a T +where + T: Value + 'a, +{ + fn record(&self, key: &Field, visitor: &mut dyn Visit) { + (*self).record(key, visitor) + } +} + +impl<'a> crate::sealed::Sealed for fmt::Arguments<'a> {} + +impl<'a> Value for fmt::Arguments<'a> { + fn record(&self, key: &Field, visitor: &mut dyn Visit) { + visitor.record_debug(key, self) + } +} + +impl fmt::Debug for dyn Value { + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + // We are only going to be recording the field value, so we don't + // actually care about the field name here. + struct NullCallsite; + static NULL_CALLSITE: NullCallsite = NullCallsite; + impl crate::callsite::Callsite for NullCallsite { + fn set_interest(&self, _: crate::subscriber::Interest) { + unreachable!("you somehow managed to register the null callsite?") + } + + fn metadata(&self) -> &crate::Metadata<'_> { + unreachable!("you somehow managed to access the null callsite?") + } + } + + static FIELD: Field = Field { + i: 0, + fields: FieldSet::new(&[], crate::identify_callsite!(&NULL_CALLSITE)), + }; + + let mut res = Ok(()); + self.record(&FIELD, &mut |_: &Field, val: &dyn fmt::Debug| { + res = write!(f, "{:?}", val); + }); + res + } +} + +impl fmt::Display for dyn Value { + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + fmt::Debug::fmt(self, f) + } +} + +// ===== impl DisplayValue ===== + +impl<T: fmt::Display> crate::sealed::Sealed for DisplayValue<T> {} + +impl<T> Value for DisplayValue<T> +where + T: fmt::Display, +{ + fn record(&self, key: &Field, visitor: &mut dyn Visit) { + visitor.record_debug(key, &format_args!("{}", self.0)) + } +} + +impl<T: fmt::Display> fmt::Debug for DisplayValue<T> { + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + write!(f, "{}", self.0) + } +} + +impl<T: fmt::Display> fmt::Display for DisplayValue<T> { + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + fmt::Display::fmt(&self.0, f) + } +} + +// ===== impl DebugValue ===== + +impl<T: fmt::Debug> crate::sealed::Sealed for DebugValue<T> {} + +impl<T: fmt::Debug> Value for DebugValue<T> +where + T: fmt::Debug, +{ + fn record(&self, key: &Field, visitor: &mut dyn Visit) { + visitor.record_debug(key, &self.0) + } +} + +impl<T: fmt::Debug> fmt::Debug for DebugValue<T> { + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + write!(f, "{:?}", self.0) + } +} + +impl crate::sealed::Sealed for Empty {} +impl Value for Empty { + #[inline] + fn record(&self, _: &Field, _: &mut dyn Visit) {} +} + +// ===== impl Field ===== + +impl Field { + /// Returns an [`Identifier`] that uniquely identifies the [`Callsite`] + /// which defines this field. + /// + /// [`Identifier`]: ../callsite/struct.Identifier.html + /// [`Callsite`]: ../callsite/trait.Callsite.html + #[inline] + pub fn callsite(&self) -> callsite::Identifier { + self.fields.callsite() + } + + /// Returns a string representing the name of the field. + pub fn name(&self) -> &'static str { + self.fields.names[self.i] + } +} + +impl fmt::Display for Field { + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + f.pad(self.name()) + } +} + +impl AsRef<str> for Field { + fn as_ref(&self) -> &str { + self.name() + } +} + +impl PartialEq for Field { + fn eq(&self, other: &Self) -> bool { + self.callsite() == other.callsite() && self.i == other.i + } +} + +impl Eq for Field {} + +impl Hash for Field { + fn hash<H>(&self, state: &mut H) + where + H: Hasher, + { + self.callsite().hash(state); + self.i.hash(state); + } +} + +impl Clone for Field { + fn clone(&self) -> Self { + Field { + i: self.i, + fields: FieldSet { + names: self.fields.names, + callsite: self.fields.callsite(), + }, + } + } +} + +// ===== impl FieldSet ===== + +impl FieldSet { + /// Constructs a new `FieldSet` with the given array of field names and callsite. + pub const fn new(names: &'static [&'static str], callsite: callsite::Identifier) -> Self { + Self { names, callsite } + } + + /// Returns an [`Identifier`] that uniquely identifies the [`Callsite`] + /// which defines this set of fields.. + /// + /// [`Identifier`]: ../callsite/struct.Identifier.html + /// [`Callsite`]: ../callsite/trait.Callsite.html + pub(crate) fn callsite(&self) -> callsite::Identifier { + callsite::Identifier(self.callsite.0) + } + + /// Returns the [`Field`] named `name`, or `None` if no such field exists. + /// + /// [`Field`]: ../struct.Field.html + pub fn field<Q: ?Sized>(&self, name: &Q) -> Option<Field> + where + Q: Borrow<str>, + { + let name = &name.borrow(); + self.names.iter().position(|f| f == name).map(|i| Field { + i, + fields: FieldSet { + names: self.names, + callsite: self.callsite(), + }, + }) + } + + /// Returns `true` if `self` contains the given `field`. + /// + /// <div class="information"> + /// <div class="tooltip ignore" style="">ⓘ<span class="tooltiptext">Note</span></div> + /// </div> + /// <div class="example-wrap" style="display:inline-block"> + /// <pre class="ignore" style="white-space:normal;font:inherit;"> + /// <strong>Note</strong>: If <code>field</code> shares a name with a field + /// in this <code>FieldSet</code>, but was created by a <code>FieldSet</code> + /// with a different callsite, this <code>FieldSet</code> does <em>not</em> + /// contain it. This is so that if two separate span callsites define a field + /// named "foo", the <code>Field</code> corresponding to "foo" for each + /// of those callsites are not equivalent. + /// </pre></div> + pub fn contains(&self, field: &Field) -> bool { + field.callsite() == self.callsite() && field.i <= self.len() + } + + /// Returns an iterator over the `Field`s in this `FieldSet`. + pub fn iter(&self) -> Iter { + let idxs = 0..self.len(); + Iter { + idxs, + fields: FieldSet { + names: self.names, + callsite: self.callsite(), + }, + } + } + + /// Returns a new `ValueSet` with entries for this `FieldSet`'s values. + /// + /// Note that a `ValueSet` may not be constructed with arrays of over 32 + /// elements. + #[doc(hidden)] + pub fn value_set<'v, V>(&'v self, values: &'v V) -> ValueSet<'v> + where + V: ValidLen<'v>, + { + ValueSet { + fields: self, + values: &values.borrow()[..], + } + } + + /// Returns the number of fields in this `FieldSet`. + #[inline] + pub fn len(&self) -> usize { + self.names.len() + } + + /// Returns whether or not this `FieldSet` has fields. + #[inline] + pub fn is_empty(&self) -> bool { + self.names.is_empty() + } +} + +impl<'a> IntoIterator for &'a FieldSet { + type IntoIter = Iter; + type Item = Field; + #[inline] + fn into_iter(self) -> Self::IntoIter { + self.iter() + } +} + +impl fmt::Debug for FieldSet { + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + f.debug_struct("FieldSet") + .field("names", &self.names) + .field("callsite", &self.callsite) + .finish() + } +} + +impl fmt::Display for FieldSet { + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + f.debug_set() + .entries(self.names.iter().map(display)) + .finish() + } +} + +// ===== impl Iter ===== + +impl Iterator for Iter { + type Item = Field; + fn next(&mut self) -> Option<Field> { + let i = self.idxs.next()?; + Some(Field { + i, + fields: FieldSet { + names: self.fields.names, + callsite: self.fields.callsite(), + }, + }) + } +} + +// ===== impl ValueSet ===== + +impl<'a> ValueSet<'a> { + /// Returns an [`Identifier`] that uniquely identifies the [`Callsite`] + /// defining the fields this `ValueSet` refers to. + /// + /// [`Identifier`]: ../callsite/struct.Identifier.html + /// [`Callsite`]: ../callsite/trait.Callsite.html + #[inline] + pub fn callsite(&self) -> callsite::Identifier { + self.fields.callsite() + } + + /// Visits all the fields in this `ValueSet` with the provided [visitor]. + /// + /// [visitor]: ../trait.Visit.html + pub(crate) fn record(&self, visitor: &mut dyn Visit) { + let my_callsite = self.callsite(); + for (field, value) in self.values { + if field.callsite() != my_callsite { + continue; + } + if let Some(value) = value { + value.record(field, visitor); + } + } + } + + /// Returns `true` if this `ValueSet` contains a value for the given `Field`. + pub(crate) fn contains(&self, field: &Field) -> bool { + field.callsite() == self.callsite() + && self + .values + .iter() + .any(|(key, val)| *key == field && val.is_some()) + } + + /// Returns true if this `ValueSet` contains _no_ values. + pub(crate) fn is_empty(&self) -> bool { + let my_callsite = self.callsite(); + self.values + .iter() + .all(|(key, val)| val.is_none() || key.callsite() != my_callsite) + } + + pub(crate) fn field_set(&self) -> &FieldSet { + self.fields + } +} + +impl<'a> fmt::Debug for ValueSet<'a> { + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + self.values + .iter() + .fold(&mut f.debug_struct("ValueSet"), |dbg, (key, v)| { + if let Some(val) = v { + val.record(key, dbg); + } + dbg + }) + .field("callsite", &self.callsite()) + .finish() + } +} + +impl<'a> fmt::Display for ValueSet<'a> { + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + self.values + .iter() + .fold(&mut f.debug_map(), |dbg, (key, v)| { + if let Some(val) = v { + val.record(key, dbg); + } + dbg + }) + .finish() + } +} + +// ===== impl ValidLen ===== + +mod private { + use super::*; + + /// Marker trait implemented by arrays which are of valid length to + /// construct a `ValueSet`. + /// + /// `ValueSet`s may only be constructed from arrays containing 32 or fewer + /// elements, to ensure the array is small enough to always be allocated on the + /// stack. This trait is only implemented by arrays of an appropriate length, + /// ensuring that the correct size arrays are used at compile-time. + pub trait ValidLen<'a>: Borrow<[(&'a Field, Option<&'a (dyn Value + 'a)>)]> {} +} + +macro_rules! impl_valid_len { + ( $( $len:tt ),+ ) => { + $( + impl<'a> private::ValidLen<'a> for + [(&'a Field, Option<&'a (dyn Value + 'a)>); $len] {} + )+ + } +} + +impl_valid_len! { + 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, + 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31, 32 +} + +#[cfg(test)] +mod test { + use super::*; + use crate::metadata::{Kind, Level, Metadata}; + use crate::stdlib::{borrow::ToOwned, string::String}; + + struct TestCallsite1; + static TEST_CALLSITE_1: TestCallsite1 = TestCallsite1; + static TEST_META_1: Metadata<'static> = metadata! { + name: "field_test1", + target: module_path!(), + level: Level::INFO, + fields: &["foo", "bar", "baz"], + callsite: &TEST_CALLSITE_1, + kind: Kind::SPAN, + }; + + impl crate::callsite::Callsite for TestCallsite1 { + fn set_interest(&self, _: crate::subscriber::Interest) { + unimplemented!() + } + + fn metadata(&self) -> &Metadata<'_> { + &TEST_META_1 + } + } + + struct TestCallsite2; + static TEST_CALLSITE_2: TestCallsite2 = TestCallsite2; + static TEST_META_2: Metadata<'static> = metadata! { + name: "field_test2", + target: module_path!(), + level: Level::INFO, + fields: &["foo", "bar", "baz"], + callsite: &TEST_CALLSITE_2, + kind: Kind::SPAN, + }; + + impl crate::callsite::Callsite for TestCallsite2 { + fn set_interest(&self, _: crate::subscriber::Interest) { + unimplemented!() + } + + fn metadata(&self) -> &Metadata<'_> { + &TEST_META_2 + } + } + + #[test] + fn value_set_with_no_values_is_empty() { + let fields = TEST_META_1.fields(); + let values = &[ + (&fields.field("foo").unwrap(), None), + (&fields.field("bar").unwrap(), None), + (&fields.field("baz").unwrap(), None), + ]; + let valueset = fields.value_set(values); + assert!(valueset.is_empty()); + } + + #[test] + fn empty_value_set_is_empty() { + let fields = TEST_META_1.fields(); + let valueset = fields.value_set(&[]); + assert!(valueset.is_empty()); + } + + #[test] + fn value_sets_with_fields_from_other_callsites_are_empty() { + let fields = TEST_META_1.fields(); + let values = &[ + (&fields.field("foo").unwrap(), Some(&1 as &dyn Value)), + (&fields.field("bar").unwrap(), Some(&2 as &dyn Value)), + (&fields.field("baz").unwrap(), Some(&3 as &dyn Value)), + ]; + let valueset = TEST_META_2.fields().value_set(values); + assert!(valueset.is_empty()) + } + + #[test] + fn sparse_value_sets_are_not_empty() { + let fields = TEST_META_1.fields(); + let values = &[ + (&fields.field("foo").unwrap(), None), + (&fields.field("bar").unwrap(), Some(&57 as &dyn Value)), + (&fields.field("baz").unwrap(), None), + ]; + let valueset = fields.value_set(values); + assert!(!valueset.is_empty()); + } + + #[test] + fn fields_from_other_callsets_are_skipped() { + let fields = TEST_META_1.fields(); + let values = &[ + (&fields.field("foo").unwrap(), None), + ( + &TEST_META_2.fields().field("bar").unwrap(), + Some(&57 as &dyn Value), + ), + (&fields.field("baz").unwrap(), None), + ]; + + struct MyVisitor; + impl Visit for MyVisitor { + fn record_debug(&mut self, field: &Field, _: &dyn (crate::stdlib::fmt::Debug)) { + assert_eq!(field.callsite(), TEST_META_1.callsite()) + } + } + let valueset = fields.value_set(values); + valueset.record(&mut MyVisitor); + } + + #[test] + fn empty_fields_are_skipped() { + let fields = TEST_META_1.fields(); + let values = &[ + (&fields.field("foo").unwrap(), Some(&Empty as &dyn Value)), + (&fields.field("bar").unwrap(), Some(&57 as &dyn Value)), + (&fields.field("baz").unwrap(), Some(&Empty as &dyn Value)), + ]; + + struct MyVisitor; + impl Visit for MyVisitor { + fn record_debug(&mut self, field: &Field, _: &dyn (crate::stdlib::fmt::Debug)) { + assert_eq!(field.name(), "bar") + } + } + let valueset = fields.value_set(values); + valueset.record(&mut MyVisitor); + } + + #[test] + fn record_debug_fn() { + let fields = TEST_META_1.fields(); + let values = &[ + (&fields.field("foo").unwrap(), Some(&1 as &dyn Value)), + (&fields.field("bar").unwrap(), Some(&2 as &dyn Value)), + (&fields.field("baz").unwrap(), Some(&3 as &dyn Value)), + ]; + let valueset = fields.value_set(values); + let mut result = String::new(); + valueset.record(&mut |_: &Field, value: &dyn fmt::Debug| { + use crate::stdlib::fmt::Write; + write!(&mut result, "{:?}", value).unwrap(); + }); + assert_eq!(result, "123".to_owned()); + } +} diff --git a/third_party/rust/tracing-core/src/lazy_static/LICENSE b/third_party/rust/tracing-core/src/lazy_static/LICENSE new file mode 100644 index 0000000000..28e478827c --- /dev/null +++ b/third_party/rust/tracing-core/src/lazy_static/LICENSE @@ -0,0 +1,26 @@ + +Copyright (c) 2010 The Rust Project Developers + +Permission is hereby granted, free of charge, to any +person obtaining a copy of this software and associated +documentation files (the "Software"), to deal in the +Software without restriction, including without +limitation the rights to use, copy, modify, merge, +publish, distribute, sublicense, and/or sell copies of +the Software, and to permit persons to whom the Software +is furnished to do so, subject to the following +conditions: + +The above copyright notice and this permission notice +shall be included in all copies or substantial portions +of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF +ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED +TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A +PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT +SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY +CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION +OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR +IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER +DEALINGS IN THE SOFTWARE. diff --git a/third_party/rust/tracing-core/src/lazy_static/core_lazy.rs b/third_party/rust/tracing-core/src/lazy_static/core_lazy.rs new file mode 100644 index 0000000000..c61d36202d --- /dev/null +++ b/third_party/rust/tracing-core/src/lazy_static/core_lazy.rs @@ -0,0 +1,30 @@ +// Copyright 2016 lazy-static.rs Developers +// +// Licensed under the Apache License, Version 2.0, <LICENSE-APACHE or +// http://apache.org/licenses/LICENSE-2.0> or the MIT license <LICENSE-MIT or +// http://opensource.org/licenses/MIT>, at your option. This file may not be +// copied, modified, or distributed except according to those terms. + +use crate::spin::Once; + +pub(crate) struct Lazy<T: Sync>(Once<T>); + +impl<T: Sync> Lazy<T> { + pub(crate) const INIT: Self = Lazy(Once::INIT); + + #[inline(always)] + pub(crate) fn get<F>(&'static self, builder: F) -> &T + where + F: FnOnce() -> T, + { + self.0.call_once(builder) + } +} + +#[macro_export] +#[doc(hidden)] +macro_rules! __lazy_static_create { + ($NAME:ident, $T:ty) => { + static $NAME: $crate::lazy_static::lazy::Lazy<$T> = $crate::lazy_static::lazy::Lazy::INIT; + }; +} diff --git a/third_party/rust/tracing-core/src/lazy_static/mod.rs b/third_party/rust/tracing-core/src/lazy_static/mod.rs new file mode 100644 index 0000000000..78f0ae722b --- /dev/null +++ b/third_party/rust/tracing-core/src/lazy_static/mod.rs @@ -0,0 +1,89 @@ +// Copyright 2016 lazy-static.rs Developers +// +// Licensed under the Apache License, Version 2.0, <LICENSE-APACHE or +// http://apache.org/licenses/LICENSE-2.0> or the MIT license <LICENSE-MIT or +// http://opensource.org/licenses/MIT>, at your option. This file may not be +// copied, modified, or distributed except according to those terms. + +/*! +A macro for declaring lazily evaluated statics. +Using this macro, it is possible to have `static`s that require code to be +executed at runtime in order to be initialized. +This includes anything requiring heap allocations, like vectors or hash maps, +as well as anything that requires function calls to be computed. +*/ + +#[path = "core_lazy.rs"] +pub(crate) mod lazy; + +#[doc(hidden)] +pub(crate) use core::ops::Deref as __Deref; + +#[macro_export] +#[doc(hidden)] +macro_rules! __lazy_static_internal { + // optional visibility restrictions are wrapped in `()` to allow for + // explicitly passing otherwise implicit information about private items + ($(#[$attr:meta])* ($($vis:tt)*) static ref $N:ident : $T:ty = $e:expr; $($t:tt)*) => { + $crate::__lazy_static_internal!(@MAKE TY, $(#[$attr])*, ($($vis)*), $N); + $crate::__lazy_static_internal!(@TAIL, $N : $T = $e); + $crate::lazy_static!($($t)*); + }; + (@TAIL, $N:ident : $T:ty = $e:expr) => { + impl $crate::lazy_static::__Deref for $N { + type Target = $T; + fn deref(&self) -> &$T { + #[inline(always)] + fn __static_ref_initialize() -> $T { $e } + + #[inline(always)] + fn __stability() -> &'static $T { + $crate::__lazy_static_create!(LAZY, $T); + LAZY.get(__static_ref_initialize) + } + __stability() + } + } + impl $crate::lazy_static::LazyStatic for $N { + fn initialize(lazy: &Self) { + let _ = &**lazy; + } + } + }; + // `vis` is wrapped in `()` to prevent parsing ambiguity + (@MAKE TY, $(#[$attr:meta])*, ($($vis:tt)*), $N:ident) => { + #[allow(missing_copy_implementations)] + #[allow(non_camel_case_types)] + #[allow(dead_code)] + $(#[$attr])* + $($vis)* struct $N {__private_field: ()} + #[doc(hidden)] + $($vis)* static $N: $N = $N {__private_field: ()}; + }; + () => () +} + +#[macro_export] +#[doc(hidden)] +macro_rules! lazy_static { + ($(#[$attr:meta])* static ref $N:ident : $T:ty = $e:expr; $($t:tt)*) => { + // use `()` to explicitly forward the information about private items + $crate::__lazy_static_internal!($(#[$attr])* () static ref $N : $T = $e; $($t)*); + }; + ($(#[$attr:meta])* pub static ref $N:ident : $T:ty = $e:expr; $($t:tt)*) => { + $crate::__lazy_static_internal!($(#[$attr])* (pub) static ref $N : $T = $e; $($t)*); + }; + ($(#[$attr:meta])* pub ($($vis:tt)+) static ref $N:ident : $T:ty = $e:expr; $($t:tt)*) => { + $crate::__lazy_static_internal!($(#[$attr])* (pub ($($vis)+)) static ref $N : $T = $e; $($t)*); + }; + () => () +} + +/// Support trait for enabling a few common operation on lazy static values. +/// +/// This is implemented by each defined lazy static, and +/// used by the free functions in this crate. +pub(crate) trait LazyStatic { + #[doc(hidden)] + fn initialize(lazy: &Self); +} diff --git a/third_party/rust/tracing-core/src/lib.rs b/third_party/rust/tracing-core/src/lib.rs new file mode 100644 index 0000000000..0d266b8e9c --- /dev/null +++ b/third_party/rust/tracing-core/src/lib.rs @@ -0,0 +1,279 @@ +//! Core primitives for `tracing`. +//! +//! [`tracing`] is a framework for instrumenting Rust programs to collect +//! structured, event-based diagnostic information. This crate defines the core +//! primitives of `tracing`. +//! +//! This crate provides: +//! +//! * [`span::Id`] identifies a span within the execution of a program. +//! +//! * [`Event`] represents a single event within a trace. +//! +//! * [`Subscriber`], the trait implemented to collect trace data. +//! +//! * [`Metadata`] and [`Callsite`] provide information describing spans and +//! `Event`s. +//! +//! * [`Field`], [`FieldSet`], [`Value`], and [`ValueSet`] represent the +//! structured data attached to a span. +//! +//! * [`Dispatch`] allows spans and events to be dispatched to `Subscriber`s. +//! +//! In addition, it defines the global callsite registry and per-thread current +//! dispatcher which other components of the tracing system rely on. +//! +//! *Compiler support: [requires `rustc` 1.40+][msrv]* +//! +//! [msrv]: #supported-rust-versions +//! +//! ## Usage +//! +//! Application authors will typically not use this crate directly. Instead, +//! they will use the [`tracing`] crate, which provides a much more +//! fully-featured API. However, this crate's API will change very infrequently, +//! so it may be used when dependencies must be very stable. +//! +//! `Subscriber` implementations may depend on `tracing-core` rather than +//! `tracing`, as the additional APIs provided by `tracing` are primarily useful +//! for instrumenting libraries and applications, and are generally not +//! necessary for `Subscriber` implementations. +//! +//! The [`tokio-rs/tracing`] repository contains less stable crates designed to +//! be used with the `tracing` ecosystem. It includes a collection of +//! `Subscriber` implementations, as well as utility and adapter crates. +//! +//! ### Crate Feature Flags +//! +//! The following crate feature flags are available: +//! +//! * `std`: Depend on the Rust standard library (enabled by default). +//! +//! `no_std` users may disable this feature with `default-features = false`: +//! +//! ```toml +//! [dependencies] +//! tracing-core = { version = "0.1.17", default-features = false } +//! ``` +//! +//! **Note**:`tracing-core`'s `no_std` support requires `liballoc`. +//! +//! ## Supported Rust Versions +//! +//! Tracing is built against the latest stable release. The minimum supported +//! version is 1.40. The current Tracing version is not guaranteed to build on +//! Rust versions earlier than the minimum supported version. +//! +//! Tracing follows the same compiler support policies as the rest of the Tokio +//! project. The current stable Rust compiler and the three most recent minor +//! versions before it will always be supported. For example, if the current +//! stable compiler version is 1.45, the minimum supported version will not be +//! increased past 1.42, three minor versions prior. Increasing the minimum +//! supported compiler version is not considered a semver breaking change as +//! long as doing so complies with this policy. +//! +//! +//! [`span::Id`]: span/struct.Id.html +//! [`Event`]: event/struct.Event.html +//! [`Subscriber`]: subscriber/trait.Subscriber.html +//! [`Metadata`]: metadata/struct.Metadata.html +//! [`Callsite`]: callsite/trait.Callsite.html +//! [`Field`]: field/struct.Field.html +//! [`FieldSet`]: field/struct.FieldSet.html +//! [`Value`]: field/trait.Value.html +//! [`ValueSet`]: field/struct.ValueSet.html +//! [`Dispatch`]: dispatcher/struct.Dispatch.html +//! [`tokio-rs/tracing`]: https://github.com/tokio-rs/tracing +//! [`tracing`]: https://crates.io/crates/tracing +#![doc(html_root_url = "https://docs.rs/tracing-core/0.1.17")] +#![doc( + html_logo_url = "https://raw.githubusercontent.com/tokio-rs/tracing/master/assets/logo-type.png", + issue_tracker_base_url = "https://github.com/tokio-rs/tracing/issues/" +)] +#![cfg_attr(not(feature = "std"), no_std)] +#![cfg_attr(docsrs, feature(doc_cfg), deny(broken_intra_doc_links))] +#![warn( + missing_debug_implementations, + missing_docs, + rust_2018_idioms, + unreachable_pub, + bad_style, + const_err, + dead_code, + improper_ctypes, + non_shorthand_field_patterns, + no_mangle_generic_items, + overflowing_literals, + path_statements, + patterns_in_fns_without_body, + private_in_public, + unconditional_recursion, + unused, + unused_allocation, + unused_comparisons, + unused_parens, + while_true +)] +#[cfg(not(feature = "std"))] +extern crate alloc; + +/// Statically constructs an [`Identifier`] for the provided [`Callsite`]. +/// +/// This may be used in contexts, such as static initializers, where the +/// [`Callsite::id`] function is not currently usable. +/// +/// For example: +/// ```rust +/// # #[macro_use] +/// # extern crate tracing_core; +/// use tracing_core::callsite; +/// # use tracing_core::{Metadata, subscriber::Interest}; +/// # fn main() { +/// pub struct MyCallsite { +/// // ... +/// } +/// impl callsite::Callsite for MyCallsite { +/// # fn set_interest(&self, _: Interest) { unimplemented!() } +/// # fn metadata(&self) -> &Metadata { unimplemented!() } +/// // ... +/// } +/// +/// static CALLSITE: MyCallsite = MyCallsite { +/// // ... +/// }; +/// +/// static CALLSITE_ID: callsite::Identifier = identify_callsite!(&CALLSITE); +/// # } +/// ``` +/// +/// [`Identifier`]: callsite/struct.Identifier.html +/// [`Callsite`]: callsite/trait.Callsite.html +/// [`Callsite::id`]: callsite/trait.Callsite.html#method.id +#[macro_export] +macro_rules! identify_callsite { + ($callsite:expr) => { + $crate::callsite::Identifier($callsite) + }; +} + +/// Statically constructs new span [metadata]. +/// +/// /// For example: +/// ```rust +/// # #[macro_use] +/// # extern crate tracing_core; +/// # use tracing_core::{callsite::Callsite, subscriber::Interest}; +/// use tracing_core::metadata::{Kind, Level, Metadata}; +/// # fn main() { +/// # pub struct MyCallsite { } +/// # impl Callsite for MyCallsite { +/// # fn set_interest(&self, _: Interest) { unimplemented!() } +/// # fn metadata(&self) -> &Metadata { unimplemented!() } +/// # } +/// # +/// static FOO_CALLSITE: MyCallsite = MyCallsite { +/// // ... +/// }; +/// +/// static FOO_METADATA: Metadata = metadata!{ +/// name: "foo", +/// target: module_path!(), +/// level: Level::DEBUG, +/// fields: &["bar", "baz"], +/// callsite: &FOO_CALLSITE, +/// kind: Kind::SPAN, +/// }; +/// # } +/// ``` +/// +/// [metadata]: metadata/struct.Metadata.html +/// [`Metadata::new`]: metadata/struct.Metadata.html#method.new +#[macro_export] +macro_rules! metadata { + ( + name: $name:expr, + target: $target:expr, + level: $level:expr, + fields: $fields:expr, + callsite: $callsite:expr, + kind: $kind:expr + ) => { + $crate::metadata! { + name: $name, + target: $target, + level: $level, + fields: $fields, + callsite: $callsite, + kind: $kind, + } + }; + ( + name: $name:expr, + target: $target:expr, + level: $level:expr, + fields: $fields:expr, + callsite: $callsite:expr, + kind: $kind:expr, + ) => { + $crate::metadata::Metadata::new( + $name, + $target, + $level, + Some(file!()), + Some(line!()), + Some(module_path!()), + $crate::field::FieldSet::new($fields, $crate::identify_callsite!($callsite)), + $kind, + ) + }; +} + +// std uses lazy_static from crates.io +#[cfg(feature = "std")] +#[macro_use] +extern crate lazy_static; + +// no_std uses vendored version of lazy_static 1.4.0 (4216696) with spin +// This can conflict when included in a project already using std lazy_static +// Remove this module when cargo enables specifying dependencies for no_std +#[cfg(not(feature = "std"))] +#[macro_use] +mod lazy_static; + +// Trimmed-down vendored version of spin 0.5.2 (0387621) +// Dependency of no_std lazy_static, not required in a std build +#[cfg(not(feature = "std"))] +pub(crate) mod spin; + +#[cfg(not(feature = "std"))] +#[doc(hidden)] +pub type Once = self::spin::Once<()>; + +#[cfg(feature = "std")] +pub use stdlib::sync::Once; + +pub mod callsite; +pub mod dispatcher; +pub mod event; +pub mod field; +pub mod metadata; +mod parent; +pub mod span; +pub(crate) mod stdlib; +pub mod subscriber; + +#[doc(inline)] +pub use self::{ + callsite::Callsite, + dispatcher::Dispatch, + event::Event, + field::Field, + metadata::{Level, LevelFilter, Metadata}, + subscriber::Subscriber, +}; + +pub use self::{metadata::Kind, subscriber::Interest}; + +mod sealed { + pub trait Sealed {} +} diff --git a/third_party/rust/tracing-core/src/metadata.rs b/third_party/rust/tracing-core/src/metadata.rs new file mode 100644 index 0000000000..fe67bcfcd8 --- /dev/null +++ b/third_party/rust/tracing-core/src/metadata.rs @@ -0,0 +1,872 @@ +//! Metadata describing trace data. +use super::{callsite, field}; +use crate::stdlib::{ + cmp, fmt, + str::FromStr, + sync::atomic::{AtomicUsize, Ordering}, +}; + +/// Metadata describing a [span] or [event]. +/// +/// All spans and events have the following metadata: +/// - A [name], represented as a static string. +/// - A [target], a string that categorizes part of the system where the span +/// or event occurred. The `tracing` macros default to using the module +/// path where the span or event originated as the target, but it may be +/// overridden. +/// - A [verbosity level]. +/// - The names of the [fields] defined by the span or event. +/// - Whether the metadata corresponds to a span or event. +/// +/// In addition, the following optional metadata describing the source code +/// location where the span or event originated _may_ be provided: +/// - The [file name] +/// - The [line number] +/// - The [module path] +/// +/// Metadata is used by [`Subscriber`]s when filtering spans and events, and it +/// may also be used as part of their data payload. +/// +/// When created by the `event!` or `span!` macro, the metadata describing a +/// particular event or span is constructed statically and exists as a single +/// static instance. Thus, the overhead of creating the metadata is +/// _significantly_ lower than that of creating the actual span. Therefore, +/// filtering is based on metadata, rather than on the constructed span. +/// +/// <div class="information"> +/// <div class="tooltip ignore" style="">ⓘ<span class="tooltiptext">Note</span></div> +/// </div> +/// <div class="example-wrap" style="display:inline-block"> +/// <pre class="ignore" style="white-space:normal;font:inherit;"> +/// <strong>Note</strong>: Although instances of <code>Metadata</code> cannot +/// be compared directly, they provide a method <a href="struct.Metadata.html#method.id"> +/// <code>id</code></a>, returning an opaque <a href="../callsite/struct.Identifier.html"> +/// callsite identifier</a> which uniquely identifies the callsite where the metadata +/// originated. This can be used to determine if two <code>Metadata</code> correspond to +/// the same callsite. +/// </pre></div> +/// +/// [span]: ../span/index.html +/// [event]: ../event/index.html +/// [name]: #method.name +/// [target]: #method.target +/// [fields]: #method.fields +/// [verbosity level]: #method.level +/// [file name]: #method.file +/// [line number]: #method.line +/// [module path]: #method.module +/// [`Subscriber`]: ../subscriber/trait.Subscriber.html +/// [`id`]: struct.Metadata.html#method.id +/// [callsite identifier]: ../callsite/struct.Identifier.html +pub struct Metadata<'a> { + /// The name of the span described by this metadata. + name: &'static str, + + /// The part of the system that the span that this metadata describes + /// occurred in. + target: &'a str, + + /// The level of verbosity of the described span. + level: Level, + + /// The name of the Rust module where the span occurred, or `None` if this + /// could not be determined. + module_path: Option<&'a str>, + + /// The name of the source code file where the span occurred, or `None` if + /// this could not be determined. + file: Option<&'a str>, + + /// The line number in the source code file where the span occurred, or + /// `None` if this could not be determined. + line: Option<u32>, + + /// The names of the key-value fields attached to the described span or + /// event. + fields: field::FieldSet, + + /// The kind of the callsite. + kind: Kind, +} + +/// Indicates whether the callsite is a span or event. +#[derive(Clone, Debug, Eq, PartialEq)] +pub struct Kind(KindInner); + +/// Describes the level of verbosity of a span or event. +#[derive(Copy, Clone, Debug, PartialEq, Eq)] +pub struct Level(LevelInner); + +/// A filter comparable to a verbosity `Level`. +/// +/// If a `Level` is considered less than a `LevelFilter`, it should be +/// considered disabled; if greater than or equal to the `LevelFilter`, that +/// level is enabled. +/// +/// Note that this is essentially identical to the `Level` type, but with the +/// addition of an `OFF` level that completely disables all trace +/// instrumentation. +#[repr(transparent)] +#[derive(Copy, Clone, Eq, PartialEq)] +pub struct LevelFilter(Option<Level>); + +/// Indicates that a string could not be parsed to a valid level. +#[derive(Clone, Debug)] +pub struct ParseLevelFilterError(()); + +static MAX_LEVEL: AtomicUsize = AtomicUsize::new(LevelFilter::OFF_USIZE); + +// ===== impl Metadata ===== + +impl<'a> Metadata<'a> { + /// Construct new metadata for a span or event, with a name, target, level, field + /// names, and optional source code location. + pub const fn new( + name: &'static str, + target: &'a str, + level: Level, + file: Option<&'a str>, + line: Option<u32>, + module_path: Option<&'a str>, + fields: field::FieldSet, + kind: Kind, + ) -> Self { + Metadata { + name, + target, + level, + module_path, + file, + line, + fields, + kind, + } + } + + /// Returns the names of the fields on the described span or event. + pub fn fields(&self) -> &field::FieldSet { + &self.fields + } + + /// Returns the level of verbosity of the described span or event. + pub fn level(&self) -> &Level { + &self.level + } + + /// Returns the name of the span. + pub fn name(&self) -> &'static str { + self.name + } + + /// Returns a string describing the part of the system where the span or + /// event that this metadata describes occurred. + /// + /// Typically, this is the module path, but alternate targets may be set + /// when spans or events are constructed. + pub fn target(&self) -> &'a str { + self.target + } + + /// Returns the path to the Rust module where the span occurred, or + /// `None` if the module path is unknown. + pub fn module_path(&self) -> Option<&'a str> { + self.module_path + } + + /// Returns the name of the source code file where the span + /// occurred, or `None` if the file is unknown + pub fn file(&self) -> Option<&'a str> { + self.file + } + + /// Returns the line number in the source code file where the span + /// occurred, or `None` if the line number is unknown. + pub fn line(&self) -> Option<u32> { + self.line + } + + /// Returns an opaque `Identifier` that uniquely identifies the callsite + /// this `Metadata` originated from. + #[inline] + pub fn callsite(&self) -> callsite::Identifier { + self.fields.callsite() + } + + /// Returns true if the callsite kind is `Event`. + pub fn is_event(&self) -> bool { + self.kind.is_event() + } + + /// Return true if the callsite kind is `Span`. + pub fn is_span(&self) -> bool { + self.kind.is_span() + } +} + +impl<'a> fmt::Debug for Metadata<'a> { + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + let mut meta = f.debug_struct("Metadata"); + meta.field("name", &self.name) + .field("target", &self.target) + .field("level", &self.level); + + if let Some(path) = self.module_path() { + meta.field("module_path", &path); + } + + match (self.file(), self.line()) { + (Some(file), Some(line)) => { + meta.field("location", &format_args!("{}:{}", file, line)); + } + (Some(file), None) => { + meta.field("file", &format_args!("{}", file)); + } + + // Note: a line num with no file is a kind of weird case that _probably_ never occurs... + (None, Some(line)) => { + meta.field("line", &line); + } + (None, None) => {} + }; + + meta.field("fields", &format_args!("{}", self.fields)) + .field("callsite", &self.callsite()) + .field("kind", &self.kind) + .finish() + } +} + +#[derive(Clone, Debug, Eq, PartialEq)] +enum KindInner { + Event, + Span, +} + +impl Kind { + /// `Event` callsite + pub const EVENT: Kind = Kind(KindInner::Event); + + /// `Span` callsite + pub const SPAN: Kind = Kind(KindInner::Span); + + /// Return true if the callsite kind is `Span` + pub fn is_span(&self) -> bool { + match self { + Kind(KindInner::Span) => true, + _ => false, + } + } + + /// Return true if the callsite kind is `Event` + pub fn is_event(&self) -> bool { + match self { + Kind(KindInner::Event) => true, + _ => false, + } + } +} + +// ===== impl Level ===== + +impl Level { + /// The "error" level. + /// + /// Designates very serious errors. + pub const ERROR: Level = Level(LevelInner::Error); + /// The "warn" level. + /// + /// Designates hazardous situations. + pub const WARN: Level = Level(LevelInner::Warn); + /// The "info" level. + /// + /// Designates useful information. + pub const INFO: Level = Level(LevelInner::Info); + /// The "debug" level. + /// + /// Designates lower priority information. + pub const DEBUG: Level = Level(LevelInner::Debug); + /// The "trace" level. + /// + /// Designates very low priority, often extremely verbose, information. + pub const TRACE: Level = Level(LevelInner::Trace); +} + +impl fmt::Display for Level { + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + match *self { + Level::TRACE => f.pad("TRACE"), + Level::DEBUG => f.pad("DEBUG"), + Level::INFO => f.pad("INFO"), + Level::WARN => f.pad("WARN"), + Level::ERROR => f.pad("ERROR"), + } + } +} + +#[cfg(feature = "std")] +#[cfg_attr(docsrs, doc(cfg(feature = "std")))] +impl crate::stdlib::error::Error for ParseLevelError {} + +impl FromStr for Level { + type Err = ParseLevelError; + fn from_str(s: &str) -> Result<Self, ParseLevelError> { + s.parse::<usize>() + .map_err(|_| ParseLevelError { _p: () }) + .and_then(|num| match num { + 1 => Ok(Level::ERROR), + 2 => Ok(Level::WARN), + 3 => Ok(Level::INFO), + 4 => Ok(Level::DEBUG), + 5 => Ok(Level::TRACE), + _ => Err(ParseLevelError { _p: () }), + }) + .or_else(|_| match s { + s if s.eq_ignore_ascii_case("error") => Ok(Level::ERROR), + s if s.eq_ignore_ascii_case("warn") => Ok(Level::WARN), + s if s.eq_ignore_ascii_case("info") => Ok(Level::INFO), + s if s.eq_ignore_ascii_case("debug") => Ok(Level::DEBUG), + s if s.eq_ignore_ascii_case("trace") => Ok(Level::TRACE), + _ => Err(ParseLevelError { _p: () }), + }) + } +} + +#[repr(usize)] +#[derive(Copy, Clone, Debug, Hash, Eq, PartialEq)] +enum LevelInner { + /// The "trace" level. + /// + /// Designates very low priority, often extremely verbose, information. + Trace = 0, + /// The "debug" level. + /// + /// Designates lower priority information. + Debug = 1, + /// The "info" level. + /// + /// Designates useful information. + Info = 2, + /// The "warn" level. + /// + /// Designates hazardous situations. + Warn = 3, + /// The "error" level. + /// + /// Designates very serious errors. + Error = 4, +} + +// === impl LevelFilter === + +impl From<Level> for LevelFilter { + #[inline] + fn from(level: Level) -> Self { + Self::from_level(level) + } +} + +impl From<Option<Level>> for LevelFilter { + #[inline] + fn from(level: Option<Level>) -> Self { + Self(level) + } +} + +impl Into<Option<Level>> for LevelFilter { + #[inline] + fn into(self) -> Option<Level> { + self.into_level() + } +} + +impl LevelFilter { + /// The "off" level. + /// + /// Designates that trace instrumentation should be completely disabled. + pub const OFF: LevelFilter = LevelFilter(None); + /// The "error" level. + /// + /// Designates very serious errors. + pub const ERROR: LevelFilter = LevelFilter::from_level(Level::ERROR); + /// The "warn" level. + /// + /// Designates hazardous situations. + pub const WARN: LevelFilter = LevelFilter::from_level(Level::WARN); + /// The "info" level. + /// + /// Designates useful information. + pub const INFO: LevelFilter = LevelFilter::from_level(Level::INFO); + /// The "debug" level. + /// + /// Designates lower priority information. + pub const DEBUG: LevelFilter = LevelFilter::from_level(Level::DEBUG); + /// The "trace" level. + /// + /// Designates very low priority, often extremely verbose, information. + pub const TRACE: LevelFilter = LevelFilter(Some(Level::TRACE)); + + /// Returns a `LevelFilter` that enables spans and events with verbosity up + /// to and including `level`. + pub const fn from_level(level: Level) -> Self { + Self(Some(level)) + } + + /// Returns the most verbose [`Level`] that this filter accepts, or `None` + /// if it is [`OFF`]. + /// + /// [`Level`]: ../struct.Level.html + /// [`OFF`]: #associatedconstant.OFF + pub const fn into_level(self) -> Option<Level> { + self.0 + } + + // These consts are necessary because `as` casts are not allowed as + // match patterns. + const ERROR_USIZE: usize = LevelInner::Error as usize; + const WARN_USIZE: usize = LevelInner::Warn as usize; + const INFO_USIZE: usize = LevelInner::Info as usize; + const DEBUG_USIZE: usize = LevelInner::Debug as usize; + const TRACE_USIZE: usize = LevelInner::Trace as usize; + // Using the value of the last variant + 1 ensures that we match the value + // for `Option::None` as selected by the niche optimization for + // `LevelFilter`. If this is the case, converting a `usize` value into a + // `LevelFilter` (in `LevelFilter::current`) will be an identity conversion, + // rather than generating a lookup table. + const OFF_USIZE: usize = LevelInner::Error as usize + 1; + + /// Returns a `LevelFilter` that matches the most verbose [`Level`] that any + /// currently active [`Subscriber`] will enable. + /// + /// User code should treat this as a *hint*. If a given span or event has a + /// level *higher* than the returned `LevelFilter`, it will not be enabled. + /// However, if the level is less than or equal to this value, the span or + /// event is *not* guaranteed to be enabled; the subscriber will still + /// filter each callsite individually. + /// + /// Therefore, comparing a given span or event's level to the returned + /// `LevelFilter` **can** be used for determining if something is + /// *disabled*, but **should not** be used for determining if something is + /// *enabled*.` + /// + /// [`Level`]: ../struct.Level.html + /// [`Subscriber`]: ../../trait.Subscriber.html + #[inline(always)] + pub fn current() -> Self { + match MAX_LEVEL.load(Ordering::Relaxed) { + Self::ERROR_USIZE => Self::ERROR, + Self::WARN_USIZE => Self::WARN, + Self::INFO_USIZE => Self::INFO, + Self::DEBUG_USIZE => Self::DEBUG, + Self::TRACE_USIZE => Self::TRACE, + Self::OFF_USIZE => Self::OFF, + #[cfg(debug_assertions)] + unknown => unreachable!( + "/!\\ `LevelFilter` representation seems to have changed! /!\\ \n\ + This is a bug (and it's pretty bad). Please contact the `tracing` \ + maintainers. Thank you and I'm sorry.\n \ + The offending repr was: {:?}", + unknown, + ), + #[cfg(not(debug_assertions))] + _ => unsafe { + // Using `unreachable_unchecked` here (rather than + // `unreachable!()`) is necessary to ensure that rustc generates + // an identity conversion from integer -> discriminant, rather + // than generating a lookup table. We want to ensure this + // function is a single `mov` instruction (on x86) if at all + // possible, because it is called *every* time a span/event + // callsite is hit; and it is (potentially) the only code in the + // hottest path for skipping a majority of callsites when level + // filtering is in use. + // + // safety: This branch is only truly unreachable if we guarantee + // that no values other than the possible enum discriminants + // will *ever* be present. The `AtomicUsize` is initialized to + // the `OFF` value. It is only set by the `set_max` function, + // which takes a `LevelFilter` as a parameter. This restricts + // the inputs to `set_max` to the set of valid discriminants. + // Therefore, **as long as `MAX_VALUE` is only ever set by + // `set_max`**, this is safe. + crate::stdlib::hint::unreachable_unchecked() + }, + } + } + + pub(crate) fn set_max(LevelFilter(level): LevelFilter) { + let val = match level { + Some(Level(level)) => level as usize, + None => Self::OFF_USIZE, + }; + + // using an AcqRel swap ensures an ordered relationship of writes to the + // max level. + MAX_LEVEL.swap(val, Ordering::AcqRel); + } +} + +impl fmt::Display for LevelFilter { + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + match *self { + LevelFilter::OFF => f.pad("off"), + LevelFilter::ERROR => f.pad("error"), + LevelFilter::WARN => f.pad("warn"), + LevelFilter::INFO => f.pad("info"), + LevelFilter::DEBUG => f.pad("debug"), + LevelFilter::TRACE => f.pad("trace"), + } + } +} + +impl fmt::Debug for LevelFilter { + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + match *self { + LevelFilter::OFF => f.pad("LevelFilter::OFF"), + LevelFilter::ERROR => f.pad("LevelFilter::ERROR"), + LevelFilter::WARN => f.pad("LevelFilter::WARN"), + LevelFilter::INFO => f.pad("LevelFilter::INFO"), + LevelFilter::DEBUG => f.pad("LevelFilter::DEBUG"), + LevelFilter::TRACE => f.pad("LevelFilter::TRACE"), + } + } +} + +impl FromStr for LevelFilter { + type Err = ParseLevelFilterError; + fn from_str(from: &str) -> Result<Self, Self::Err> { + from.parse::<usize>() + .ok() + .and_then(|num| match num { + 0 => Some(LevelFilter::OFF), + 1 => Some(LevelFilter::ERROR), + 2 => Some(LevelFilter::WARN), + 3 => Some(LevelFilter::INFO), + 4 => Some(LevelFilter::DEBUG), + 5 => Some(LevelFilter::TRACE), + _ => None, + }) + .or_else(|| match from { + "" => Some(LevelFilter::ERROR), + s if s.eq_ignore_ascii_case("error") => Some(LevelFilter::ERROR), + s if s.eq_ignore_ascii_case("warn") => Some(LevelFilter::WARN), + s if s.eq_ignore_ascii_case("info") => Some(LevelFilter::INFO), + s if s.eq_ignore_ascii_case("debug") => Some(LevelFilter::DEBUG), + s if s.eq_ignore_ascii_case("trace") => Some(LevelFilter::TRACE), + s if s.eq_ignore_ascii_case("off") => Some(LevelFilter::OFF), + _ => None, + }) + .ok_or_else(|| ParseLevelFilterError(())) + } +} + +/// Returned if parsing a `Level` fails. +#[derive(Debug)] +pub struct ParseLevelError { + _p: (), +} + +impl fmt::Display for ParseLevelError { + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + f.pad( + "error parsing level: expected one of \"error\", \"warn\", \ + \"info\", \"debug\", \"trace\", or a number 1-5", + ) + } +} + +impl fmt::Display for ParseLevelFilterError { + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + f.pad( + "error parsing level filter: expected one of \"off\", \"error\", \ + \"warn\", \"info\", \"debug\", \"trace\", or a number 0-5", + ) + } +} + +#[cfg(feature = "std")] +impl std::error::Error for ParseLevelFilterError {} + +// ==== Level and LevelFilter comparisons ==== + +// /!\ BIG, IMPORTANT WARNING /!\ +// Do NOT mess with these implementations! They are hand-written for a reason! +// +// Since comparing `Level`s and `LevelFilter`s happens in a *very* hot path +// (potentially, every time a span or event macro is hit, regardless of whether +// or not is enabled), we *need* to ensure that these comparisons are as fast as +// possible. Therefore, we have some requirements: +// +// 1. We want to do our best to ensure that rustc will generate integer-integer +// comparisons wherever possible. +// +// The derived `Ord`/`PartialOrd` impls for `LevelFilter` will not do this, +// because `LevelFilter`s are represented by `Option<Level>`, rather than as +// a separate `#[repr(usize)]` enum. This was (unfortunately) necessary for +// backwards-compatibility reasons, as the `tracing` crate's original +// version of `LevelFilter` defined `const fn` conversions between `Level`s +// and `LevelFilter`, so we're stuck with the `Option<Level>` repr. +// Therefore, we need hand-written `PartialOrd` impls that cast both sides of +// the comparison to `usize`s, to force the compiler to generate integer +// compares. +// +// 2. The hottest `Level`/`LevelFilter` comparison, the one that happens every +// time a callsite is hit, occurs *within the `tracing` crate's macros*. +// This means that the comparison is happening *inside* a crate that +// *depends* on `tracing-core`, not in `tracing-core` itself. The compiler +// will only inline function calls across crate boundaries if the called +// function is annotated with an `#[inline]` attribute, and we *definitely* +// want the comparison functions to be inlined: as previously mentioned, they +// should compile down to a single integer comparison on release builds, and +// it seems really sad to push an entire stack frame to call a function +// consisting of one `cmp` instruction! +// +// Therefore, we need to ensure that all the comparison methods have +// `#[inline]` or `#[inline(always)]` attributes. It's not sufficient to just +// add the attribute to `partial_cmp` in a manual implementation of the +// trait, since it's the comparison operators (`lt`, `le`, `gt`, and `ge`) +// that will actually be *used*, and the default implementation of *those* +// methods, which calls `partial_cmp`, does not have an inline annotation. +// +// 3. We need the comparisons to be inverted. The discriminants for the +// `LevelInner` enum are assigned in "backwards" order, with `TRACE` having +// the *lowest* value. However, we want `TRACE` to compare greater-than all +// other levels. +// +// Why are the numeric values inverted? In order to ensure that `LevelFilter` +// (which, as previously mentioned, *has* to be internally represented by an +// `Option<Level>`) compiles down to a single integer value. This is +// necessary for storing the global max in an `AtomicUsize`, and for ensuring +// that we use fast integer-integer comparisons, as mentioned previously. In +// order to ensure this, we exploit the niche optimization. The niche +// optimization for `Option<{enum with a numeric repr}>` will choose +// `(HIGHEST_DISCRIMINANT_VALUE + 1)` as the representation for `None`. +// Therefore, the integer representation of `LevelFilter::OFF` (which is +// `None`) will be the number 5. `OFF` must compare higher than every other +// level in order for it to filter as expected. Since we want to use a single +// `cmp` instruction, we can't special-case the integer value of `OFF` to +// compare higher, as that will generate more code. Instead, we need it to be +// on one end of the enum, with `ERROR` on the opposite end, so we assign the +// value 0 to `ERROR`. +// +// This *does* mean that when parsing `LevelFilter`s or `Level`s from +// `String`s, the integer values are inverted, but that doesn't happen in a +// hot path. +// +// Note that we manually invert the comparisons by swapping the left-hand and +// right-hand side. Using `Ordering::reverse` generates significantly worse +// code (per Matt Godbolt's Compiler Explorer). +// +// Anyway, that's a brief history of why this code is the way it is. Don't +// change it unless you know what you're doing. + +impl PartialEq<LevelFilter> for Level { + #[inline(always)] + fn eq(&self, other: &LevelFilter) -> bool { + self.0 as usize == filter_as_usize(&other.0) + } +} + +impl PartialOrd for Level { + #[inline(always)] + fn partial_cmp(&self, other: &Level) -> Option<cmp::Ordering> { + Some(self.cmp(other)) + } + + #[inline(always)] + fn lt(&self, other: &Level) -> bool { + (other.0 as usize) < (self.0 as usize) + } + + #[inline(always)] + fn le(&self, other: &Level) -> bool { + (other.0 as usize) <= (self.0 as usize) + } + + #[inline(always)] + fn gt(&self, other: &Level) -> bool { + (other.0 as usize) > (self.0 as usize) + } + + #[inline(always)] + fn ge(&self, other: &Level) -> bool { + (other.0 as usize) >= (self.0 as usize) + } +} + +impl Ord for Level { + #[inline(always)] + fn cmp(&self, other: &Self) -> cmp::Ordering { + (other.0 as usize).cmp(&(self.0 as usize)) + } +} + +impl PartialOrd<LevelFilter> for Level { + #[inline(always)] + fn partial_cmp(&self, other: &LevelFilter) -> Option<cmp::Ordering> { + Some(filter_as_usize(&other.0).cmp(&(self.0 as usize))) + } + + #[inline(always)] + fn lt(&self, other: &LevelFilter) -> bool { + filter_as_usize(&other.0) < (self.0 as usize) + } + + #[inline(always)] + fn le(&self, other: &LevelFilter) -> bool { + filter_as_usize(&other.0) <= (self.0 as usize) + } + + #[inline(always)] + fn gt(&self, other: &LevelFilter) -> bool { + filter_as_usize(&other.0) > (self.0 as usize) + } + + #[inline(always)] + fn ge(&self, other: &LevelFilter) -> bool { + filter_as_usize(&other.0) >= (self.0 as usize) + } +} + +#[inline(always)] +fn filter_as_usize(x: &Option<Level>) -> usize { + match x { + Some(Level(f)) => *f as usize, + None => LevelFilter::OFF_USIZE, + } +} + +impl PartialEq<Level> for LevelFilter { + #[inline(always)] + fn eq(&self, other: &Level) -> bool { + filter_as_usize(&self.0) == other.0 as usize + } +} + +impl PartialOrd for LevelFilter { + #[inline(always)] + fn partial_cmp(&self, other: &LevelFilter) -> Option<cmp::Ordering> { + Some(self.cmp(other)) + } + + #[inline(always)] + fn lt(&self, other: &LevelFilter) -> bool { + filter_as_usize(&other.0) < filter_as_usize(&self.0) + } + + #[inline(always)] + fn le(&self, other: &LevelFilter) -> bool { + filter_as_usize(&other.0) <= filter_as_usize(&self.0) + } + + #[inline(always)] + fn gt(&self, other: &LevelFilter) -> bool { + filter_as_usize(&other.0) > filter_as_usize(&self.0) + } + + #[inline(always)] + fn ge(&self, other: &LevelFilter) -> bool { + filter_as_usize(&other.0) >= filter_as_usize(&self.0) + } +} + +impl Ord for LevelFilter { + #[inline(always)] + fn cmp(&self, other: &Self) -> cmp::Ordering { + filter_as_usize(&other.0).cmp(&filter_as_usize(&self.0)) + } +} + +impl PartialOrd<Level> for LevelFilter { + #[inline(always)] + fn partial_cmp(&self, other: &Level) -> Option<cmp::Ordering> { + Some((other.0 as usize).cmp(&filter_as_usize(&self.0))) + } + + #[inline(always)] + fn lt(&self, other: &Level) -> bool { + (other.0 as usize) < filter_as_usize(&self.0) + } + + #[inline(always)] + fn le(&self, other: &Level) -> bool { + (other.0 as usize) <= filter_as_usize(&self.0) + } + + #[inline(always)] + fn gt(&self, other: &Level) -> bool { + (other.0 as usize) > filter_as_usize(&self.0) + } + + #[inline(always)] + fn ge(&self, other: &Level) -> bool { + (other.0 as usize) >= filter_as_usize(&self.0) + } +} + +#[cfg(test)] +mod tests { + use super::*; + use crate::stdlib::mem; + + #[test] + fn level_from_str() { + assert_eq!("error".parse::<Level>().unwrap(), Level::ERROR); + assert_eq!("4".parse::<Level>().unwrap(), Level::DEBUG); + assert!("0".parse::<Level>().is_err()) + } + + #[test] + fn filter_level_conversion() { + let mapping = [ + (LevelFilter::OFF, None), + (LevelFilter::ERROR, Some(Level::ERROR)), + (LevelFilter::WARN, Some(Level::WARN)), + (LevelFilter::INFO, Some(Level::INFO)), + (LevelFilter::DEBUG, Some(Level::DEBUG)), + (LevelFilter::TRACE, Some(Level::TRACE)), + ]; + for (filter, level) in mapping.iter() { + assert_eq!(filter.clone().into_level(), *level); + match level { + Some(level) => { + let actual: LevelFilter = level.clone().into(); + assert_eq!(actual, *filter); + } + None => { + let actual: LevelFilter = None.into(); + assert_eq!(actual, *filter); + } + } + } + } + + #[test] + fn level_filter_is_usize_sized() { + assert_eq!( + mem::size_of::<LevelFilter>(), + mem::size_of::<usize>(), + "`LevelFilter` is no longer `usize`-sized! global MAX_LEVEL may now be invalid!" + ) + } + + #[test] + fn level_filter_reprs() { + let mapping = [ + (LevelFilter::OFF, LevelInner::Error as usize + 1), + (LevelFilter::ERROR, LevelInner::Error as usize), + (LevelFilter::WARN, LevelInner::Warn as usize), + (LevelFilter::INFO, LevelInner::Info as usize), + (LevelFilter::DEBUG, LevelInner::Debug as usize), + (LevelFilter::TRACE, LevelInner::Trace as usize), + ]; + for &(filter, expected) in &mapping { + let repr = unsafe { + // safety: The entire purpose of this test is to assert that the + // actual repr matches what we expect it to be --- we're testing + // that *other* unsafe code is sound using the transmuted value. + // We're not going to do anything with it that might be unsound. + mem::transmute::<LevelFilter, usize>(filter) + }; + assert_eq!(expected, repr, "repr changed for {:?}", filter) + } + } +} diff --git a/third_party/rust/tracing-core/src/parent.rs b/third_party/rust/tracing-core/src/parent.rs new file mode 100644 index 0000000000..cb34b376cc --- /dev/null +++ b/third_party/rust/tracing-core/src/parent.rs @@ -0,0 +1,11 @@ +use crate::span::Id; + +#[derive(Debug)] +pub(crate) enum Parent { + /// The new span will be a root span. + Root, + /// The new span will be rooted in the current span. + Current, + /// The new span has an explicitly-specified parent. + Explicit(Id), +} diff --git a/third_party/rust/tracing-core/src/span.rs b/third_party/rust/tracing-core/src/span.rs new file mode 100644 index 0000000000..6dfc41dca6 --- /dev/null +++ b/third_party/rust/tracing-core/src/span.rs @@ -0,0 +1,327 @@ +//! Spans represent periods of time in the execution of a program. +use crate::parent::Parent; +use crate::stdlib::num::NonZeroU64; +use crate::{field, Metadata}; + +/// Identifies a span within the context of a subscriber. +/// +/// They are generated by [`Subscriber`]s for each span as it is created, by +/// the [`new_span`] trait method. See the documentation for that method for +/// more information on span ID generation. +/// +/// [`Subscriber`]: ../subscriber/trait.Subscriber.html +/// [`new_span`]: ../subscriber/trait.Subscriber.html#method.new_span +#[derive(Clone, Debug, PartialEq, Eq, Hash)] +pub struct Id(NonZeroU64); + +/// Attributes provided to a `Subscriber` describing a new span when it is +/// created. +#[derive(Debug)] +pub struct Attributes<'a> { + metadata: &'static Metadata<'static>, + values: &'a field::ValueSet<'a>, + parent: Parent, +} + +/// A set of fields recorded by a span. +#[derive(Debug)] +pub struct Record<'a> { + values: &'a field::ValueSet<'a>, +} + +/// Indicates what [the `Subscriber` considers] the "current" span. +/// +/// As subscribers may not track a notion of a current span, this has three +/// possible states: +/// - "unknown", indicating that the subscriber does not track a current span, +/// - "none", indicating that the current context is known to not be in a span, +/// - "some", with the current span's [`Id`] and [`Metadata`]. +/// +/// [the `Subscriber` considers]: ../subscriber/trait.Subscriber.html#method.current_span +/// [`Id`]: struct.Id.html +/// [`Metadata`]: ../metadata/struct.Metadata.html +#[derive(Debug)] +pub struct Current { + inner: CurrentInner, +} + +#[derive(Debug)] +enum CurrentInner { + Current { + id: Id, + metadata: &'static Metadata<'static>, + }, + None, + Unknown, +} + +// ===== impl Span ===== + +impl Id { + /// Constructs a new span ID from the given `u64`. + /// + /// <div class="information"> + /// <div class="tooltip ignore" style="">ⓘ<span class="tooltiptext">Note</span></div> + /// </div> + /// <div class="example-wrap" style="display:inline-block"> + /// <pre class="ignore" style="white-space:normal;font:inherit;"> + /// <strong>Note</strong>: Span IDs must be greater than zero.</pre></div> + /// + /// # Panics + /// - If the provided `u64` is 0 + pub fn from_u64(u: u64) -> Self { + Id(NonZeroU64::new(u).expect("span IDs must be > 0")) + } + + /// Constructs a new span ID from the given `NonZeroU64`. + /// + /// Unlike [`Id::from_u64`](#method.from_u64), this will never panic. + #[inline] + pub const fn from_non_zero_u64(id: NonZeroU64) -> Self { + Id(id) + } + + // Allow `into` by-ref since we don't want to impl Copy for Id + #[allow(clippy::wrong_self_convention)] + /// Returns the span's ID as a `u64`. + pub fn into_u64(&self) -> u64 { + self.0.get() + } + + // Allow `into` by-ref since we don't want to impl Copy for Id + #[allow(clippy::wrong_self_convention)] + /// Returns the span's ID as a `NonZeroU64`. + #[inline] + pub const fn into_non_zero_u64(&self) -> NonZeroU64 { + self.0 + } +} + +impl<'a> Into<Option<Id>> for &'a Id { + fn into(self) -> Option<Id> { + Some(self.clone()) + } +} + +// ===== impl Attributes ===== + +impl<'a> Attributes<'a> { + /// Returns `Attributes` describing a new child span of the current span, + /// with the provided metadata and values. + pub fn new(metadata: &'static Metadata<'static>, values: &'a field::ValueSet<'a>) -> Self { + Attributes { + metadata, + values, + parent: Parent::Current, + } + } + + /// Returns `Attributes` describing a new span at the root of its own trace + /// tree, with the provided metadata and values. + pub fn new_root(metadata: &'static Metadata<'static>, values: &'a field::ValueSet<'a>) -> Self { + Attributes { + metadata, + values, + parent: Parent::Root, + } + } + + /// Returns `Attributes` describing a new child span of the specified + /// parent span, with the provided metadata and values. + pub fn child_of( + parent: Id, + metadata: &'static Metadata<'static>, + values: &'a field::ValueSet<'a>, + ) -> Self { + Attributes { + metadata, + values, + parent: Parent::Explicit(parent), + } + } + + /// Returns a reference to the new span's metadata. + pub fn metadata(&self) -> &'static Metadata<'static> { + self.metadata + } + + /// Returns a reference to a `ValueSet` containing any values the new span + /// was created with. + pub fn values(&self) -> &field::ValueSet<'a> { + self.values + } + + /// Returns true if the new span should be a root. + pub fn is_root(&self) -> bool { + match self.parent { + Parent::Root => true, + _ => false, + } + } + + /// Returns true if the new span's parent should be determined based on the + /// current context. + /// + /// If this is true and the current thread is currently inside a span, then + /// that span should be the new span's parent. Otherwise, if the current + /// thread is _not_ inside a span, then the new span will be the root of its + /// own trace tree. + pub fn is_contextual(&self) -> bool { + match self.parent { + Parent::Current => true, + _ => false, + } + } + + /// Returns the new span's explicitly-specified parent, if there is one. + /// + /// Otherwise (if the new span is a root or is a child of the current span), + /// returns false. + pub fn parent(&self) -> Option<&Id> { + match self.parent { + Parent::Explicit(ref p) => Some(p), + _ => None, + } + } + + /// Records all the fields in this set of `Attributes` with the provided + /// [Visitor]. + /// + /// [visitor]: ../field/trait.Visit.html + pub fn record(&self, visitor: &mut dyn field::Visit) { + self.values.record(visitor) + } + + /// Returns `true` if this set of `Attributes` contains a value for the + /// given `Field`. + pub fn contains(&self, field: &field::Field) -> bool { + self.values.contains(field) + } + + /// Returns true if this set of `Attributes` contains _no_ values. + pub fn is_empty(&self) -> bool { + self.values.is_empty() + } +} + +// ===== impl Record ===== + +impl<'a> Record<'a> { + /// Constructs a new `Record` from a `ValueSet`. + pub fn new(values: &'a field::ValueSet<'a>) -> Self { + Self { values } + } + + /// Records all the fields in this `Record` with the provided [Visitor]. + /// + /// [visitor]: ../field/trait.Visit.html + pub fn record(&self, visitor: &mut dyn field::Visit) { + self.values.record(visitor) + } + + /// Returns `true` if this `Record` contains a value for the given `Field`. + pub fn contains(&self, field: &field::Field) -> bool { + self.values.contains(field) + } + + /// Returns true if this `Record` contains _no_ values. + pub fn is_empty(&self) -> bool { + self.values.is_empty() + } +} + +// ===== impl Current ===== + +impl Current { + /// Constructs a new `Current` that indicates the current context is a span + /// with the given `metadata` and `metadata`. + pub fn new(id: Id, metadata: &'static Metadata<'static>) -> Self { + Self { + inner: CurrentInner::Current { id, metadata }, + } + } + + /// Constructs a new `Current` that indicates the current context is *not* + /// in a span. + pub fn none() -> Self { + Self { + inner: CurrentInner::None, + } + } + + /// Constructs a new `Current` that indicates the `Subscriber` does not + /// track a current span. + pub(crate) fn unknown() -> Self { + Self { + inner: CurrentInner::Unknown, + } + } + + /// Returns `true` if the `Subscriber` that constructed this `Current` tracks a + /// current span. + /// + /// If this returns `true` and [`id`], [`metadata`], or [`into_inner`] + /// return `None`, that indicates that we are currently known to *not* be + /// inside a span. If this returns `false`, those methods will also return + /// `None`, but in this case, that is because the subscriber does not keep + /// track of the currently-entered span. + /// + /// [`id`]: #method.id + /// [`metadata`]: #method.metadata + /// [`into_inner`]: #method.into_inner + pub fn is_known(&self) -> bool { + match self.inner { + CurrentInner::Unknown => false, + _ => true, + } + } + + /// Consumes `self` and returns the span `Id` and `Metadata` of the current + /// span, if one exists and is known. + pub fn into_inner(self) -> Option<(Id, &'static Metadata<'static>)> { + match self.inner { + CurrentInner::Current { id, metadata } => Some((id, metadata)), + _ => None, + } + } + + /// Borrows the `Id` of the current span, if one exists and is known. + pub fn id(&self) -> Option<&Id> { + match self.inner { + CurrentInner::Current { ref id, .. } => Some(id), + _ => None, + } + } + + /// Borrows the `Metadata` of the current span, if one exists and is known. + pub fn metadata(&self) -> Option<&'static Metadata<'static>> { + match self.inner { + CurrentInner::Current { ref metadata, .. } => Some(*metadata), + _ => None, + } + } +} + +impl<'a> Into<Option<&'a Id>> for &'a Current { + fn into(self) -> Option<&'a Id> { + self.id() + } +} + +impl<'a> Into<Option<Id>> for &'a Current { + fn into(self) -> Option<Id> { + self.id().cloned() + } +} + +impl Into<Option<Id>> for Current { + fn into(self) -> Option<Id> { + self.id().cloned() + } +} + +impl<'a> Into<Option<&'static Metadata<'static>>> for &'a Current { + fn into(self) -> Option<&'static Metadata<'static>> { + self.metadata() + } +} diff --git a/third_party/rust/tracing-core/src/spin/LICENSE b/third_party/rust/tracing-core/src/spin/LICENSE new file mode 100644 index 0000000000..84d5f4d7af --- /dev/null +++ b/third_party/rust/tracing-core/src/spin/LICENSE @@ -0,0 +1,21 @@ +The MIT License (MIT) + +Copyright (c) 2014 Mathijs van de Nes + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/third_party/rust/tracing-core/src/spin/mod.rs b/third_party/rust/tracing-core/src/spin/mod.rs new file mode 100644 index 0000000000..148b192b34 --- /dev/null +++ b/third_party/rust/tracing-core/src/spin/mod.rs @@ -0,0 +1,7 @@ +//! Synchronization primitives based on spinning + +pub(crate) use mutex::*; +pub(crate) use once::Once; + +mod mutex; +mod once; diff --git a/third_party/rust/tracing-core/src/spin/mutex.rs b/third_party/rust/tracing-core/src/spin/mutex.rs new file mode 100644 index 0000000000..383a2cd839 --- /dev/null +++ b/third_party/rust/tracing-core/src/spin/mutex.rs @@ -0,0 +1,109 @@ +use core::cell::UnsafeCell; +use core::default::Default; +use core::fmt; +use core::marker::Sync; +use core::ops::{Deref, DerefMut, Drop}; +use core::option::Option::{self, None, Some}; +use core::sync::atomic::{spin_loop_hint as cpu_relax, AtomicBool, Ordering}; + +/// This type provides MUTual EXclusion based on spinning. +pub(crate) struct Mutex<T: ?Sized> { + lock: AtomicBool, + data: UnsafeCell<T>, +} + +/// A guard to which the protected data can be accessed +/// +/// When the guard falls out of scope it will release the lock. +#[derive(Debug)] +pub(crate) struct MutexGuard<'a, T: ?Sized> { + lock: &'a AtomicBool, + data: &'a mut T, +} + +// Same unsafe impls as `std::sync::Mutex` +unsafe impl<T: ?Sized + Send> Sync for Mutex<T> {} +unsafe impl<T: ?Sized + Send> Send for Mutex<T> {} + +impl<T> Mutex<T> { + /// Creates a new spinlock wrapping the supplied data. + pub(crate) const fn new(user_data: T) -> Mutex<T> { + Mutex { + lock: AtomicBool::new(false), + data: UnsafeCell::new(user_data), + } + } +} + +impl<T: ?Sized> Mutex<T> { + fn obtain_lock(&self) { + while self.lock.compare_and_swap(false, true, Ordering::Acquire) != false { + // Wait until the lock looks unlocked before retrying + while self.lock.load(Ordering::Relaxed) { + cpu_relax(); + } + } + } + + /// Locks the spinlock and returns a guard. + /// + /// The returned value may be dereferenced for data access + /// and the lock will be dropped when the guard falls out of scope. + pub(crate) fn lock(&self) -> MutexGuard<'_, T> { + self.obtain_lock(); + MutexGuard { + lock: &self.lock, + data: unsafe { &mut *self.data.get() }, + } + } + + /// Tries to lock the mutex. If it is already locked, it will return None. Otherwise it returns + /// a guard within Some. + pub(crate) fn try_lock(&self) -> Option<MutexGuard<'_, T>> { + if self.lock.compare_and_swap(false, true, Ordering::Acquire) == false { + Some(MutexGuard { + lock: &self.lock, + data: unsafe { &mut *self.data.get() }, + }) + } else { + None + } + } +} + +impl<T: ?Sized + fmt::Debug> fmt::Debug for Mutex<T> { + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + match self.try_lock() { + Some(guard) => write!(f, "Mutex {{ data: ") + .and_then(|()| (&*guard).fmt(f)) + .and_then(|()| write!(f, "}}")), + None => write!(f, "Mutex {{ <locked> }}"), + } + } +} + +impl<T: ?Sized + Default> Default for Mutex<T> { + fn default() -> Mutex<T> { + Mutex::new(Default::default()) + } +} + +impl<'a, T: ?Sized> Deref for MutexGuard<'a, T> { + type Target = T; + fn deref<'b>(&'b self) -> &'b T { + &*self.data + } +} + +impl<'a, T: ?Sized> DerefMut for MutexGuard<'a, T> { + fn deref_mut<'b>(&'b mut self) -> &'b mut T { + &mut *self.data + } +} + +impl<'a, T: ?Sized> Drop for MutexGuard<'a, T> { + /// The dropping of the MutexGuard will release the lock it was created from. + fn drop(&mut self) { + self.lock.store(false, Ordering::Release); + } +} diff --git a/third_party/rust/tracing-core/src/spin/once.rs b/third_party/rust/tracing-core/src/spin/once.rs new file mode 100644 index 0000000000..0bc47b566a --- /dev/null +++ b/third_party/rust/tracing-core/src/spin/once.rs @@ -0,0 +1,146 @@ +use core::cell::UnsafeCell; +use core::fmt; +use core::sync::atomic::{spin_loop_hint as cpu_relax, AtomicUsize, Ordering}; + +/// A synchronization primitive which can be used to run a one-time global +/// initialization. Unlike its std equivalent, this is generalized so that the +/// closure returns a value and it is stored. Once therefore acts something like +/// a future, too. +pub struct Once<T> { + state: AtomicUsize, + data: UnsafeCell<Option<T>>, // TODO remove option and use mem::uninitialized +} + +impl<T: fmt::Debug> fmt::Debug for Once<T> { + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + match self.r#try() { + Some(s) => write!(f, "Once {{ data: ") + .and_then(|()| s.fmt(f)) + .and_then(|()| write!(f, "}}")), + None => write!(f, "Once {{ <uninitialized> }}"), + } + } +} + +// Same unsafe impls as `std::sync::RwLock`, because this also allows for +// concurrent reads. +unsafe impl<T: Send + Sync> Sync for Once<T> {} +unsafe impl<T: Send> Send for Once<T> {} + +// Four states that a Once can be in, encoded into the lower bits of `state` in +// the Once structure. +const INCOMPLETE: usize = 0x0; +const RUNNING: usize = 0x1; +const COMPLETE: usize = 0x2; +const PANICKED: usize = 0x3; + +use core::hint::unreachable_unchecked as unreachable; + +impl<T> Once<T> { + /// Initialization constant of `Once`. + pub const INIT: Self = Once { + state: AtomicUsize::new(INCOMPLETE), + data: UnsafeCell::new(None), + }; + + /// Creates a new `Once` value. + pub const fn new() -> Once<T> { + Self::INIT + } + + fn force_get<'a>(&'a self) -> &'a T { + match unsafe { &*self.data.get() }.as_ref() { + None => unsafe { unreachable() }, + Some(p) => p, + } + } + + /// Performs an initialization routine once and only once. The given closure + /// will be executed if this is the first time `call_once` has been called, + /// and otherwise the routine will *not* be invoked. + /// + /// This method will block the calling thread if another initialization + /// routine is currently running. + /// + /// When this function returns, it is guaranteed that some initialization + /// has run and completed (it may not be the closure specified). The + /// returned pointer will point to the result from the closure that was + /// run. + pub fn call_once<'a, F>(&'a self, builder: F) -> &'a T + where + F: FnOnce() -> T, + { + let mut status = self.state.load(Ordering::SeqCst); + + if status == INCOMPLETE { + status = self + .state + .compare_and_swap(INCOMPLETE, RUNNING, Ordering::SeqCst); + if status == INCOMPLETE { + // We init + // We use a guard (Finish) to catch panics caused by builder + let mut finish = Finish { + state: &self.state, + panicked: true, + }; + unsafe { *self.data.get() = Some(builder()) }; + finish.panicked = false; + + status = COMPLETE; + self.state.store(status, Ordering::SeqCst); + + // This next line is strictly an optimization + return self.force_get(); + } + } + + loop { + match status { + INCOMPLETE => unreachable!(), + RUNNING => { + // We spin + cpu_relax(); + status = self.state.load(Ordering::SeqCst) + } + PANICKED => panic!("Once has panicked"), + COMPLETE => return self.force_get(), + _ => unsafe { unreachable() }, + } + } + } + + /// Returns a pointer iff the `Once` was previously initialized + pub fn r#try<'a>(&'a self) -> Option<&'a T> { + match self.state.load(Ordering::SeqCst) { + COMPLETE => Some(self.force_get()), + _ => None, + } + } + + /// Like try, but will spin if the `Once` is in the process of being + /// initialized + pub fn wait<'a>(&'a self) -> Option<&'a T> { + loop { + match self.state.load(Ordering::SeqCst) { + INCOMPLETE => return None, + RUNNING => cpu_relax(), // We spin + COMPLETE => return Some(self.force_get()), + PANICKED => panic!("Once has panicked"), + _ => unsafe { unreachable() }, + } + } + } +} + +struct Finish<'a> { + state: &'a AtomicUsize, + panicked: bool, +} + +impl<'a> Drop for Finish<'a> { + fn drop(&mut self) { + if self.panicked { + self.state.store(PANICKED, Ordering::SeqCst); + } + } +} diff --git a/third_party/rust/tracing-core/src/stdlib.rs b/third_party/rust/tracing-core/src/stdlib.rs new file mode 100644 index 0000000000..4a1c17c2b8 --- /dev/null +++ b/third_party/rust/tracing-core/src/stdlib.rs @@ -0,0 +1,78 @@ +//! Re-exports either the Rust `std` library or `core` and `alloc` when `std` is +//! disabled. +//! +//! `crate::stdlib::...` should be used rather than `std::` when adding code that +//! will be available with the standard library disabled. +//! +//! Note that this module is called `stdlib` rather than `std`, as Rust 1.34.0 +//! does not permit redefining the name `stdlib` (although this works on the +//! latest stable Rust). +#[cfg(feature = "std")] +pub(crate) use std::*; + +#[cfg(not(feature = "std"))] +pub(crate) use self::no_std::*; + +#[cfg(not(feature = "std"))] +mod no_std { + // We pre-emptively export everything from libcore/liballoc, (even modules + // we aren't using currently) to make adding new code easier. Therefore, + // some of these imports will be unused. + #![allow(unused_imports)] + + pub(crate) use core::{ + any, array, ascii, cell, char, clone, cmp, convert, default, f32, f64, ffi, future, hash, + hint, i128, i16, i8, isize, iter, marker, mem, num, ops, option, pin, ptr, result, task, + time, u128, u16, u32, u8, usize, + }; + + pub(crate) use alloc::{boxed, collections, rc, string, vec}; + + pub(crate) mod borrow { + pub(crate) use alloc::borrow::*; + pub(crate) use core::borrow::*; + } + + pub(crate) mod fmt { + pub(crate) use alloc::fmt::*; + pub(crate) use core::fmt::*; + } + + pub(crate) mod slice { + pub(crate) use alloc::slice::*; + pub(crate) use core::slice::*; + } + + pub(crate) mod str { + pub(crate) use alloc::str::*; + pub(crate) use core::str::*; + } + + pub(crate) mod sync { + pub(crate) use crate::spin::MutexGuard; + pub(crate) use alloc::sync::*; + pub(crate) use core::sync::*; + + /// This wraps `spin::Mutex` to return a `Result`, so that it can be + /// used with code written against `std::sync::Mutex`. + /// + /// Since `spin::Mutex` doesn't support poisoning, the `Result` returned + /// by `lock` will always be `Ok`. + #[derive(Debug, Default)] + pub(crate) struct Mutex<T> { + inner: crate::spin::Mutex<T>, + } + + impl<T> Mutex<T> { + pub(crate) fn new(data: T) -> Self { + Self { + inner: crate::spin::Mutex::new(data), + } + } + + pub(crate) fn lock(&self) -> Result<MutexGuard<'_, T>, ()> { + Ok(self.inner.lock()) + } + } + } +} diff --git a/third_party/rust/tracing-core/src/subscriber.rs b/third_party/rust/tracing-core/src/subscriber.rs new file mode 100644 index 0000000000..2b56f8d483 --- /dev/null +++ b/third_party/rust/tracing-core/src/subscriber.rs @@ -0,0 +1,570 @@ +//! Subscribers collect and record trace data. +use crate::{span, Event, LevelFilter, Metadata}; + +use crate::stdlib::any::{Any, TypeId}; + +/// Trait representing the functions required to collect trace data. +/// +/// Crates that provide implementations of methods for collecting or recording +/// trace data should implement the `Subscriber` interface. This trait is +/// intended to represent fundamental primitives for collecting trace events and +/// spans — other libraries may offer utility functions and types to make +/// subscriber implementations more modular or improve the ergonomics of writing +/// subscribers. +/// +/// A subscriber is responsible for the following: +/// - Registering new spans as they are created, and providing them with span +/// IDs. Implicitly, this means the subscriber may determine the strategy for +/// determining span equality. +/// - Recording the attachment of field values and follows-from annotations to +/// spans. +/// - Filtering spans and events, and determining when those filters must be +/// invalidated. +/// - Observing spans as they are entered, exited, and closed, and events as +/// they occur. +/// +/// When a span is entered or exited, the subscriber is provided only with the +/// [ID] with which it tagged that span when it was created. This means +/// that it is up to the subscriber to determine whether and how span _data_ — +/// the fields and metadata describing the span — should be stored. The +/// [`new_span`] function is called when a new span is created, and at that +/// point, the subscriber _may_ choose to store the associated data if it will +/// be referenced again. However, if the data has already been recorded and will +/// not be needed by the implementations of `enter` and `exit`, the subscriber +/// may freely discard that data without allocating space to store it. +/// +/// ## Overriding default impls +/// +/// Some trait methods on `Subscriber` have default implementations, either in +/// order to reduce the surface area of implementing `Subscriber`, or for +/// backward-compatibility reasons. However, many subscribers will likely want +/// to override these default implementations. +/// +/// The following methods are likely of interest: +/// +/// - [`register_callsite`] is called once for each callsite from which a span +/// event may originate, and returns an [`Interest`] value describing whether or +/// not the subscriber wishes to see events or spans from that callsite. By +/// default, it calls [`enabled`], and returns `Interest::always()` if +/// `enabled` returns true, or `Interest::never()` if enabled returns false. +/// However, if the subscriber's interest can change dynamically at runtime, +/// it may want to override this function to return `Interest::sometimes()`. +/// Additionally, subscribers which wish to perform a behaviour once for each +/// callsite, such as allocating storage for data related to that callsite, +/// can perform it in `register_callsite`. +/// - [`clone_span`] is called every time a span ID is cloned, and [`try_close`] +/// is called when a span ID is dropped. By default, these functions do +/// nothing. However, they can be used to implement reference counting for +/// spans, allowing subscribers to free storage for span data and to determine +/// when a span has _closed_ permanently (rather than being exited). +/// Subscribers which store per-span data or which need to track span closures +/// should override these functions together. +/// +/// [ID]: ../span/struct.Id.html +/// [`new_span`]: trait.Subscriber.html#method.new_span +/// [`register_callsite`]: trait.Subscriber.html#method.register_callsite +/// [`Interest`]: struct.Interest.html +/// [`enabled`]: trait.Subscriber.html#method.enabled +/// [`clone_span`]: trait.Subscriber.html#method.clone_span +/// [`try_close`]: trait.Subscriber.html#method.try_close +pub trait Subscriber: 'static { + // === Span registry methods ============================================== + + /// Registers a new callsite with this subscriber, returning whether or not + /// the subscriber is interested in being notified about the callsite. + /// + /// By default, this function assumes that the subscriber's [filter] + /// represents an unchanging view of its interest in the callsite. However, + /// if this is not the case, subscribers may override this function to + /// indicate different interests, or to implement behaviour that should run + /// once for every callsite. + /// + /// This function is guaranteed to be called at least once per callsite on + /// every active subscriber. The subscriber may store the keys to fields it + /// cares about in order to reduce the cost of accessing fields by name, + /// preallocate storage for that callsite, or perform any other actions it + /// wishes to perform once for each callsite. + /// + /// The subscriber should then return an [`Interest`], indicating + /// whether it is interested in being notified about that callsite in the + /// future. This may be `Always` indicating that the subscriber always + /// wishes to be notified about the callsite, and its filter need not be + /// re-evaluated; `Sometimes`, indicating that the subscriber may sometimes + /// care about the callsite but not always (such as when sampling), or + /// `Never`, indicating that the subscriber never wishes to be notified about + /// that callsite. If all active subscribers return `Never`, a callsite will + /// never be enabled unless a new subscriber expresses interest in it. + /// + /// `Subscriber`s which require their filters to be run every time an event + /// occurs or a span is entered/exited should return `Interest::sometimes`. + /// If a subscriber returns `Interest::sometimes`, then its' [`enabled`] method + /// will be called every time an event or span is created from that callsite. + /// + /// For example, suppose a sampling subscriber is implemented by + /// incrementing a counter every time `enabled` is called and only returning + /// `true` when the counter is divisible by a specified sampling rate. If + /// that subscriber returns `Interest::always` from `register_callsite`, then + /// the filter will not be re-evaluated once it has been applied to a given + /// set of metadata. Thus, the counter will not be incremented, and the span + /// or event that corresponds to the metadata will never be `enabled`. + /// + /// `Subscriber`s that need to change their filters occasionally should call + /// [`rebuild_interest_cache`] to re-evaluate `register_callsite` for all + /// callsites. + /// + /// Similarly, if a `Subscriber` has a filtering strategy that can be + /// changed dynamically at runtime, it would need to re-evaluate that filter + /// if the cached results have changed. + /// + /// A subscriber which manages fanout to multiple other subscribers + /// should proxy this decision to all of its child subscribers, + /// returning `Interest::never` only if _all_ such children return + /// `Interest::never`. If the set of subscribers to which spans are + /// broadcast may change dynamically, the subscriber should also never + /// return `Interest::Never`, as a new subscriber may be added that _is_ + /// interested. + /// + /// # Notes + /// This function may be called again when a new subscriber is created or + /// when the registry is invalidated. + /// + /// If a subscriber returns `Interest::never` for a particular callsite, it + /// _may_ still see spans and events originating from that callsite, if + /// another subscriber expressed interest in it. + /// + /// [filter]: #method.enabled + /// [metadata]: ../metadata/struct.Metadata.html + /// [`Interest`]: struct.Interest.html + /// [`enabled`]: #method.enabled + /// [`rebuild_interest_cache`]: ../callsite/fn.rebuild_interest_cache.html + fn register_callsite(&self, metadata: &'static Metadata<'static>) -> Interest { + if self.enabled(metadata) { + Interest::always() + } else { + Interest::never() + } + } + + /// Returns true if a span or event with the specified [metadata] would be + /// recorded. + /// + /// By default, it is assumed that this filter needs only be evaluated once + /// for each callsite, so it is called by [`register_callsite`] when each + /// callsite is registered. The result is used to determine if the subscriber + /// is always [interested] or never interested in that callsite. This is intended + /// primarily as an optimization, so that expensive filters (such as those + /// involving string search, et cetera) need not be re-evaluated. + /// + /// However, if the subscriber's interest in a particular span or event may + /// change, or depends on contexts only determined dynamically at runtime, + /// then the `register_callsite` method should be overridden to return + /// [`Interest::sometimes`]. In that case, this function will be called every + /// time that span or event occurs. + /// + /// [metadata]: ../metadata/struct.Metadata.html + /// [interested]: struct.Interest.html + /// [`Interest::sometimes`]: struct.Interest.html#method.sometimes + /// [`register_callsite`]: #method.register_callsite + fn enabled(&self, metadata: &Metadata<'_>) -> bool; + + /// Returns the highest [verbosity level][level] that this `Subscriber` will + /// enable, or `None`, if the subscriber does not implement level-based + /// filtering or chooses not to implement this method. + /// + /// If this method returns a [`Level`][level], it will be used as a hint to + /// determine the most verbose level that will be enabled. This will allow + /// spans and events which are more verbose than that level to be skipped + /// more efficiently. Subscribers which perform filtering are strongly + /// encouraged to provide an implementation of this method. + /// + /// If the maximum level the subscriber will enable can change over the + /// course of its lifetime, it is free to return a different value from + /// multiple invocations of this method. However, note that changes in the + /// maximum level will **only** be reflected after the callsite [`Interest`] + /// cache is rebuilt, by calling the [`callsite::rebuild_interest_cache`][rebuild] + /// function. Therefore, if the subscriber will change the value returned by + /// this method, it is responsible for ensuring that + /// [`rebuild_interest_cache`][rebuild] is called after the value of the max + /// level changes. + /// + /// [level]: ../struct.Level.html + /// [`Interest`]: struct.Interest.html + /// [rebuild]: ../callsite/fn.rebuild_interest_cache.html + fn max_level_hint(&self) -> Option<LevelFilter> { + None + } + + /// Visit the construction of a new span, returning a new [span ID] for the + /// span being constructed. + /// + /// The provided [`Attributes`] contains any field values that were provided + /// when the span was created. The subscriber may pass a [visitor] to the + /// `Attributes`' [`record` method] to record these values. + /// + /// IDs are used to uniquely identify spans and events within the context of a + /// subscriber, so span equality will be based on the returned ID. Thus, if + /// the subscriber wishes for all spans with the same metadata to be + /// considered equal, it should return the same ID every time it is given a + /// particular set of metadata. Similarly, if it wishes for two separate + /// instances of a span with the same metadata to *not* be equal, it should + /// return a distinct ID every time this function is called, regardless of + /// the metadata. + /// + /// Note that the subscriber is free to assign span IDs based on whatever + /// scheme it sees fit. Any guarantees about uniqueness, ordering, or ID + /// reuse are left up to the subscriber implementation to determine. + /// + /// [span ID]: ../span/struct.Id.html + /// [`Attributes`]: ../span/struct.Attributes.html + /// [visitor]: ../field/trait.Visit.html + /// [`record` method]: ../span/struct.Attributes.html#method.record + fn new_span(&self, span: &span::Attributes<'_>) -> span::Id; + + // === Notification methods =============================================== + + /// Record a set of values on a span. + /// + /// This method will be invoked when value is recorded on a span. + /// Recording multiple values for the same field is possible, + /// but the actual behaviour is defined by the subscriber implementation. + /// + /// Keep in mind that a span might not provide a value + /// for each field it declares. + /// + /// The subscriber is expected to provide a [visitor] to the `Record`'s + /// [`record` method] in order to record the added values. + /// + /// # Example + /// "foo = 3" will be recorded when [`record`] is called on the + /// `Attributes` passed to `new_span`. + /// Since values are not provided for the `bar` and `baz` fields, + /// the span's `Metadata` will indicate that it _has_ those fields, + /// but values for them won't be recorded at this time. + /// + /// ```rust,ignore + /// #[macro_use] + /// extern crate tracing; + /// + /// let mut span = span!("my_span", foo = 3, bar, baz); + /// + /// // `Subscriber::record` will be called with a `Record` + /// // containing "bar = false" + /// span.record("bar", &false); + /// + /// // `Subscriber::record` will be called with a `Record` + /// // containing "baz = "a string"" + /// span.record("baz", &"a string"); + /// ``` + /// + /// [visitor]: ../field/trait.Visit.html + /// [`record`]: ../span/struct.Attributes.html#method.record + /// [`record` method]: ../span/struct.Record.html#method.record + fn record(&self, span: &span::Id, values: &span::Record<'_>); + + /// Adds an indication that `span` follows from the span with the id + /// `follows`. + /// + /// This relationship differs somewhat from the parent-child relationship: a + /// span may have any number of prior spans, rather than a single one; and + /// spans are not considered to be executing _inside_ of the spans they + /// follow from. This means that a span may close even if subsequent spans + /// that follow from it are still open, and time spent inside of a + /// subsequent span should not be included in the time its precedents were + /// executing. This is used to model causal relationships such as when a + /// single future spawns several related background tasks, et cetera. + /// + /// If the subscriber has spans corresponding to the given IDs, it should + /// record this relationship in whatever way it deems necessary. Otherwise, + /// if one or both of the given span IDs do not correspond to spans that the + /// subscriber knows about, or if a cyclical relationship would be created + /// (i.e., some span _a_ which proceeds some other span _b_ may not also + /// follow from _b_), it may silently do nothing. + fn record_follows_from(&self, span: &span::Id, follows: &span::Id); + + /// Records that an [`Event`] has occurred. + /// + /// This method will be invoked when an Event is constructed by + /// the `Event`'s [`dispatch` method]. For example, this happens internally + /// when an event macro from `tracing` is called. + /// + /// The key difference between this method and `record` is that `record` is + /// called when a value is recorded for a field defined by a span, + /// while `event` is called when a new event occurs. + /// + /// The provided `Event` struct contains any field values attached to the + /// event. The subscriber may pass a [visitor] to the `Event`'s + /// [`record` method] to record these values. + /// + /// [`Event`]: ../event/struct.Event.html + /// [visitor]: ../field/trait.Visit.html + /// [`record` method]: ../event/struct.Event.html#method.record + /// [`dispatch` method]: ../event/struct.Event.html#method.dispatch + fn event(&self, event: &Event<'_>); + + /// Records that a span has been entered. + /// + /// When entering a span, this method is called to notify the subscriber + /// that the span has been entered. The subscriber is provided with the + /// [span ID] of the entered span, and should update any internal state + /// tracking the current span accordingly. + /// + /// [span ID]: ../span/struct.Id.html + fn enter(&self, span: &span::Id); + + /// Records that a span has been exited. + /// + /// When exiting a span, this method is called to notify the subscriber + /// that the span has been exited. The subscriber is provided with the + /// [span ID] of the exited span, and should update any internal state + /// tracking the current span accordingly. + /// + /// Exiting a span does not imply that the span will not be re-entered. + /// + /// [span ID]: ../span/struct.Id.html + fn exit(&self, span: &span::Id); + + /// Notifies the subscriber that a [span ID] has been cloned. + /// + /// This function is guaranteed to only be called with span IDs that were + /// returned by this subscriber's `new_span` function. + /// + /// Note that the default implementation of this function this is just the + /// identity function, passing through the identifier. However, it can be + /// used in conjunction with [`try_close`] to track the number of handles + /// capable of `enter`ing a span. When all the handles have been dropped + /// (i.e., `try_close` has been called one more time than `clone_span` for a + /// given ID), the subscriber may assume that the span will not be entered + /// again. It is then free to deallocate storage for data associated with + /// that span, write data from that span to IO, and so on. + /// + /// For more unsafe situations, however, if `id` is itself a pointer of some + /// kind this can be used as a hook to "clone" the pointer, depending on + /// what that means for the specified pointer. + /// + /// [span ID]: ../span/struct.Id.html + /// [`try_close`]: trait.Subscriber.html#method.try_close + fn clone_span(&self, id: &span::Id) -> span::Id { + id.clone() + } + + /// **This method is deprecated.** + /// + /// Using `drop_span` may result in subscribers composed using + /// `tracing-subscriber` crate's `Layer` trait from observing close events. + /// Use [`try_close`] instead. + /// + /// The default implementation of this function does nothing. + /// + /// [`try_close`]: trait.Subscriber.html#method.try_close + #[deprecated(since = "0.1.2", note = "use `Subscriber::try_close` instead")] + fn drop_span(&self, _id: span::Id) {} + + /// Notifies the subscriber that a [`span ID`] has been dropped, and returns + /// `true` if there are now 0 IDs that refer to that span. + /// + /// Higher-level libraries providing functionality for composing multiple + /// subscriber implementations may use this return value to notify any + /// "layered" subscribers that this subscriber considers the span closed. + /// + /// The default implementation of this method calls the subscriber's + /// [`drop_span`] method and returns `false`. This means that, unless the + /// subscriber overrides the default implementation, close notifications + /// will never be sent to any layered subscribers. In general, if the + /// subscriber tracks reference counts, this method should be implemented, + /// rather than `drop_span`. + /// + /// This function is guaranteed to only be called with span IDs that were + /// returned by this subscriber's `new_span` function. + /// + /// It's guaranteed that if this function has been called once more than the + /// number of times `clone_span` was called with the same `id`, then no more + /// handles that can enter the span with that `id` exist. This means that it + /// can be used in conjunction with [`clone_span`] to track the number of + /// handles capable of `enter`ing a span. When all the handles have been + /// dropped (i.e., `try_close` has been called one more time than + /// `clone_span` for a given ID), the subscriber may assume that the span + /// will not be entered again, and should return `true`. It is then free to + /// deallocate storage for data associated with that span, write data from + /// that span to IO, and so on. + /// + /// **Note**: since this function is called when spans are dropped, + /// implementations should ensure that they are unwind-safe. Panicking from + /// inside of a `try_close` function may cause a double panic, if the span + /// was dropped due to a thread unwinding. + /// + /// [span ID]: ../span/struct.Id.html + /// [`clone_span`]: trait.Subscriber.html#method.clone_span + /// [`drop_span`]: trait.Subscriber.html#method.drop_span + fn try_close(&self, id: span::Id) -> bool { + #[allow(deprecated)] + self.drop_span(id); + false + } + + /// Returns a type representing this subscriber's view of the current span. + /// + /// If subscribers track a current span, they should override this function + /// to return [`Current::new`] if the thread from which this method is + /// called is inside a span, or [`Current::none`] if the thread is not + /// inside a span. + /// + /// By default, this returns a value indicating that the subscriber + /// does **not** track what span is current. If the subscriber does not + /// implement a current span, it should not override this method. + /// + /// [`Current::new`]: ../span/struct.Current.html#tymethod.new + /// [`Current::none`]: ../span/struct.Current.html#tymethod.none + fn current_span(&self) -> span::Current { + span::Current::unknown() + } + + // === Downcasting methods ================================================ + + /// If `self` is the same type as the provided `TypeId`, returns an untyped + /// `*const` pointer to that type. Otherwise, returns `None`. + /// + /// If you wish to downcast a `Subscriber`, it is strongly advised to use + /// the safe API provided by [`downcast_ref`] instead. + /// + /// This API is required for `downcast_raw` to be a trait method; a method + /// signature like [`downcast_ref`] (with a generic type parameter) is not + /// object-safe, and thus cannot be a trait method for `Subscriber`. This + /// means that if we only exposed `downcast_ref`, `Subscriber` + /// implementations could not override the downcasting behavior + /// + /// This method may be overridden by "fan out" or "chained" subscriber + /// implementations which consist of multiple composed types. Such + /// subscribers might allow `downcast_raw` by returning references to those + /// component if they contain components with the given `TypeId`. + /// + /// # Safety + /// + /// The [`downcast_ref`] method expects that the pointer returned by + /// `downcast_raw` is non-null and points to a valid instance of the type + /// with the provided `TypeId`. Failure to ensure this will result in + /// undefined behaviour, so implementing `downcast_raw` is unsafe. + /// + /// [`downcast_ref`]: #method.downcast_ref + unsafe fn downcast_raw(&self, id: TypeId) -> Option<*const ()> { + if id == TypeId::of::<Self>() { + Some(self as *const Self as *const ()) + } else { + None + } + } +} + +impl dyn Subscriber { + /// Returns `true` if this `Subscriber` is the same type as `T`. + pub fn is<T: Any>(&self) -> bool { + self.downcast_ref::<T>().is_some() + } + + /// Returns some reference to this `Subscriber` value if it is of type `T`, + /// or `None` if it isn't. + pub fn downcast_ref<T: Any>(&self) -> Option<&T> { + unsafe { + let raw = self.downcast_raw(TypeId::of::<T>())?; + if raw.is_null() { + None + } else { + Some(&*(raw as *const _)) + } + } + } +} + +/// Indicates a [`Subscriber`]'s interest in a particular callsite. +/// +/// `Subscriber`s return an `Interest` from their [`register_callsite`] methods +/// in order to determine whether that span should be enabled or disabled. +/// +/// [`Subscriber`]: ../trait.Subscriber.html +/// [`register_callsite`]: ../trait.Subscriber.html#method.register_callsite +#[derive(Clone, Debug)] +pub struct Interest(InterestKind); + +#[derive(Copy, Clone, Debug, Eq, PartialEq, Ord, PartialOrd)] +enum InterestKind { + Never = 0, + Sometimes = 1, + Always = 2, +} + +impl Interest { + /// Returns an `Interest` indicating that the subscriber is never interested + /// in being notified about a callsite. + /// + /// If all active subscribers are `never()` interested in a callsite, it will + /// be completely disabled unless a new subscriber becomes active. + #[inline] + pub fn never() -> Self { + Interest(InterestKind::Never) + } + + /// Returns an `Interest` indicating the subscriber is sometimes interested + /// in being notified about a callsite. + /// + /// If all active subscribers are `sometimes` or `never` interested in a + /// callsite, the currently active subscriber will be asked to filter that + /// callsite every time it creates a span. This will be the case until a new + /// subscriber expresses that it is `always` interested in the callsite. + #[inline] + pub fn sometimes() -> Self { + Interest(InterestKind::Sometimes) + } + + /// Returns an `Interest` indicating the subscriber is always interested in + /// being notified about a callsite. + /// + /// If any subscriber expresses that it is `always()` interested in a given + /// callsite, then the callsite will always be enabled. + #[inline] + pub fn always() -> Self { + Interest(InterestKind::Always) + } + + /// Returns `true` if the subscriber is never interested in being notified + /// about this callsite. + #[inline] + pub fn is_never(&self) -> bool { + match self.0 { + InterestKind::Never => true, + _ => false, + } + } + + /// Returns `true` if the subscriber is sometimes interested in being notified + /// about this callsite. + #[inline] + pub fn is_sometimes(&self) -> bool { + match self.0 { + InterestKind::Sometimes => true, + _ => false, + } + } + + /// Returns `true` if the subscriber is always interested in being notified + /// about this callsite. + #[inline] + pub fn is_always(&self) -> bool { + match self.0 { + InterestKind::Always => true, + _ => false, + } + } + + /// Returns the common interest between these two Interests. + /// + /// If both interests are the same, this propagates that interest. + /// Otherwise, if they differ, the result must always be + /// `Interest::sometimes` --- if the two subscribers differ in opinion, we + /// will have to ask the current subscriber what it thinks, no matter what. + pub(crate) fn and(self, rhs: Interest) -> Self { + if self.0 == rhs.0 { + self + } else { + Interest::sometimes() + } + } +} diff --git a/third_party/rust/tracing-core/tests/common/mod.rs b/third_party/rust/tracing-core/tests/common/mod.rs new file mode 100644 index 0000000000..3420f0b899 --- /dev/null +++ b/third_party/rust/tracing-core/tests/common/mod.rs @@ -0,0 +1,30 @@ +use tracing_core::{metadata::Metadata, span, subscriber::Subscriber, Event}; + +pub struct TestSubscriberA; +impl Subscriber for TestSubscriberA { + fn enabled(&self, _: &Metadata<'_>) -> bool { + true + } + fn new_span(&self, _: &span::Attributes<'_>) -> span::Id { + span::Id::from_u64(1) + } + fn record(&self, _: &span::Id, _: &span::Record<'_>) {} + fn record_follows_from(&self, _: &span::Id, _: &span::Id) {} + fn event(&self, _: &Event<'_>) {} + fn enter(&self, _: &span::Id) {} + fn exit(&self, _: &span::Id) {} +} +pub struct TestSubscriberB; +impl Subscriber for TestSubscriberB { + fn enabled(&self, _: &Metadata<'_>) -> bool { + true + } + fn new_span(&self, _: &span::Attributes<'_>) -> span::Id { + span::Id::from_u64(1) + } + fn record(&self, _: &span::Id, _: &span::Record<'_>) {} + fn record_follows_from(&self, _: &span::Id, _: &span::Id) {} + fn event(&self, _: &Event<'_>) {} + fn enter(&self, _: &span::Id) {} + fn exit(&self, _: &span::Id) {} +} diff --git a/third_party/rust/tracing-core/tests/dispatch.rs b/third_party/rust/tracing-core/tests/dispatch.rs new file mode 100644 index 0000000000..7184fc9f33 --- /dev/null +++ b/third_party/rust/tracing-core/tests/dispatch.rs @@ -0,0 +1,57 @@ +mod common; + +use common::*; +use tracing_core::dispatcher::*; + +#[cfg(feature = "std")] +#[test] +fn set_default_dispatch() { + set_global_default(Dispatch::new(TestSubscriberA)).expect("global dispatch set failed"); + get_default(|current| { + assert!( + current.is::<TestSubscriberA>(), + "global dispatch get failed" + ) + }); + + let guard = set_default(&Dispatch::new(TestSubscriberB)); + get_default(|current| assert!(current.is::<TestSubscriberB>(), "set_default get failed")); + + // Drop the guard, setting the dispatch back to the global dispatch + drop(guard); + + get_default(|current| { + assert!( + current.is::<TestSubscriberA>(), + "global dispatch get failed" + ) + }); +} + +#[cfg(feature = "std")] +#[test] +fn nested_set_default() { + let _guard = set_default(&Dispatch::new(TestSubscriberA)); + get_default(|current| { + assert!( + current.is::<TestSubscriberA>(), + "set_default for outer subscriber failed" + ) + }); + + let inner_guard = set_default(&Dispatch::new(TestSubscriberB)); + get_default(|current| { + assert!( + current.is::<TestSubscriberB>(), + "set_default inner subscriber failed" + ) + }); + + drop(inner_guard); + get_default(|current| { + assert!( + current.is::<TestSubscriberA>(), + "set_default outer subscriber failed" + ) + }); +} diff --git a/third_party/rust/tracing-core/tests/global_dispatch.rs b/third_party/rust/tracing-core/tests/global_dispatch.rs new file mode 100644 index 0000000000..d430ac6182 --- /dev/null +++ b/third_party/rust/tracing-core/tests/global_dispatch.rs @@ -0,0 +1,34 @@ +mod common; + +use common::*; +use tracing_core::dispatcher::*; +#[test] +fn global_dispatch() { + set_global_default(Dispatch::new(TestSubscriberA)).expect("global dispatch set failed"); + get_default(|current| { + assert!( + current.is::<TestSubscriberA>(), + "global dispatch get failed" + ) + }); + + #[cfg(feature = "std")] + with_default(&Dispatch::new(TestSubscriberB), || { + get_default(|current| { + assert!( + current.is::<TestSubscriberB>(), + "thread-local override of global dispatch failed" + ) + }); + }); + + get_default(|current| { + assert!( + current.is::<TestSubscriberA>(), + "reset to global override failed" + ) + }); + + set_global_default(Dispatch::new(TestSubscriberA)) + .expect_err("double global dispatch set succeeded"); +} diff --git a/third_party/rust/tracing-core/tests/macros.rs b/third_party/rust/tracing-core/tests/macros.rs new file mode 100644 index 0000000000..ee9007eeeb --- /dev/null +++ b/third_party/rust/tracing-core/tests/macros.rs @@ -0,0 +1,48 @@ +use tracing_core::{ + callsite::Callsite, + metadata, + metadata::{Kind, Level, Metadata}, + subscriber::Interest, +}; + +#[test] +fn metadata_macro_api() { + // This test should catch any inadvertent breaking changes + // caused by changes to the macro. + struct TestCallsite; + + impl Callsite for TestCallsite { + fn set_interest(&self, _: Interest) { + unimplemented!("test") + } + fn metadata(&self) -> &Metadata<'_> { + unimplemented!("test") + } + } + + static CALLSITE: TestCallsite = TestCallsite; + let _metadata = metadata! { + name: "test_metadata", + target: "test_target", + level: Level::DEBUG, + fields: &["foo", "bar", "baz"], + callsite: &CALLSITE, + kind: Kind::SPAN, + }; + let _metadata = metadata! { + name: "test_metadata", + target: "test_target", + level: Level::TRACE, + fields: &[], + callsite: &CALLSITE, + kind: Kind::EVENT, + }; + let _metadata = metadata! { + name: "test_metadata", + target: "test_target", + level: Level::INFO, + fields: &[], + callsite: &CALLSITE, + kind: Kind::EVENT + }; +} diff --git a/third_party/rust/tracing/.cargo-checksum.json b/third_party/rust/tracing/.cargo-checksum.json new file mode 100644 index 0000000000..51b9e3ffd2 --- /dev/null +++ b/third_party/rust/tracing/.cargo-checksum.json @@ -0,0 +1 @@ +{"files":{"CHANGELOG.md":"31b10e6cb5c73a58c5181b37d6595832ccc98318a66f2368561b34d9de276b4a","Cargo.toml":"dfa3ce66aa1c75c611d7e35f9e6e7cdfcb2600a5975e561bcdde2437e355baa1","LICENSE":"898b1ae9821e98daf8964c8d6c7f61641f5f5aa78ad500020771c0939ee0dea1","README.md":"00f72d1c89ccf8036512d17a761ddfea2b7481b93f569c5c542d5ee93680945a","benches/no_subscriber.rs":"799c293113c78255e1cb45eec3656ee85c0f8910458bc3412f3175c44c2bff46","benches/subscriber.rs":"066a69119ffc8dc5ccf2801b0d75fb73cbd563dbaadb824121b9a68301a68a4e","src/dispatcher.rs":"8279c019ecceae81e47407323cebe8f7a017abbf4fd6b5314fb88b7b1c9ec26e","src/field.rs":"f5537ea28cc98850a27f86dc6b937e8baff40869b8999b17751ae3f559500ab0","src/instrument.rs":"fe0a173f404b970f0ce78785f151f56a8f53ded97a9ac56214864f7670527a9d","src/level_filters.rs":"8b81db76629b00a802b40a91f4a617b97a6f78b3d9fda233b6d9ec99ecb4bb8a","src/lib.rs":"46d4f3e75506c793921ef026fa7a4d2a7604351790ba9d264f973fe5cd863fe6","src/macros.rs":"aba201cd59e0ff119794b1af6774db678d556e18ddedb4a39415680e8fc20fdb","src/span.rs":"24304f752eb893aa912bcf73ac748f6df679327d5a75ba4a052bc91349e1c3b4","src/stdlib.rs":"248514a9bae6106e436358aee44c92abf8e7f79022895c4a25136ddef211d198","src/subscriber.rs":"4d489dfa55b29db439b447bb42eedd5fa030579634b9f403603afb0055fb9371","tests/event.rs":"7c043893e2ec6202906043ac0a2b9433b53ba6156b59afdd264bf4b9e38fc712","tests/filter_caching_is_lexically_scoped.rs":"0845255a0cf0b3288f8d641fd7d72277051b759fdbce6ff24e266523219ee68c","tests/filters_are_not_reevaluated_for_the_same_span.rs":"d3287dabe73e321870128e87b4084e20548ec18964004cd73cc3ca6383b73c26","tests/filters_are_reevaluated_for_different_call_sites.rs":"98c891a0ebd8c2297c9f4a38a7a0406b0a55757f99cc0deea968929d2a998092","tests/filters_dont_leak.rs":"f302ea2ba976f32400206b81a8de6110aa53a4d4555cd4c284242d0417220dab","tests/macro_imports.rs":"d5de857162185d4a2384f3cb644bfcf76c7f5c1a3b5f72bfa0d2620ac6e3873c","tests/macros.rs":"846a3ce9fbd3f781000b8557485b5dc99f8ff89915e602d4e0c17e3775a50627","tests/max_level_hint.rs":"973124e340f6250ecb2ef8a8e5602623702ddfc75885187b15107accfb378e08","tests/multiple_max_level_hints.rs":"c8339fe81dafdc89ab4a86658be2a44d0ddd70d639522a76cd273f03f563d09c","tests/span.rs":"399615f8a2d8e2f4cce9c63adb0c1f2bbf7eaa70347adb3dc1e4c5ba3522f449","tests/subscriber.rs":"51035f71f9642dea4c5b9348691d47611b1d77fe78dd217931187f7b7549e5db","tests/support/event.rs":"ffcfa68f305782b393bb30ac4514308751757d2d81001ef5e774588141b595db","tests/support/field.rs":"bc221de91feb5f6705fedf1440fb6fccc5d7e1e0906c8a8d01a3029b1af77054","tests/support/metadata.rs":"408f9cb169e7a9330f1db0db25bdff7eaa8580143c99b3aca0d3653d8e155ea8","tests/support/mod.rs":"c67ea2e17f9cf8642069972ee6b02acd23e6d782a4382b57828810d3130de24d","tests/support/span.rs":"769690c93c2766a7a3ba683c59c41ccbd24e183d14e8151f028960785918e636","tests/support/subscriber.rs":"f51424720f46a73fc6b65a540b9a4653473ffeca1f58367e6f98744268c49584"},"package":"b0987850db3733619253fe60e17cb59b82d37c7e6c0236bb81e4d6b87c879f27"}
\ No newline at end of file diff --git a/third_party/rust/tracing/CHANGELOG.md b/third_party/rust/tracing/CHANGELOG.md new file mode 100644 index 0000000000..0a6c648e5c --- /dev/null +++ b/third_party/rust/tracing/CHANGELOG.md @@ -0,0 +1,368 @@ +# 0.1.21 (September 28, 2020) + +### Fixed + +- Incorrect inlining of `Span::new`, `Span::new_root`, and `Span::new_child_of`, + which could result in `dispatcher::get_default` being inlined at the callsite + ([#994]) +- Regression where using a struct field as a span or event field when other + fields on that struct are borrowed mutably would fail to compile ([#987]) + +### Changed + +- Updated `tracing-core` to 0.1.17 ([#992]) + +### Added + +- `Instrument` trait and `Instrumented` type for attaching a `Span` to a + `Future` ([#808]) +- `Copy` implementations for `Level` and `LevelFilter` ([#992]) +- Multiple documentation fixes and improvements ([#964], [#980], [#981]) + +Thanks to @nagisa, and new contributors @SecurityInsanity, @froydnj, @jyn514 and +@TaKO8Ki for contributing to this release! + +[#994]: https://github.com/tokio-rs/tracing/pull/994 +[#992]: https://github.com/tokio-rs/tracing/pull/992 +[#987]: https://github.com/tokio-rs/tracing/pull/987 +[#980]: https://github.com/tokio-rs/tracing/pull/980 +[#981]: https://github.com/tokio-rs/tracing/pull/981 +[#964]: https://github.com/tokio-rs/tracing/pull/964 +[#808]: https://github.com/tokio-rs/tracing/pull/808 + +# 0.1.20 (August 24, 2020) + +### Changed + +- Significantly reduced assembly generated by macro invocations (#943) +- Updated `tracing-core` to 0.1.15 (#943) + +### Added + +- Documented minimum supported Rust version policy (#941) + +# 0.1.19 (August 10, 2020) + +### Fixed + +- Updated `tracing-core` to fix incorrect calculation of the global max level + filter (#908) + +### Added + +- **attributes**: Support for using `self` in field expressions when + instrumenting `async-trait` functions (#875) +- Several documentation improvements (#832, #881, #896, #897, #911, #913) + +Thanks to @anton-dutov, @nightmared, @mystor, and @toshokan for contributing to +this release! + +# 0.1.18 (July 31, 2020) + +### Fixed + +- Fixed a bug where `LevelFilter::OFF` (and thus also the `static_max_level_off` + feature flag) would enable *all* traces, rather than *none* (#853) +- **log**: Fixed `tracing` macros and `Span`s not checking `log::max_level` + before emitting `log` records (#870) + +### Changed + +- **macros**: Macros now check the global max level (`LevelFilter::current`) + before the per-callsite cache when determining if a span or event is enabled. + This significantly improves performance in some use cases (#853) +- **macros**: Simplified the code generated by macro expansion significantly, + which may improve compile times and/or `rustc` optimizatation of surrounding + code (#869, #869) +- **macros**: Macros now check the static max level before checking any runtime + filtering, improving performance when a span or event is disabled by a + `static_max_level_XXX` feature flag (#868) +- `LevelFilter` is now a re-export of the `tracing_core::LevelFilter` type, it + can now be used interchangably with the versions in `tracing-core` and + `tracing-subscriber` (#853) +- Significant performance improvements when comparing `LevelFilter`s and + `Level`s (#853) +- Updated the minimum `tracing-core` dependency to 0.1.12 (#853) + +### Added + +- **macros**: Quoted string literals may now be used as field names, to allow + fields whose names are not valid Rust identifiers (#790) +- **docs**: Several documentation improvements (#850, #857, #841) +- `LevelFilter::current()` function, which returns the highest level that any + subscriber will enable (#853) +- `Subscriber::max_level_hint` optional trait method, for setting the value + returned by `LevelFilter::current()` (#853) + +Thanks to new contributors @cuviper, @ethanboxx, @ben0x539, @dignati, +@colelawrence, and @rbtcollins for helping out with this release! + +# 0.1.17 (July 22, 2020) + +### Changed + +- **log**: Moved verbose span enter/exit log records to "tracing::span::active" + target, allowing them to be filtered separately (#833) +- **log**: All span lifecycle log records without fields now have the `Trace` + log filter, to guard against `log` users enabling them by default with blanket + level filtering (#833) + +### Fixed + +- **log**/**macros**: Fixed missing implicit imports of the + `tracing::field::debug` and `tracing::field::display` functions inside the + macros when the "log" feature is enabled (#835) + +# 0.1.16 (July 8, 2020) + +### Added + +- **attributes**: Support for arbitrary expressions as fields in `#[instrument]` (#672) +- **attributes**: `#[instrument]` now emits a compiler warning when ignoring unrecognized + input (#672, #786) +- Improved documentation on using `tracing` in async code (#769) + +### Changed + +- Updated `tracing-core` dependency to 0.1.11 + +### Fixed + +- **macros**: Excessive monomorphization in macros, which could lead to + longer compilation times (#787) +- **log**: Compiler warnings in macros when `log` or `log-always` features + are enabled (#753) +- Compiler error when `tracing-core/std` feature is enabled but `tracing/std` is + not (#760) + +Thanks to @nagisa for contributing to this release! + +# 0.1.15 (June 2, 2020) + +### Changed + +- **macros**: Replaced use of legacy `local_inner_macros` with `$crate::` (#740) + +### Added + +- Docs fixes and improvements (#742, #731, #730) + +Thanks to @bnjjj, @blaenk, and @LukeMathWalker for contributing to this release! + +# 0.1.14 (May 14, 2020) + +### Added + +- **log**: When using the [`log`] compatibility feature alongside a `tracing` + `Subscriber`, log records for spans now include span IDs (#613) +- **attributes**: Support for using `#[instrument]` on methods that are part of + [`async-trait`] trait implementations (#711) +- **attributes**: Optional `#[instrument(err)]` argument to automatically emit + an event if an instrumented function returns `Err` (#637) +- Added `#[must_use]` attribute to the guard returned by + `subscriber::set_default` (#685) + +### Changed + +- **log**: Made [`log`] records emitted by spans much less noisy when span IDs are + not available (#613) + +### Fixed + +- Several typos in the documentation (#656, #710, #715) + +Thanks to @FintanH, @shepmaster, @inanna-malick, @zekisharif, @bkchr, @majecty, +@ilana and @nightmared for contributing to this release! + +[`async-trait`]: https://crates.io/crates/async-trait +[`log`]: https://crates.io/crates/log + +# 0.1.13 (February 26, 2019) + +### Added + +- **field**: `field::Empty` type for declaring empty fields whose values will be + recorded later (#548) +- **field**: `field::Value` implementations for `Wrapping` and `NonZero*` + numbers (#538) +- **attributes**: Support for adding arbitrary literal fields to spans generated + by `#[instrument]` (#569) +- **attributes**: `#[instrument]` now emits a helpful compiler error when + attempting to skip a function parameter (#600) + +### Changed + +- **attributes**: The `#[instrument]` attribute was placed under an on-by-default + feature flag "attributes" (#603) + +### Fixed + +- Broken and unresolvable links in RustDoc (#595) + +Thanks to @oli-cosmian and @Kobzol for contributing to this release! + +# 0.1.12 (January 11, 2019) + +### Added + +- `Span::with_subscriber` method to access the subscriber that tracks a `Span` + (#503) +- API documentation now shows which features are required by feature-flagged + items (#523) +- Improved README examples (#496) +- Documentation links to related crates (#507) + +# 0.1.11 (December 20, 2019) + +### Added + +- `Span::is_none` method (#475) +- `LevelFilter::into_level` method (#470) +- `LevelFilter::from_level` function and `From<Level>` impl (#471) +- Documented minimum supported Rust version (#482) + +### Fixed + +- Incorrect parameter type to `Span::follows_from` that made it impossible to + call (#467) +- Missing whitespace in `log` records generated when enabling the `log` feature + flag (#484) +- Typos and missing links in documentation (#405, #423, #439) + +# 0.1.10 (October 23, 2019) + +### Added + +- Support for destructuring in arguments to `#[instrument]`ed functions (#397) +- Generated field for `self` parameters when `#[instrument]`ing methods (#397) +- Optional `skip` argument to `#[instrument]` for excluding function parameters + from generated spans (#359) +- Added `dispatcher::set_default` and `subscriber::set_default` APIs, which + return a drop guard (#388) + +### Fixed + +- Some minor documentation errors (#356, #370) + +# 0.1.9 (September 13, 2019) + +### Fixed + +- Fixed `#[instrument]`ed async functions not compiling on `nightly-2019-09-11` + or newer (#342) + +### Changed + +- Significantly reduced performance impact of skipped spans and events when a + `Subscriber` is not in use (#326) +- The `log` feature will now only cause `tracing` spans and events to emit log + records when a `Subscriber` is not in use (#346) + +### Added + +- Added support for overriding the name of the span generated by `#[instrument]` + (#330) +- `log-always` feature flag to emit log records even when a `Subscriber` is set + (#346) + +# 0.1.8 (September 3, 2019) + +### Changed + +- Reorganized and improved API documentation (#317) + +### Removed + +- Dev-dependencies on `ansi_term` and `humantime` crates, which were used only + for examples (#316) + +# 0.1.7 (August 30, 2019) + +### Changed + +- New (curly-brace free) event message syntax to place the message in the first + field rather than the last (#309) + +### Fixed + +- Fixed a regression causing macro stack exhaustion when the `log` feature flag + is enabled (#304) + +# 0.1.6 (August 20, 2019) + +### Added + +- `std::error::Error` as a new primitive type (#277) +- Support for mixing key-value fields and `format_args` messages without curly + braces as delimiters (#288) + +### Changed + +- `tracing-core` dependency to 0.1.5 (#294) +- `tracing-attributes` dependency to 0.1.2 (#297) + +# 0.1.5 (August 9, 2019) + +### Added + +- Support for `no-std` + `liballoc` (#263) + +### Changed + +- Using the `#[instrument]` attribute on `async fn`s no longer requires a + feature flag (#258) + +### Fixed + +- The `#[instrument]` macro now works on generic functions (#262) + +# 0.1.4 (August 8, 2019) + +### Added + +- `#[instrument]` attribute for automatically adding spans to functions (#253) + +# 0.1.3 (July 11, 2019) + +### Added + +- Log messages when a subscriber indicates that a span has closed, when the + `log` feature flag is enabled (#180). + +### Changed + +- `tracing-core` minimum dependency version to 0.1.2 (#174). + +### Fixed + +- Fixed an issue where event macro invocations with a single field, using local + variable shorthand, would recur infinitely (#166). +- Fixed uses of deprecated `tracing-core` APIs (#174). + +# 0.1.2 (July 6, 2019) + +### Added + +- `Span::none()` constructor, which does not require metadata and + returns a completely empty span (#147). +- `Span::current()` function, returning the current span if it is + known to the subscriber (#148). + +### Fixed + +- Broken macro imports when used prefixed with `tracing::` (#152). + +# 0.1.1 (July 3, 2019) + +### Changed + +- `cfg_if` dependency to 0.1.9. + +### Fixed + +- Compilation errors when the `log` feature is enabled (#131). +- Unclear wording and typos in documentation (#124, #128, #142). + +# 0.1.0 (June 27, 2019) + +- Initial release diff --git a/third_party/rust/tracing/Cargo.toml b/third_party/rust/tracing/Cargo.toml new file mode 100644 index 0000000000..94b5916458 --- /dev/null +++ b/third_party/rust/tracing/Cargo.toml @@ -0,0 +1,88 @@ +# THIS FILE IS AUTOMATICALLY GENERATED BY CARGO +# +# When uploading crates to the registry Cargo will automatically +# "normalize" Cargo.toml files for maximal compatibility +# with all versions of Cargo and also rewrite `path` dependencies +# to registry (e.g., crates.io) dependencies +# +# If you believe there's an error in this file please file an +# issue against the rust-lang/cargo repository. If you're +# editing this file be aware that the upstream Cargo.toml +# will likely look very different (and much more reasonable) + +[package] +edition = "2018" +name = "tracing" +version = "0.1.21" +authors = ["Eliza Weisman <eliza@buoyant.io>", "Tokio Contributors <team@tokio.rs>"] +description = "Application-level tracing for Rust.\n" +homepage = "https://tokio.rs" +readme = "README.md" +keywords = ["logging", "tracing", "metrics", "async"] +categories = ["development-tools::debugging", "development-tools::profiling", "asynchronous", "no-std"] +license = "MIT" +repository = "https://github.com/tokio-rs/tracing" +[package.metadata.docs.rs] +all-features = true +rustdoc-args = ["--cfg", "docsrs"] + +[[bench]] +name = "subscriber" +harness = false + +[[bench]] +name = "no_subscriber" +harness = false +[dependencies.cfg-if] +version = "0.1.10" + +[dependencies.log] +version = "0.4" +optional = true + +[dependencies.pin-project-lite] +version = "0.1" + +[dependencies.tracing-attributes] +version = "0.1.10" +optional = true + +[dependencies.tracing-core] +version = "0.1.17" +default-features = false +[dev-dependencies.criterion] +version = "0.3" +default_features = false + +[dev-dependencies.futures] +version = "0.1" + +[dev-dependencies.log] +version = "0.4" + +[dev-dependencies.tokio] +version = "0.2.21" +features = ["rt-core"] + +[features] +async-await = [] +attributes = ["tracing-attributes"] +default = ["std", "attributes"] +log-always = ["log"] +max_level_debug = [] +max_level_error = [] +max_level_info = [] +max_level_off = [] +max_level_trace = [] +max_level_warn = [] +release_max_level_debug = [] +release_max_level_error = [] +release_max_level_info = [] +release_max_level_off = [] +release_max_level_trace = [] +release_max_level_warn = [] +std = ["tracing-core/std"] +[target."cfg(target_arch = \"wasm32\")".dev-dependencies.wasm-bindgen-test] +version = "^0.3" +[badges.maintenance] +status = "actively-developed" diff --git a/third_party/rust/tracing/LICENSE b/third_party/rust/tracing/LICENSE new file mode 100644 index 0000000000..cdb28b4b56 --- /dev/null +++ b/third_party/rust/tracing/LICENSE @@ -0,0 +1,25 @@ +Copyright (c) 2019 Tokio Contributors + +Permission is hereby granted, free of charge, to any +person obtaining a copy of this software and associated +documentation files (the "Software"), to deal in the +Software without restriction, including without +limitation the rights to use, copy, modify, merge, +publish, distribute, sublicense, and/or sell copies of +the Software, and to permit persons to whom the Software +is furnished to do so, subject to the following +conditions: + +The above copyright notice and this permission notice +shall be included in all copies or substantial portions +of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF +ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED +TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A +PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT +SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY +CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION +OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR +IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER +DEALINGS IN THE SOFTWARE. diff --git a/third_party/rust/tracing/README.md b/third_party/rust/tracing/README.md new file mode 100644 index 0000000000..e524235feb --- /dev/null +++ b/third_party/rust/tracing/README.md @@ -0,0 +1,444 @@ +![Tracing — Structured, application-level diagnostics][splash] + +[splash]: https://raw.githubusercontent.com/tokio-rs/tracing/master/assets/splash.svg + +# tracing + +Application-level tracing for Rust. + +[![Crates.io][crates-badge]][crates-url] +[![Documentation][docs-badge]][docs-url] +[![Documentation (master)][docs-master-badge]][docs-master-url] +[![MIT licensed][mit-badge]][mit-url] +[![Build Status][actions-badge]][actions-url] +[![Discord chat][discord-badge]][discord-url] + +[Documentation][docs-url] | [Chat][discord-url] + +[crates-badge]: https://img.shields.io/crates/v/tracing.svg +[crates-url]: https://crates.io/crates/tracing/0.1.21 +[docs-badge]: https://docs.rs/tracing/badge.svg +[docs-url]: https://docs.rs/tracing/0.1.21 +[docs-master-badge]: https://img.shields.io/badge/docs-master-blue +[docs-master-url]: https://tracing-rs.netlify.com/tracing +[mit-badge]: https://img.shields.io/badge/license-MIT-blue.svg +[mit-url]: LICENSE +[actions-badge]: https://github.com/tokio-rs/tracing/workflows/CI/badge.svg +[actions-url]:https://github.com/tokio-rs/tracing/actions?query=workflow%3ACI +[discord-badge]: https://img.shields.io/discord/500028886025895936?logo=discord&label=discord&logoColor=white +[discord-url]: https://discord.gg/EeF3cQw + +## Overview + +`tracing` is a framework for instrumenting Rust programs to collect +structured, event-based diagnostic information. + +In asynchronous systems like Tokio, interpreting traditional log messages can +often be quite challenging. Since individual tasks are multiplexed on the same +thread, associated events and log lines are intermixed making it difficult to +trace the logic flow. `tracing` expands upon logging-style diagnostics by +allowing libraries and applications to record structured events with additional +information about *temporality* and *causality* — unlike a log message, a span +in `tracing` has a beginning and end time, may be entered and exited by the +flow of execution, and may exist within a nested tree of similar spans. In +addition, `tracing` spans are *structured*, with the ability to record typed +data as well as textual messages. + +The `tracing` crate provides the APIs necessary for instrumenting libraries +and applications to emit trace data. + +*Compiler support: [requires `rustc` 1.40+][msrv]* + +[msrv]: #supported-rust-versions + +## Usage + +(The examples below are borrowed from the `log` crate's yak-shaving +[example](https://docs.rs/log/0.4.10/log/index.html#examples), modified to +idiomatic `tracing`.) + +### In Applications + +In order to record trace events, executables have to use a `Subscriber` +implementation compatible with `tracing`. A `Subscriber` implements a way of +collecting trace data, such as by logging it to standard output. [`tracing_subscriber`](https://docs.rs/tracing-subscriber/)'s +[`fmt` module](https://docs.rs/tracing-subscriber/0.2.0-alpha.2/tracing_subscriber/fmt/index.html) provides reasonable defaults. +Additionally, `tracing-subscriber` is able to consume messages emitted by `log`-instrumented libraries and modules. + +The simplest way to use a subscriber is to call the `set_global_default` function. + +```rust +use tracing::{info, Level}; +use tracing_subscriber::FmtSubscriber; + +fn main() { + // a builder for `FmtSubscriber`. + let subscriber = FmtSubscriber::builder() + // all spans/events with a level higher than TRACE (e.g, debug, info, warn, etc.) + // will be written to stdout. + .with_max_level(Level::TRACE) + // completes the builder. + .finish(); + + tracing::subscriber::set_global_default(subscriber) + .expect("setting default subscriber failed"); + + let number_of_yaks = 3; + // this creates a new event, outside of any spans. + info!(number_of_yaks, "preparing to shave yaks"); + + let number_shaved = yak_shave::shave_all(number_of_yaks); + info!( + all_yaks_shaved = number_shaved == number_of_yaks, + "yak shaving completed." + ); +} +``` + +```toml +[dependencies] +tracing = "0.1" +tracing-subscriber = "0.2.0" +``` + +This subscriber will be used as the default in all threads for the remainder of the duration +of the program, similar to how loggers work in the `log` crate. + +In addition, you can locally override the default subscriber. For example: + +```rust +use tracing::{info, Level}; +use tracing_subscruber::FmtSubscriber; + +fn main() { + let subscriber = tracing_subscriber::FmtSubscriber::builder() + // all spans/events with a level higher than TRACE (e.g, debug, info, warn, etc.) + // will be written to stdout. + .with_max_level(Level::TRACE) + // builds the subscriber. + .finish(); + + tracing::subscriber::with_default(subscriber, || { + info!("This will be logged to stdout"); + }); + info!("This will _not_ be logged to stdout"); +} +``` + +This approach allows trace data to be collected by multiple subscribers +within different contexts in the program. Note that the override only applies to the +currently executing thread; other threads will not see the change from with_default. + +Any trace events generated outside the context of a subscriber will not be collected. + +Once a subscriber has been set, instrumentation points may be added to the +executable using the `tracing` crate's macros. + +### In Libraries + +Libraries should only rely on the `tracing` crate and use the provided macros +and types to collect whatever information might be useful to downstream consumers. + +```rust +use std::{error::Error, io}; +use tracing::{debug, error, info, span, warn, Level}; + +// the `#[tracing::instrument]` attribute creates and enters a span +// every time the instrumented function is called. The span is named after the +// the function or method. Paramaters passed to the function are recorded as fields. +#[tracing::instrument] +pub fn shave(yak: usize) -> Result<(), Box<dyn Error + 'static>> { + // this creates an event at the DEBUG level with two fields: + // - `excitement`, with the key "excitement" and the value "yay!" + // - `message`, with the key "message" and the value "hello! I'm gonna shave a yak." + // + // unlike other fields, `message`'s shorthand initialization is just the string itself. + debug!(excitement = "yay!", "hello! I'm gonna shave a yak."); + if yak == 3 { + warn!("could not locate yak!"); + // note that this is intended to demonstrate `tracing`'s features, not idiomatic + // error handling! in a library or application, you should consider returning + // a dedicated `YakError`. libraries like snafu or thiserror make this easy. + return Err(io::Error::new(io::ErrorKind::Other, "shaving yak failed!").into()); + } else { + debug!("yak shaved successfully"); + } + Ok(()) +} + +pub fn shave_all(yaks: usize) -> usize { + // Constructs a new span named "shaving_yaks" at the TRACE level, + // and a field whose key is "yaks". This is equivalent to writing: + // + // let span = span!(Level::TRACE, "shaving_yaks", yaks = yaks); + // + // local variables (`yaks`) can be used as field values + // without an assignment, similar to struct initializers. + let span = span!(Level::TRACE, "shaving_yaks", yaks); + let _enter = span.enter(); + + info!("shaving yaks"); + + let mut yaks_shaved = 0; + for yak in 1..=yaks { + let res = shave(yak); + debug!(yak, shaved = res.is_ok()); + + if let Err(ref error) = res { + // Like spans, events can also use the field initialization shorthand. + // In this instance, `yak` is the field being initalized. + error!(yak, error = error.as_ref(), "failed to shave yak!"); + } else { + yaks_shaved += 1; + } + debug!(yaks_shaved); + } + + yaks_shaved +} +``` + +```toml +[dependencies] +tracing = "0.1" +``` + +Note: Libraries should *NOT* call `set_global_default()`, as this will cause +conflicts when executables try to set the default later. + +### In Asynchronous Code + +If you are instrumenting code that make use of +[`std::future::Future`](https://doc.rust-lang.org/stable/std/future/trait.Future.html) +or async/await, be sure to use the +[`tracing-futures`](https://docs.rs/tracing-futures) crate. This is needed +because the following example _will not_ work: + +```rust +async { + let _s = span.enter(); + // ... +} +``` + +The span guard `_s` will not exit until the future generated by the `async` block is complete. +Since futures and spans can be entered and exited _multiple_ times without them completing, +the span remains entered for as long as the future exists, rather than being entered only when +it is polled, leading to very confusing and incorrect output. +For more details, see [the documentation on closing spans](https://tracing.rs/tracing/span/index.html#closing-spans). + +There are two ways to instrument asynchronous code. The first is through the +[`Future::instrument`](https://docs.rs/tracing/latest/tracing/trait.Instrument.html#method.instrument) combinator: + +```rust +use tracing::Instrument; + +let my_future = async { + // ... +}; + +my_future + .instrument(tracing::info_span!("my_future")) + .await +``` + +`Future::instrument` attaches a span to the future, ensuring that the span's lifetime +is as long as the future's. + +The second, and preferred, option is through the +[`#[instrument]`](https://docs.rs/tracing/0.1.21/tracing/attr.instrument.html) +attribute: + +```rust +use tracing::{info, instrument}; +use tokio::{io::AsyncWriteExt, net::TcpStream}; +use std::io; + +#[instrument] +async fn write(stream: &mut TcpStream) -> io::Result<usize> { + let result = stream.write(b"hello world\n").await; + info!("wrote to stream; success={:?}", result.is_ok()); + result +} +``` + +Under the hood, the `#[instrument]` macro performs the same explicit span +attachment that `Future::instrument` does. + +### Concepts + +This crate provides macros for creating `Span`s and `Event`s, which represent +periods of time and momentary events within the execution of a program, +respectively. + +As a rule of thumb, _spans_ should be used to represent discrete units of work +(e.g., a given request's lifetime in a server) or periods of time spent in a +given context (e.g., time spent interacting with an instance of an external +system, such as a database). In contrast, _events_ should be used to represent +points in time within a span — a request returned with a given status code, +_n_ new items were taken from a queue, and so on. + +`Span`s are constructed using the `span!` macro, and then _entered_ +to indicate that some code takes place within the context of that `Span`: + +```rust +use tracing::{span, Level}; + +// Construct a new span named "my span". +let mut span = span!(Level::INFO, "my span"); +span.in_scope(|| { + // Any trace events in this closure or code called by it will occur within + // the span. +}); +// Dropping the span will close it, indicating that it has ended. +``` + +The [`#[instrument]`](https://docs.rs/tracing/0.1.21/tracing/attr.instrument.html) attribute macro +can reduce some of this boilerplate: + +```rust +use tracing::{instrument}; + +#[instrument] +pub fn my_function(my_arg: usize) { + // This event will be recorded inside a span named `my_function` with the + // field `my_arg`. + tracing::info!("inside my_function!"); + // ... +} +``` + +The `Event` type represent an event that occurs instantaneously, and is +essentially a `Span` that cannot be entered. They are created using the `event!` +macro: + +```rust +use tracing::{event, Level}; + +event!(Level::INFO, "something has happened!"); +``` + +Users of the [`log`] crate should note that `tracing` exposes a set of macros for +creating `Event`s (`trace!`, `debug!`, `info!`, `warn!`, and `error!`) which may +be invoked with the same syntax as the similarly-named macros from the `log` +crate. Often, the process of converting a project to use `tracing` can begin +with a simple drop-in replacement. + +## Supported Rust Versions + +Tracing is built against the latest stable release. The minimum supported +version is 1.40. The current Tracing version is not guaranteed to build on Rust +versions earlier than the minimum supported version. + +Tracing follows the same compiler support policies as the rest of the Tokio +project. The current stable Rust compiler and the three most recent minor +versions before it will always be supported. For example, if the current stable +compiler version is 1.45, the minimum supported version will not be increased +past 1.42, three minor versions prior. Increasing the minimum supported compiler +version is not considered a semver breaking change as long as doing so complies +with this policy. + +## Ecosystem + +### Related Crates + +In addition to `tracing` and `tracing-core`, the [`tokio-rs/tracing`] repository +contains several additional crates designed to be used with the `tracing` ecosystem. +This includes a collection of `Subscriber` implementations, as well as utility +and adapter crates to assist in writing `Subscriber`s and instrumenting +applications. + +In particular, the following crates are likely to be of interest: + +- [`tracing-futures`] provides a compatibility layer with the `futures` + crate, allowing spans to be attached to `Future`s, `Stream`s, and `Executor`s. +- [`tracing-subscriber`] provides `Subscriber` implementations and + utilities for working with `Subscriber`s. This includes a [`FmtSubscriber`] + `FmtSubscriber` for logging formatted trace data to stdout, with similar + filtering and formatting to the [`env_logger`] crate. +- [`tracing-log`] provides a compatibility layer with the [`log`] crate, + allowing log messages to be recorded as `tracing` `Event`s within the + trace tree. This is useful when a project using `tracing` have + dependencies which use `log`. Note that if you're using + `tracing-subscriber`'s `FmtSubscriber`, you don't need to depend on + `tracing-log` directly. + +Additionally, there are also several third-party crates which are not +maintained by the `tokio` project. These include: + +- [`tracing-timing`] implements inter-event timing metrics on top of `tracing`. + It provides a subscriber that records the time elapsed between pairs of + `tracing` events and generates histograms. +- [`tracing-opentelemetry`] provides a subscriber for emitting traces to + [OpenTelemetry]-compatible distributed tracing systems. +- [`tracing-honeycomb`] Provides a layer that reports traces spanning multiple machines to [honeycomb.io]. Backed by [`tracing-distributed`]. +- [`tracing-distributed`] Provides a generic implementation of a layer that reports traces spanning multiple machines to some backend. +- [`tracing-actix`] provides `tracing` integration for the `actix` actor + framework. +- [`tracing-gelf`] implements a subscriber for exporting traces in Greylog + GELF format. +- [`tracing-coz`] provides integration with the [coz] causal profiler + (Linux-only). +- [`test-env-log`] takes care of initializing `tracing` for tests, based on + environment variables with an `env_logger` compatible syntax. +- [`tracing-unwrap`] provides convenience methods to report failed unwraps on `Result` or `Option` types to a `Subscriber`. +- [`diesel-tracing`] provides integration with [`diesel`] database connections. +- [`tracing-tracy`] provides a way to collect [Tracy] profiles in instrumented + applications. + +If you're the maintainer of a `tracing` ecosystem crate not listed above, +please let us know! We'd love to add your project to the list! + +[`tracing-timing`]: https://crates.io/crates/tracing-timing +[`tracing-opentelemetry`]: https://crates.io/crates/tracing-opentelemetry +[OpenTelemetry]: https://opentelemetry.io/ +[`tracing-honeycomb`]: https://crates.io/crates/tracing-honeycomb +[`tracing-distributed`]: https://crates.io/crates/tracing-distributed +[honeycomb.io]: https://www.honeycomb.io/ +[`tracing-actix`]: https://crates.io/crates/tracing-actix +[`tracing-gelf`]: https://crates.io/crates/tracing-gelf +[`tracing-coz`]: https://crates.io/crates/tracing-coz +[coz]: https://github.com/plasma-umass/coz +[`test-env-log`]: https://crates.io/crates/test-env-log +[`tracing-unwrap`]: https://docs.rs/tracing-unwrap +[`diesel`]: https://crates.io/crates/diesel +[`diesel-tracing`]: https://crates.io/crates/diesel-tracing +[`tracing-tracy`]: https://crates.io/crates/tracing-tracy +[Tracy]: https://github.com/wolfpld/tracy + +**Note:** that some of the ecosystem crates are currently unreleased and +undergoing active development. They may be less stable than `tracing` and +`tracing-core`. + +[`log`]: https://docs.rs/log/0.4.6/log/ +[`tokio-rs/tracing`]: https://github.com/tokio-rs/tracing +[`tracing-futures`]: https://github.com/tokio-rs/tracing/tree/master/tracing-futures +[`tracing-subscriber`]: https://github.com/tokio-rs/tracing/tree/master/tracing-subscriber +[`tracing-log`]: https://github.com/tokio-rs/tracing/tree/master/tracing-log +[`env_logger`]: https://crates.io/crates/env_logger +[`FmtSubscriber`]: https://docs.rs/tracing-subscriber/latest/tracing_subscriber/fmt/struct.Subscriber.html +[`examples`]: https://github.com/tokio-rs/tracing/tree/master/examples + +## Supported Rust Versions + +Tracing is built against the latest stable release. The minimum supported +version is 1.40. The current Tracing version is not guaranteed to build on Rust +versions earlier than the minimum supported version. + +Tracing follows the same compiler support policies as the rest of the Tokio +project. The current stable Rust compiler and the three most recent minor +versions before it will always be supported. For example, if the current stable +compiler version is 1.45, the minimum supported version will not be increased +past 1.42, three minor versions prior. Increasing the minimum supported compiler +version is not considered a semver breaking change as long as doing so complies +with this policy. + +## License + +This project is licensed under the [MIT license](LICENSE). + +### Contribution + +Unless you explicitly state otherwise, any contribution intentionally submitted +for inclusion in Tokio by you, shall be licensed as MIT, without any additional +terms or conditions. diff --git a/third_party/rust/tracing/benches/no_subscriber.rs b/third_party/rust/tracing/benches/no_subscriber.rs new file mode 100644 index 0000000000..797f258c6b --- /dev/null +++ b/third_party/rust/tracing/benches/no_subscriber.rs @@ -0,0 +1,61 @@ +use criterion::{black_box, criterion_group, criterion_main, Criterion}; +use tracing::Level; + +fn bench_no_subscriber(c: &mut Criterion) { + use std::sync::atomic::{AtomicUsize, Ordering}; + + let mut group = c.benchmark_group("no_subscriber"); + + group.bench_function("span", |b| { + b.iter(|| { + black_box(tracing::span!(Level::TRACE, "span")); + }) + }); + group.bench_function("event", |b| { + b.iter(|| { + tracing::event!(Level::TRACE, "hello"); + }) + }); + group.bench_function("relaxed_load", |b| { + let foo = AtomicUsize::new(1); + b.iter(|| black_box(foo.load(Ordering::Relaxed))); + }); + group.bench_function("acquire_load", |b| { + let foo = AtomicUsize::new(1); + b.iter(|| black_box(foo.load(Ordering::Acquire))) + }); + group.bench_function("log", |b| { + b.iter(|| { + log::log!(log::Level::Info, "log"); + }) + }); + group.finish(); +} + +fn bench_fields(c: &mut Criterion) { + let mut group = c.benchmark_group("no_subscriber_field"); + group.bench_function("span", |b| { + b.iter(|| { + black_box(tracing::span!( + Level::TRACE, + "span", + foo = tracing::field::display(format!("bar {:?}", 2)) + )); + }) + }); + group.bench_function("event", |b| { + b.iter(|| { + tracing::event!( + Level::TRACE, + foo = tracing::field::display(format!("bar {:?}", 2)) + ); + }) + }); + group.bench_function("log", |b| { + b.iter(|| log::log!(log::Level::Trace, "{}", format!("bar {:?}", 2))) + }); + group.finish(); +} + +criterion_group!(benches, bench_no_subscriber, bench_fields); +criterion_main!(benches); diff --git a/third_party/rust/tracing/benches/subscriber.rs b/third_party/rust/tracing/benches/subscriber.rs new file mode 100644 index 0000000000..0595d64222 --- /dev/null +++ b/third_party/rust/tracing/benches/subscriber.rs @@ -0,0 +1,192 @@ +extern crate criterion; +extern crate tracing; + +use criterion::{black_box, criterion_group, criterion_main, Criterion}; +use tracing::Level; + +use std::{ + fmt, + sync::{Mutex, MutexGuard}, +}; +use tracing::{field, span, Event, Id, Metadata}; + +/// A subscriber that is enabled but otherwise does nothing. +struct EnabledSubscriber; + +impl tracing::Subscriber for EnabledSubscriber { + fn new_span(&self, span: &span::Attributes<'_>) -> Id { + let _ = span; + Id::from_u64(0xDEAD_FACE) + } + + fn event(&self, event: &Event<'_>) { + let _ = event; + } + + fn record(&self, span: &Id, values: &span::Record<'_>) { + let _ = (span, values); + } + + fn record_follows_from(&self, span: &Id, follows: &Id) { + let _ = (span, follows); + } + + fn enabled(&self, metadata: &Metadata<'_>) -> bool { + let _ = metadata; + true + } + + fn enter(&self, span: &Id) { + let _ = span; + } + + fn exit(&self, span: &Id) { + let _ = span; + } +} + +/// Simulates a subscriber that records span data. +struct VisitingSubscriber(Mutex<String>); + +struct Visitor<'a>(MutexGuard<'a, String>); + +impl<'a> field::Visit for Visitor<'a> { + fn record_debug(&mut self, _field: &field::Field, value: &dyn fmt::Debug) { + use std::fmt::Write; + let _ = write!(&mut *self.0, "{:?}", value); + } +} + +impl tracing::Subscriber for VisitingSubscriber { + fn new_span(&self, span: &span::Attributes<'_>) -> Id { + let mut visitor = Visitor(self.0.lock().unwrap()); + span.record(&mut visitor); + Id::from_u64(0xDEAD_FACE) + } + + fn record(&self, _span: &Id, values: &span::Record<'_>) { + let mut visitor = Visitor(self.0.lock().unwrap()); + values.record(&mut visitor); + } + + fn event(&self, event: &Event<'_>) { + let mut visitor = Visitor(self.0.lock().unwrap()); + event.record(&mut visitor); + } + + fn record_follows_from(&self, span: &Id, follows: &Id) { + let _ = (span, follows); + } + + fn enabled(&self, metadata: &Metadata<'_>) -> bool { + let _ = metadata; + true + } + + fn enter(&self, span: &Id) { + let _ = span; + } + + fn exit(&self, span: &Id) { + let _ = span; + } +} + +const N_SPANS: usize = 100; + +fn criterion_benchmark(c: &mut Criterion) { + c.bench_function("span_no_fields", |b| { + tracing::subscriber::with_default(EnabledSubscriber, || { + b.iter(|| span!(Level::TRACE, "span")) + }); + }); + + c.bench_function("enter_span", |b| { + tracing::subscriber::with_default(EnabledSubscriber, || { + let span = span!(Level::TRACE, "span"); + #[allow(clippy::unit_arg)] + b.iter(|| black_box(span.in_scope(|| {}))) + }); + }); + + c.bench_function("span_repeatedly", |b| { + #[inline] + fn mk_span(i: u64) -> tracing::Span { + span!(Level::TRACE, "span", i = i) + } + + let n = black_box(N_SPANS); + tracing::subscriber::with_default(EnabledSubscriber, || { + b.iter(|| (0..n).fold(mk_span(0), |_, i| mk_span(i as u64))) + }); + }); + + c.bench_function("span_with_fields", |b| { + tracing::subscriber::with_default(EnabledSubscriber, || { + b.iter(|| { + span!( + Level::TRACE, + "span", + foo = "foo", + bar = "bar", + baz = 3, + quuux = tracing::field::debug(0.99) + ) + }) + }); + }); + + c.bench_function("span_with_fields_record", |b| { + let subscriber = VisitingSubscriber(Mutex::new(String::from(""))); + tracing::subscriber::with_default(subscriber, || { + b.iter(|| { + span!( + Level::TRACE, + "span", + foo = "foo", + bar = "bar", + baz = 3, + quuux = tracing::field::debug(0.99) + ) + }) + }); + }); +} + +fn bench_dispatch(c: &mut Criterion) { + let mut group = c.benchmark_group("dispatch"); + group.bench_function("no_dispatch_get_ref", |b| { + b.iter(|| { + tracing::dispatcher::get_default(|current| { + black_box(¤t); + }) + }) + }); + group.bench_function("no_dispatch_get_clone", |b| { + b.iter(|| { + let current = tracing::dispatcher::get_default(|current| current.clone()); + black_box(current); + }) + }); + group.bench_function("get_ref", |b| { + tracing::subscriber::with_default(EnabledSubscriber, || { + b.iter(|| { + tracing::dispatcher::get_default(|current| { + black_box(¤t); + }) + }) + }) + }); + group.bench_function("get_clone", |b| { + tracing::subscriber::with_default(EnabledSubscriber, || { + b.iter(|| { + let current = tracing::dispatcher::get_default(|current| current.clone()); + black_box(current); + }) + }) + }); + group.finish(); +} + +criterion_group!(benches, criterion_benchmark, bench_dispatch); +criterion_main!(benches); diff --git a/third_party/rust/tracing/src/dispatcher.rs b/third_party/rust/tracing/src/dispatcher.rs new file mode 100644 index 0000000000..4041c994fb --- /dev/null +++ b/third_party/rust/tracing/src/dispatcher.rs @@ -0,0 +1,152 @@ +//! Dispatches trace events to [`Subscriber`]s. +//! +//! The _dispatcher_ is the component of the tracing system which is responsible +//! for forwarding trace data from the instrumentation points that generate it +//! to the subscriber that collects it. +//! +//! # Using the Trace Dispatcher +//! +//! Every thread in a program using `tracing` has a _default subscriber_. When +//! events occur, or spans are created, they are dispatched to the thread's +//! current subscriber. +//! +//! ## Setting the Default Subscriber +//! +//! By default, the current subscriber is an empty implementation that does +//! nothing. To use a subscriber implementation, it must be set as the default. +//! There are two methods for doing so: [`with_default`] and +//! [`set_global_default`]. `with_default` sets the default subscriber for the +//! duration of a scope, while `set_global_default` sets a default subscriber +//! for the entire process. +//! +//! To use either of these functions, we must first wrap our subscriber in a +//! [`Dispatch`], a cloneable, type-erased reference to a subscriber. For +//! example: +//! ```rust +//! # pub struct FooSubscriber; +//! # use tracing_core::{ +//! # dispatcher, Event, Metadata, +//! # span::{Attributes, Id, Record} +//! # }; +//! # impl tracing_core::Subscriber for FooSubscriber { +//! # fn new_span(&self, _: &Attributes) -> Id { Id::from_u64(0) } +//! # fn record(&self, _: &Id, _: &Record) {} +//! # fn event(&self, _: &Event) {} +//! # fn record_follows_from(&self, _: &Id, _: &Id) {} +//! # fn enabled(&self, _: &Metadata) -> bool { false } +//! # fn enter(&self, _: &Id) {} +//! # fn exit(&self, _: &Id) {} +//! # } +//! # impl FooSubscriber { fn new() -> Self { FooSubscriber } } +//! use dispatcher::Dispatch; +//! +//! let my_subscriber = FooSubscriber::new(); +//! let my_dispatch = Dispatch::new(my_subscriber); +//! ``` +//! Then, we can use [`with_default`] to set our `Dispatch` as the default for +//! the duration of a block: +//! ```rust +//! # pub struct FooSubscriber; +//! # use tracing_core::{ +//! # dispatcher, Event, Metadata, +//! # span::{Attributes, Id, Record} +//! # }; +//! # impl tracing_core::Subscriber for FooSubscriber { +//! # fn new_span(&self, _: &Attributes) -> Id { Id::from_u64(0) } +//! # fn record(&self, _: &Id, _: &Record) {} +//! # fn event(&self, _: &Event) {} +//! # fn record_follows_from(&self, _: &Id, _: &Id) {} +//! # fn enabled(&self, _: &Metadata) -> bool { false } +//! # fn enter(&self, _: &Id) {} +//! # fn exit(&self, _: &Id) {} +//! # } +//! # impl FooSubscriber { fn new() -> Self { FooSubscriber } } +//! # let my_subscriber = FooSubscriber::new(); +//! # let my_dispatch = dispatcher::Dispatch::new(my_subscriber); +//! // no default subscriber +//! +//! # #[cfg(feature = "std")] +//! dispatcher::with_default(&my_dispatch, || { +//! // my_subscriber is the default +//! }); +//! +//! // no default subscriber again +//! ``` +//! It's important to note that `with_default` will not propagate the current +//! thread's default subscriber to any threads spawned within the `with_default` +//! block. To propagate the default subscriber to new threads, either use +//! `with_default` from the new thread, or use `set_global_default`. +//! +//! As an alternative to `with_default`, we can use [`set_global_default`] to +//! set a `Dispatch` as the default for all threads, for the lifetime of the +//! program. For example: +//! ```rust +//! # pub struct FooSubscriber; +//! # use tracing_core::{ +//! # dispatcher, Event, Metadata, +//! # span::{Attributes, Id, Record} +//! # }; +//! # impl tracing_core::Subscriber for FooSubscriber { +//! # fn new_span(&self, _: &Attributes) -> Id { Id::from_u64(0) } +//! # fn record(&self, _: &Id, _: &Record) {} +//! # fn event(&self, _: &Event) {} +//! # fn record_follows_from(&self, _: &Id, _: &Id) {} +//! # fn enabled(&self, _: &Metadata) -> bool { false } +//! # fn enter(&self, _: &Id) {} +//! # fn exit(&self, _: &Id) {} +//! # } +//! # impl FooSubscriber { fn new() -> Self { FooSubscriber } } +//! # let my_subscriber = FooSubscriber::new(); +//! # let my_dispatch = dispatcher::Dispatch::new(my_subscriber); +//! // no default subscriber +//! +//! dispatcher::set_global_default(my_dispatch) +//! // `set_global_default` will return an error if the global default +//! // subscriber has already been set. +//! .expect("global default was already set!"); +//! +//! // `my_subscriber` is now the default +//! ``` +//! <div class="information"> +//! <div class="tooltip ignore" style="">ⓘ<span class="tooltiptext">Note</span></div> +//! </div> +//! <div class="example-wrap" style="display:inline-block"> +//! <pre class="ignore" style="white-space:normal;font:inherit;"> +//! <strong>Note</strong>: The thread-local scoped dispatcher (<code>with_default</code>) +//! requires the Rust standard library. <code>no_std</code> users should +//! use <a href="fn.set_global_default.html"><code>set_global_default</code></a> +//! instead. +//! </pre></div> +//! +//! ## Accessing the Default Subscriber +//! +//! A thread's current default subscriber can be accessed using the +//! [`get_default`] function, which executes a closure with a reference to the +//! currently default `Dispatch`. This is used primarily by `tracing` +//! instrumentation. +//! +//! [`Subscriber`]: struct.Subscriber.html +//! [`with_default`]: fn.with_default.html +//! [`set_global_default`]: fn.set_global_default.html +//! [`get_default`]: fn.get_default.html +//! [`Dispatch`]: struct.Dispatch.html +#[cfg(feature = "std")] +#[cfg_attr(docsrs, doc(cfg(feature = "std")))] +pub use tracing_core::dispatcher::set_default; +#[cfg(feature = "std")] +#[cfg_attr(docsrs, doc(cfg(feature = "std")))] +pub use tracing_core::dispatcher::with_default; +#[cfg(feature = "std")] +#[cfg_attr(docsrs, doc(cfg(feature = "std")))] +pub use tracing_core::dispatcher::DefaultGuard; +pub use tracing_core::dispatcher::{ + get_default, set_global_default, Dispatch, SetGlobalDefaultError, +}; + +/// Private API for internal use by tracing's macros. +/// +/// This function is *not* considered part of `tracing`'s public API, and has no +/// stability guarantees. If you use it, and it breaks or disappears entirely, +/// don't say we didn;'t warn you. +#[doc(hidden)] +pub use tracing_core::dispatcher::has_been_set; diff --git a/third_party/rust/tracing/src/field.rs b/third_party/rust/tracing/src/field.rs new file mode 100644 index 0000000000..2514336585 --- /dev/null +++ b/third_party/rust/tracing/src/field.rs @@ -0,0 +1,62 @@ +//! Structured data associated with `Span`s and `Event`s. +pub use tracing_core::field::*; + +use crate::Metadata; + +/// Trait implemented to allow a type to be used as a field key. +/// +/// <div class="information"> +/// <div class="tooltip ignore" style="">ⓘ<span class="tooltiptext">Note</span></div> +/// </div> +/// <div class="example-wrap" style="display:inline-block"> +/// <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 {} diff --git a/third_party/rust/tracing/src/instrument.rs b/third_party/rust/tracing/src/instrument.rs new file mode 100644 index 0000000000..d1070ba8e2 --- /dev/null +++ b/third_party/rust/tracing/src/instrument.rs @@ -0,0 +1,194 @@ +use crate::stdlib::pin::Pin; +use crate::stdlib::task::{Context, Poll}; +use crate::stdlib::{future::Future, marker::Sized}; +use crate::{dispatcher, span::Span, Dispatch}; +use pin_project_lite::pin_project; + +/// Attaches spans to a `std::future::Future`. +/// +/// Extension trait allowing futures to be +/// instrumented with a `tracing` [span]. +/// +/// [span]: ../struct.Span.html +pub trait Instrument: Sized { + /// Instruments this type with the provided `Span`, returning an + /// `Instrumented` wrapper. + /// + /// The attached `Span` will be [entered] every time the instrumented `Future` is polled. + /// + /// # Examples + /// + /// Instrumenting a future: + /// + /// ```rust + /// use tracing::Instrument; + /// + /// # async fn doc() { + /// let my_future = async { + /// // ... + /// }; + /// + /// my_future + /// .instrument(tracing::info_span!("my_future")) + /// .await + /// # } + /// ``` + /// + /// [entered]: ../struct.Span.html#method.enter + fn instrument(self, span: Span) -> Instrumented<Self> { + Instrumented { inner: self, span } + } + + /// Instruments this type with the [current] `Span`, returning an + /// `Instrumented` wrapper. + /// + /// If the instrumented type is a future, stream, or sink, the attached `Span` + /// will be [entered] every time it is polled. If the instrumented type + /// is a future executor, every future spawned on that executor will be + /// instrumented by the attached `Span`. + /// + /// This can be used to propagate the current span when spawning a new future. + /// + /// # Examples + /// + /// ```rust + /// use tracing::Instrument; + /// + /// # async fn doc() { + /// let span = tracing::info_span!("my_span"); + /// let _enter = span.enter(); + /// + /// // ... + /// + /// let future = async { + /// tracing::debug!("this event will occur inside `my_span`"); + /// // ... + /// }; + /// tokio::spawn(future.in_current_span()); + /// # } + /// ``` + /// + /// [current]: ../struct.Span.html#method.current + /// [entered]: ../struct.Span.html#method.enter + #[inline] + fn in_current_span(self) -> Instrumented<Self> { + self.instrument(Span::current()) + } +} + +/// Extension trait allowing futures to be instrumented with +/// a `tracing` [`Subscriber`]. +/// +/// [`Subscriber`]: ../trait.Subscriber.html +pub trait WithSubscriber: Sized { + /// Attaches the provided [`Subscriber`] to this type, returning a + /// `WithDispatch` wrapper. + /// + /// The attached subscriber will be set as the [default] when the returned `Future` is polled. + /// + /// [`Subscriber`]: ../trait.Subscriber.html + /// [default]: https://docs.rs/tracing/latest/tracing/dispatcher/index.html#setting-the-default-subscriber + fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self> + where + S: Into<Dispatch>, + { + WithDispatch { + inner: self, + dispatch: subscriber.into(), + } + } + + /// Attaches the current [default] [`Subscriber`] to this type, returning a + /// `WithDispatch` wrapper. + /// + /// When the wrapped type is a future, stream, or sink, the attached + /// subscriber will be set as the [default] while it is being polled. + /// When the wrapped type is an executor, the subscriber will be set as the + /// default for any futures spawned on that executor. + /// + /// This can be used to propagate the current dispatcher context when + /// spawning a new future. + /// + /// [`Subscriber`]: ../trait.Subscriber.html + /// [default]: https://docs.rs/tracing/latest/tracing/dispatcher/index.html#setting-the-default-subscriber + #[inline] + fn with_current_subscriber(self) -> WithDispatch<Self> { + WithDispatch { + inner: self, + dispatch: dispatcher::get_default(|default| default.clone()), + } + } +} + +pin_project! { + /// A future that has been instrumented with a `tracing` subscriber. + #[derive(Clone, Debug)] + #[must_use = "futures do nothing unless you `.await` or poll them"] + pub struct WithDispatch<T> { + #[pin] + inner: T, + dispatch: Dispatch, + } +} + +pin_project! { + /// A future that has been instrumented with a `tracing` span. + #[derive(Debug, Clone)] + #[must_use = "futures do nothing unless you `.await` or poll them"] + pub struct Instrumented<T> { + #[pin] + inner: T, + span: Span, + } +} + +impl<T: Future> Future for Instrumented<T> { + type Output = T::Output; + + fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output> { + let this = self.project(); + let _enter = this.span.enter(); + this.inner.poll(cx) + } +} + +impl<T: Sized> Instrument for T {} + +impl<T> Instrumented<T> { + /// Borrows the `Span` that this type is instrumented by. + pub fn span(&self) -> &Span { + &self.span + } + + /// Mutably borrows the `Span` that this type is instrumented by. + pub fn span_mut(&mut self) -> &mut Span { + &mut self.span + } + + /// Borrows the wrapped type. + pub fn inner(&self) -> &T { + &self.inner + } + + /// Mutably borrows the wrapped type. + pub fn inner_mut(&mut self) -> &mut T { + &mut self.inner + } + + /// Get a pinned reference to the wrapped type. + pub fn inner_pin_ref(self: Pin<&Self>) -> Pin<&T> { + self.project_ref().inner + } + + /// Get a pinned mutable reference to the wrapped type. + pub fn inner_pin_mut(self: Pin<&mut Self>) -> Pin<&mut T> { + self.project().inner + } + + /// Consumes the `Instrumented`, returning the wrapped type. + /// + /// Note that this drops the span. + pub fn into_inner(self) -> T { + self.inner + } +} diff --git a/third_party/rust/tracing/src/level_filters.rs b/third_party/rust/tracing/src/level_filters.rs new file mode 100644 index 0000000000..df9405b5e4 --- /dev/null +++ b/third_party/rust/tracing/src/level_filters.rs @@ -0,0 +1,81 @@ +//! Trace verbosity level filtering. +//! +//! # Compile time filters +//! +//! Trace verbosity levels can be statically disabled at compile time via Cargo +//! features, similar to the [`log` crate]. Trace instrumentation at disabled +//! levels will be skipped and will not even be present in the resulting binary +//! unless the verbosity level is specified dynamically. This level is +//! configured separately for release and debug builds. The features are: +//! +//! * `max_level_off` +//! * `max_level_error` +//! * `max_level_warn` +//! * `max_level_info` +//! * `max_level_debug` +//! * `max_level_trace` +//! * `release_max_level_off` +//! * `release_max_level_error` +//! * `release_max_level_warn` +//! * `release_max_level_info` +//! * `release_max_level_debug` +//! * `release_max_level_trace` +//! +//! These features control the value of the `STATIC_MAX_LEVEL` constant. The +//! instrumentation macros macros check this value before recording an event or +//! constructing a span. By default, no levels are disabled. +//! +//! For example, a crate can disable trace level instrumentation in debug builds +//! and trace, debug, and info level instrumentation in release builds with the +//! following configuration: +//! +//! ```toml +//! [dependencies] +//! tracing = { version = "0.1", features = ["max_level_debug", "release_max_level_warn"] } +//! ``` +//! +//! *Compiler support: requires rustc 1.39+* +//! +//! [`log` crate]: https://docs.rs/log/0.4.6/log/#compile-time-filters +pub use tracing_core::{metadata::ParseLevelFilterError, LevelFilter}; + +/// The statically configured maximum trace level. +/// +/// See the [module-level documentation] for information on how to configure +/// this. +/// +/// This value is checked by the `event!` and `span!` macros. Code that +/// manually constructs events or spans via the `Event::record` function or +/// `Span` constructors should compare the level against this value to +/// determine if those spans or events are enabled. +/// +/// [module-level documentation]: ../index.html#compile-time-filters +pub const STATIC_MAX_LEVEL: LevelFilter = MAX_LEVEL; + +cfg_if! { + if #[cfg(all(not(debug_assertions), feature = "release_max_level_off"))] { + const MAX_LEVEL: LevelFilter = LevelFilter::OFF; + } else if #[cfg(all(not(debug_assertions), feature = "release_max_level_error"))] { + const MAX_LEVEL: LevelFilter = LevelFilter::ERROR; + } else if #[cfg(all(not(debug_assertions), feature = "release_max_level_warn"))] { + const MAX_LEVEL: LevelFilter = LevelFilter::WARN; + } else if #[cfg(all(not(debug_assertions), feature = "release_max_level_info"))] { + const MAX_LEVEL: LevelFilter = LevelFilter::INFO; + } else if #[cfg(all(not(debug_assertions), feature = "release_max_level_debug"))] { + const MAX_LEVEL: LevelFilter = LevelFilter::DEBUG; + } else if #[cfg(all(not(debug_assertions), feature = "release_max_level_trace"))] { + const MAX_LEVEL: LevelFilter = LevelFilter::TRACE; + } else if #[cfg(feature = "max_level_off")] { + const MAX_LEVEL: LevelFilter = LevelFilter::OFF; + } else if #[cfg(feature = "max_level_error")] { + const MAX_LEVEL: LevelFilter = LevelFilter::ERROR; + } else if #[cfg(feature = "max_level_warn")] { + const MAX_LEVEL: LevelFilter = LevelFilter::WARN; + } else if #[cfg(feature = "max_level_info")] { + const MAX_LEVEL: LevelFilter = LevelFilter::INFO; + } else if #[cfg(feature = "max_level_debug")] { + const MAX_LEVEL: LevelFilter = LevelFilter::DEBUG; + } else { + const MAX_LEVEL: LevelFilter = LevelFilter::TRACE; + } +} diff --git a/third_party/rust/tracing/src/lib.rs b/third_party/rust/tracing/src/lib.rs new file mode 100644 index 0000000000..5fc5382642 --- /dev/null +++ b/third_party/rust/tracing/src/lib.rs @@ -0,0 +1,1035 @@ +//! A scoped, structured logging and diagnostics system. +//! +//! # Overview +//! +//! `tracing` is a framework for instrumenting Rust programs to collect +//! structured, event-based diagnostic information. +//! +//! In asynchronous systems like Tokio, interpreting traditional log messages can +//! often be quite challenging. Since individual tasks are multiplexed on the same +//! thread, associated events and log lines are intermixed making it difficult to +//! trace the logic flow. `tracing` expands upon logging-style diagnostics by +//! allowing libraries and applications to record structured events with additional +//! information about *temporality* and *causality* — unlike a log message, a span +//! in `tracing` has a beginning and end time, may be entered and exited by the +//! flow of execution, and may exist within a nested tree of similar spans. In +//! addition, `tracing` spans are *structured*, with the ability to record typed +//! data as well as textual messages. +//! +//! The `tracing` crate provides the APIs necessary for instrumenting libraries +//! and applications to emit trace data. +//! +//! *Compiler support: [requires `rustc` 1.40+][msrv]* +//! +//! [msrv]: #supported-rust-versions +//! # Core Concepts +//! +//! The core of `tracing`'s API is composed of _spans_, _events_ and +//! _subscribers_. We'll cover these in turn. +//! +//! ## Spans +//! +//! To record the flow of execution through a program, `tracing` introduces the +//! concept of [spans]. Unlike a log line that represents a _moment in +//! time_, a span represents a _period of time_ with a beginning and an end. When a +//! program begins executing in a context or performing a unit of work, it +//! _enters_ that context's span, and when it stops executing in that context, +//! it _exits_ the span. The span in which a thread is currently executing is +//! referred to as that thread's _current_ span. +//! +//! For example: +//! ``` +//! use tracing::{span, Level}; +//! # fn main() { +//! let span = span!(Level::TRACE, "my_span"); +//! // `enter` returns a RAII guard which, when dropped, exits the span. this +//! // indicates that we are in the span for the current lexical scope. +//! let _enter = span.enter(); +//! // perform some work in the context of `my_span`... +//! # } +//!``` +//! +//! The [`span` module][span]'s documentation provides further details on how to +//! use spans. +//! +//! <div class="information"> +//! <div class="tooltip compile_fail" style="">⚠ ️<span class="tooltiptext">Warning</span></div> +//! </div><div class="example-wrap" style="display:inline-block"><pre class="compile_fail" style="white-space:normal;font:inherit;"> +//! <strong>Warning</strong>: In asynchronous code that uses async/await syntax, +//! <code>Span::enter</code> may produce incorrect traces if the returned drop +//! guard is held across an await point. See +//! <a href="span/struct.Span.html#in-asynchronous-code">the method documentation</a> +//! for details. +//! </pre></div> +//! +//! ## Events +//! +//! An [`Event`] represents a _moment_ in time. It signifies something that +//! happened while a trace was being recorded. `Event`s are comparable to the log +//! records emitted by unstructured logging code, but unlike a typical log line, +//! an `Event` may occur within the context of a span. +//! +//! For example: +//! ``` +//! use tracing::{event, span, Level}; +//! +//! # fn main() { +//! // records an event outside of any span context: +//! event!(Level::INFO, "something happened"); +//! +//! let span = span!(Level::INFO, "my_span"); +//! let _guard = span.enter(); +//! +//! // records an event within "my_span". +//! event!(Level::DEBUG, "something happened inside my_span"); +//! # } +//!``` +//! +//! In general, events should be used to represent points in time _within_ a +//! span — a request returned with a given status code, _n_ new items were +//! taken from a queue, and so on. +//! +//! The [`Event` struct][`Event`] documentation provides further details on using +//! events. +//! +//! ## Subscribers +//! +//! As `Span`s and `Event`s occur, they are recorded or aggregated by +//! implementations of the [`Subscriber`] trait. `Subscriber`s are notified +//! when an `Event` takes place and when a `Span` is entered or exited. These +//! notifications are represented by the following `Subscriber` trait methods: +//! +//! + [`event`][Subscriber::event], called when an `Event` takes place, +//! + [`enter`], called when execution enters a `Span`, +//! + [`exit`], called when execution exits a `Span` +//! +//! In addition, subscribers may implement the [`enabled`] function to _filter_ +//! the notifications they receive based on [metadata] describing each `Span` +//! or `Event`. If a call to `Subscriber::enabled` returns `false` for a given +//! set of metadata, that `Subscriber` will *not* be notified about the +//! corresponding `Span` or `Event`. For performance reasons, if no currently +//! active subscribers express interest in a given set of metadata by returning +//! `true`, then the corresponding `Span` or `Event` will never be constructed. +//! +//! # Usage +//! +//! First, add this to your `Cargo.toml`: +//! +//! ```toml +//! [dependencies] +//! tracing = "0.1" +//! ``` +//! +//! *Compiler support: requires rustc 1.39+* +//! +//! ## Recording Spans and Events +//! +//! Spans and events are recorded using macros. +//! +//! ### Spans +//! +//! The [`span!`] macro expands to a [`Span` struct][`Span`] which is used to +//! record a span. The [`Span::enter`] method on that struct records that the +//! span has been entered, and returns a [RAII] guard object, which will exit +//! the span when dropped. +//! +//! For example: +//! +//! ```rust +//! use tracing::{span, Level}; +//! # fn main() { +//! // Construct a new span named "my span" with trace log level. +//! let span = span!(Level::TRACE, "my span"); +//! +//! // Enter the span, returning a guard object. +//! let _enter = span.enter(); +//! +//! // Any trace events that occur before the guard is dropped will occur +//! // within the span. +//! +//! // Dropping the guard will exit the span. +//! # } +//! ``` +//! +//! The [`#[instrument]`][instrument] attribute provides an easy way to +//! add `tracing` spans to functions. A function annotated with `#[instrument]` +//! will create and enter a span with that function's name every time the +//! function is called, with arguments to that function will be recorded as +//! fields using `fmt::Debug`. +//! +//! For example: +//! ```ignore +//! # // this doctest is ignored because we don't have a way to say +//! # // that it should only be run with cfg(feature = "attributes") +//! use tracing::{Level, event, instrument}; +//! +//! #[instrument] +//! pub fn my_function(my_arg: usize) { +//! // This event will be recorded inside a span named `my_function` with the +//! // field `my_arg`. +//! event!(Level::INFO, "inside my_function!"); +//! // ... +//! } +//! # fn main() {} +//! ``` +//! +//! +//! You can find more examples showing how to use this crate [here][examples]. +//! +//! [RAII]: https://github.com/rust-unofficial/patterns/blob/master/patterns/RAII.md +//! [examples]: https://github.com/tokio-rs/tracing/tree/master/examples +//! +//! ### Events +//! +//! [`Event`]s are recorded using the [`event!`] macro: +//! +//! ```rust +//! # fn main() { +//! use tracing::{event, Level}; +//! event!(Level::INFO, "something has happened!"); +//! # } +//! ``` +//! +//! ## Using the Macros +//! +//! The [`span!`] and [`event!`] macros use fairly similar syntax, with some +//! exceptions. +//! +//! ### Configuring Attributes +//! +//! Both macros require a [`Level`] specifying the verbosity of the span or +//! event. Optionally, the [target] and [parent span] may be overridden. If the +//! target and parent span are not overridden, they will default to the +//! module path where the macro was invoked and the current span (as determined +//! by the subscriber), respectively. +//! +//! For example: +//! +//! ``` +//! # use tracing::{span, event, Level}; +//! # fn main() { +//! span!(target: "app_spans", Level::TRACE, "my span"); +//! event!(target: "app_events", Level::INFO, "something has happened!"); +//! # } +//! ``` +//! ``` +//! # use tracing::{span, event, Level}; +//! # fn main() { +//! let span = span!(Level::TRACE, "my span"); +//! event!(parent: &span, Level::INFO, "something has happened!"); +//! # } +//! ``` +//! +//! The span macros also take a string literal after the level, to set the name +//! of the span. +//! +//! ### Recording Fields +//! +//! Structured fields on spans and events are specified using the syntax +//! `field_name = field_value`. Fields are separated by commas. +//! +//! ``` +//! # use tracing::{event, Level}; +//! # fn main() { +//! // records an event with two fields: +//! // - "answer", with the value 42 +//! // - "question", with the value "life, the universe and everything" +//! event!(Level::INFO, answer = 42, question = "life, the universe, and everything"); +//! # } +//! ``` +//! +//! As shorthand, local variables may be used as field values without an +//! assignment, similar to [struct initializers]. For example: +//! +//! ``` +//! # use tracing::{span, Level}; +//! # fn main() { +//! let user = "ferris"; +//! +//! span!(Level::TRACE, "login", user); +//! // is equivalent to: +//! span!(Level::TRACE, "login", user = user); +//! # } +//!``` +//! +//! Field names can include dots, but should not be terminated by them: +//! ``` +//! # use tracing::{span, Level}; +//! # fn main() { +//! let user = "ferris"; +//! let email = "ferris@rust-lang.org"; +//! span!(Level::TRACE, "login", user, user.email = email); +//! # } +//!``` +//! +//! Since field names can include dots, fields on local structs can be used +//! using the local variable shorthand: +//! ``` +//! # use tracing::{span, Level}; +//! # fn main() { +//! # struct User { +//! # name: &'static str, +//! # email: &'static str, +//! # } +//! let user = User { +//! name: "ferris", +//! email: "ferris@rust-lang.org", +//! }; +//! // the span will have the fields `user.name = "ferris"` and +//! // `user.email = "ferris@rust-lang.org"`. +//! span!(Level::TRACE, "login", user.name, user.email); +//! # } +//!``` +//! +//! Fields with names that are not Rust identifiers, or with names that are Rust reserved words, +//! may be created using quoted string literals. However, this may not be used with the local +//! variable shorthand. +//! ``` +//! # use tracing::{span, Level}; +//! # fn main() { +//! // records an event with fields whose names are not Rust identifiers +//! // - "guid:x-request-id", containing a `:`, with the value "abcdef" +//! // - "type", which is a reserved word, with the value "request" +//! span!(Level::TRACE, "api", "guid:x-request-id" = "abcdef", "type" = "request"); +//! # } +//!``` +//! +//! The `?` sigil is shorthand that specifies a field should be recorded using +//! its [`fmt::Debug`] implementation: +//! ``` +//! # use tracing::{event, Level}; +//! # fn main() { +//! #[derive(Debug)] +//! struct MyStruct { +//! field: &'static str, +//! } +//! +//! let my_struct = MyStruct { +//! field: "Hello world!" +//! }; +//! +//! // `my_struct` will be recorded using its `fmt::Debug` implementation. +//! event!(Level::TRACE, greeting = ?my_struct); +//! // is equivalent to: +//! event!(Level::TRACE, greeting = tracing::field::debug(&my_struct)); +//! # } +//! ``` +//! +//! The `%` sigil operates similarly, but indicates that the value should be +//! recorded using its [`fmt::Display`] implementation: +//! ``` +//! # use tracing::{event, Level}; +//! # fn main() { +//! # #[derive(Debug)] +//! # struct MyStruct { +//! # field: &'static str, +//! # } +//! # +//! # let my_struct = MyStruct { +//! # field: "Hello world!" +//! # }; +//! // `my_struct.field` will be recorded using its `fmt::Display` implementation. +//! event!(Level::TRACE, greeting = %my_struct.field); +//! // is equivalent to: +//! event!(Level::TRACE, greeting = tracing::field::display(&my_struct.field)); +//! # } +//! ``` +//! +//! The `%` and `?` sigils may also be used with local variable shorthand: +//! +//! ``` +//! # use tracing::{event, Level}; +//! # fn main() { +//! # #[derive(Debug)] +//! # struct MyStruct { +//! # field: &'static str, +//! # } +//! # +//! # let my_struct = MyStruct { +//! # field: "Hello world!" +//! # }; +//! // `my_struct.field` will be recorded using its `fmt::Display` implementation. +//! event!(Level::TRACE, %my_struct.field); +//! # } +//! ``` +//! +//! Additionally, a span may declare fields with the special value [`Empty`], +//! which indicates that that the value for that field does not currently exist +//! but may be recorded later. For example: +//! +//! ``` +//! use tracing::{trace_span, field}; +//! +//! // Create a span with two fields: `greeting`, with the value "hello world", and +//! // `parting`, without a value. +//! let span = trace_span!("my_span", greeting = "hello world", parting = field::Empty); +//! +//! // ... +//! +//! // Now, record a value for parting as well. +//! span.record("parting", &"goodbye world!"); +//! ``` +//! +//! Note that a span may have up to 32 fields. The following will not compile: +//! +//! ```rust,compile_fail +//! # use tracing::Level; +//! # fn main() { +//! let bad_span = span!( +//! Level::TRACE, +//! "too many fields!", +//! a = 1, b = 2, c = 3, d = 4, e = 5, f = 6, g = 7, h = 8, i = 9, +//! j = 10, k = 11, l = 12, m = 13, n = 14, o = 15, p = 16, q = 17, +//! r = 18, s = 19, t = 20, u = 21, v = 22, w = 23, x = 24, y = 25, +//! z = 26, aa = 27, bb = 28, cc = 29, dd = 30, ee = 31, ff = 32, gg = 33 +//! ); +//! # } +//! ``` +//! +//! Finally, events may also include human-readable messages, in the form of a +//! [format string][fmt] and (optional) arguments, **after** the event's +//! key-value fields. If a format string and arguments are provided, +//! they will implicitly create a new field named `message` whose value is the +//! provided set of format arguments. +//! +//! For example: +//! +//! ``` +//! # use tracing::{event, Level}; +//! # fn main() { +//! let question = "the answer to the ultimate question of life, the universe, and everything"; +//! let answer = 42; +//! // records an event with the following fields: +//! // - `question.answer` with the value 42, +//! // - `question.tricky` with the value `true`, +//! // - "message", with the value "the answer to the ultimate question of life, the +//! // universe, and everything is 42." +//! event!( +//! Level::DEBUG, +//! question.answer = answer, +//! question.tricky = true, +//! "the answer to {} is {}.", question, answer +//! ); +//! # } +//! ``` +//! +//! Specifying a formatted message in this manner does not allocate by default. +//! +//! [struct initializers]: https://doc.rust-lang.org/book/ch05-01-defining-structs.html#using-the-field-init-shorthand-when-variables-and-fields-have-the-same-name +//! [target]: struct.Metadata.html#method.target +//! [parent span]: span/struct.Attributes.html#method.parent +//! [determined contextually]: span/struct.Attributes.html#method.is_contextual +//! [`fmt::Debug`]: https://doc.rust-lang.org/std/fmt/trait.Debug.html +//! [`fmt::Display`]: https://doc.rust-lang.org/std/fmt/trait.Display.html +//! [fmt]: https://doc.rust-lang.org/std/fmt/#usage +//! [`Empty`]: field/struct.Empty.html +//! +//! ### Shorthand Macros +//! +//! `tracing` also offers a number of macros with preset verbosity levels. +//! The [`trace!`], [`debug!`], [`info!`], [`warn!`], and [`error!`] behave +//! similarly to the [`event!`] macro, but with the [`Level`] argument already +//! specified, while the corresponding [`trace_span!`], [`debug_span!`], +//! [`info_span!`], [`warn_span!`], and [`error_span!`] macros are the same, +//! but for the [`span!`] macro. +//! +//! These are intended both as a shorthand, and for compatibility with the [`log`] +//! crate (see the next section). +//! +//! [`span!`]: macro.span.html +//! [`event!`]: macro.event.html +//! [`trace!`]: macro.trace.html +//! [`debug!`]: macro.debug.html +//! [`info!`]: macro.info.html +//! [`warn!`]: macro.warn.html +//! [`error!`]: macro.error.html +//! [`trace_span!`]: macro.trace_span.html +//! [`debug_span!`]: macro.debug_span.html +//! [`info_span!`]: macro.info_span.html +//! [`warn_span!`]: macro.warn_span.html +//! [`error_span!`]: macro.error_span.html +//! [`Level`]: struct.Level.html +//! +//! ### For `log` Users +//! +//! Users of the [`log`] crate should note that `tracing` exposes a set of +//! macros for creating `Event`s (`trace!`, `debug!`, `info!`, `warn!`, and +//! `error!`) which may be invoked with the same syntax as the similarly-named +//! macros from the `log` crate. Often, the process of converting a project to +//! use `tracing` can begin with a simple drop-in replacement. +//! +//! Let's consider the `log` crate's yak-shaving example: +//! +//! ```rust,ignore +//! use std::{error::Error, io}; +//! use tracing::{debug, error, info, span, warn, Level}; +//! +//! // the `#[tracing::instrument]` attribute creates and enters a span +//! // every time the instrumented function is called. The span is named after the +//! // the function or method. Parameters passed to the function are recorded as fields. +//! #[tracing::instrument] +//! pub fn shave(yak: usize) -> Result<(), Box<dyn Error + 'static>> { +//! // this creates an event at the DEBUG level with two fields: +//! // - `excitement`, with the key "excitement" and the value "yay!" +//! // - `message`, with the key "message" and the value "hello! I'm gonna shave a yak." +//! // +//! // unlike other fields, `message`'s shorthand initialization is just the string itself. +//! debug!(excitement = "yay!", "hello! I'm gonna shave a yak."); +//! if yak == 3 { +//! warn!("could not locate yak!"); +//! // note that this is intended to demonstrate `tracing`'s features, not idiomatic +//! // error handling! in a library or application, you should consider returning +//! // a dedicated `YakError`. libraries like snafu or thiserror make this easy. +//! return Err(io::Error::new(io::ErrorKind::Other, "shaving yak failed!").into()); +//! } else { +//! debug!("yak shaved successfully"); +//! } +//! Ok(()) +//! } +//! +//! pub fn shave_all(yaks: usize) -> usize { +//! // Constructs a new span named "shaving_yaks" at the TRACE level, +//! // and a field whose key is "yaks". This is equivalent to writing: +//! // +//! // let span = span!(Level::TRACE, "shaving_yaks", yaks = yaks); +//! // +//! // local variables (`yaks`) can be used as field values +//! // without an assignment, similar to struct initializers. +//! let span = span!(Level::TRACE, "shaving_yaks", yaks); +//! let _enter = span.enter(); +//! +//! info!("shaving yaks"); +//! +//! let mut yaks_shaved = 0; +//! for yak in 1..=yaks { +//! let res = shave(yak); +//! debug!(yak, shaved = res.is_ok()); +//! +//! if let Err(ref error) = res { +//! // Like spans, events can also use the field initialization shorthand. +//! // In this instance, `yak` is the field being initalized. +//! error!(yak, error = error.as_ref(), "failed to shave yak!"); +//! } else { +//! yaks_shaved += 1; +//! } +//! debug!(yaks_shaved); +//! } +//! +//! yaks_shaved +//! } +//! ``` +//! +//! ## In libraries +//! +//! Libraries should link only to the `tracing` crate, and use the provided +//! macros to record whatever information will be useful to downstream +//! consumers. +//! +//! ## In executables +//! +//! In order to record trace events, executables have to use a `Subscriber` +//! implementation compatible with `tracing`. A `Subscriber` implements a +//! way of collecting trace data, such as by logging it to standard output. +//! +//! This library does not contain any `Subscriber` implementations; these are +//! provided by [other crates](#related-crates). +//! +//! The simplest way to use a subscriber is to call the [`set_global_default`] +//! function: +//! +//! ``` +//! extern crate tracing; +//! # pub struct FooSubscriber; +//! # use tracing::{span::{Id, Attributes, Record}, Metadata}; +//! # impl tracing::Subscriber for FooSubscriber { +//! # fn new_span(&self, _: &Attributes) -> Id { Id::from_u64(0) } +//! # fn record(&self, _: &Id, _: &Record) {} +//! # fn event(&self, _: &tracing::Event) {} +//! # fn record_follows_from(&self, _: &Id, _: &Id) {} +//! # fn enabled(&self, _: &Metadata) -> bool { false } +//! # fn enter(&self, _: &Id) {} +//! # fn exit(&self, _: &Id) {} +//! # } +//! # impl FooSubscriber { +//! # fn new() -> Self { FooSubscriber } +//! # } +//! # fn main() { +//! +//! let my_subscriber = FooSubscriber::new(); +//! tracing::subscriber::set_global_default(my_subscriber) +//! .expect("setting tracing default failed"); +//! # } +//! ``` +//! +//! <div class="information"> +//! <div class="tooltip compile_fail" style="">⚠ ️<span class="tooltiptext">Warning</span></div> +//! </div><div class="example-wrap" style="display:inline-block"><pre class="compile_fail" style="white-space:normal;font:inherit;"> +//! <strong>Warning</strong>: In general, libraries should <em>not</em> call +//! <code>set_global_default()</code>! Doing so will cause conflicts when +//! executables that depend on the library try to set the default later. +//! </pre></div> +//! +//! This subscriber will be used as the default in all threads for the +//! remainder of the duration of the program, similar to setting the logger +//! in the `log` crate. +//! +//! In addition, the default subscriber can be set through using the +//! [`with_default`] function. This follows the `tokio` pattern of using +//! closures to represent executing code in a context that is exited at the end +//! of the closure. For example: +//! +//! ```rust +//! # pub struct FooSubscriber; +//! # use tracing::{span::{Id, Attributes, Record}, Metadata}; +//! # impl tracing::Subscriber for FooSubscriber { +//! # fn new_span(&self, _: &Attributes) -> Id { Id::from_u64(0) } +//! # fn record(&self, _: &Id, _: &Record) {} +//! # fn event(&self, _: &tracing::Event) {} +//! # fn record_follows_from(&self, _: &Id, _: &Id) {} +//! # fn enabled(&self, _: &Metadata) -> bool { false } +//! # fn enter(&self, _: &Id) {} +//! # fn exit(&self, _: &Id) {} +//! # } +//! # impl FooSubscriber { +//! # fn new() -> Self { FooSubscriber } +//! # } +//! # fn main() { +//! +//! let my_subscriber = FooSubscriber::new(); +//! # #[cfg(feature = "std")] +//! tracing::subscriber::with_default(my_subscriber, || { +//! // Any trace events generated in this closure or by functions it calls +//! // will be collected by `my_subscriber`. +//! }) +//! # } +//! ``` +//! +//! This approach allows trace data to be collected by multiple subscribers +//! within different contexts in the program. Note that the override only applies to the +//! currently executing thread; other threads will not see the change from with_default. +//! +//! Any trace events generated outside the context of a subscriber will not be collected. +//! +//! Once a subscriber has been set, instrumentation points may be added to the +//! executable using the `tracing` crate's macros. +//! +//! ## `log` Compatibility +//! +//! The [`log`] crate provides a simple, lightweight logging facade for Rust. +//! While `tracing` builds upon `log`'s foundation with richer structured +//! diagnostic data, `log`'s simplicity and ubiquity make it the "lowest common +//! denominator" for text-based logging in Rust — a vast majority of Rust +//! libraries and applications either emit or consume `log` records. Therefore, +//! `tracing` provides multiple forms of interoperability with `log`: `tracing` +//! instrumentation can emit `log` records, and a compatibility layer enables +//! `tracing` [`Subscriber`]s to consume `log` records as `tracing` [`Event`]s. +//! +//! ### Emitting `log` Records +//! +//! This crate provides two feature flags, "log" and "log-always", which will +//! cause [spans] and [events] to emit `log` records. When the "log" feature is +//! enabled, if no `tracing` `Subscriber` is active, invoking an event macro or +//! creating a span with fields will emit a `log` record. This is intended +//! primarily for use in libraries which wish to emit diagnostics that can be +//! consumed by applications using `tracing` *or* `log`, without paying the +//! additional overhead of emitting both forms of diagnostics when `tracing` is +//! in use. +//! +//! Enabling the "log-always" feature will cause `log` records to be emitted +//! even if a `tracing` `Subscriber` _is_ set. This is intended to be used in +//! applications where a `log` `Logger` is being used to record a textual log, +//! and `tracing` is used only to record other forms of diagnostics (such as +//! metrics, profiling, or distributed tracing data). Unlike the "log" feature, +//! libraries generally should **not** enable the "log-always" feature, as doing +//! so will prevent applications from being able to opt out of the `log` records. +//! +//! See [here][flags] for more details on this crate's feature flags. +//! +//! The generated `log` records' messages will be a string representation of the +//! span or event's fields, and all additional information recorded by `log` +//! (target, verbosity level, module path, file, and line number) will also be +//! populated. Additionally, `log` records are also generated when spans are +//! entered, exited, and closed. Since these additional span lifecycle logs have +//! the potential to be very verbose, and don't include additional fields, they +//! will always be emitted at the `Trace` level, rather than inheriting the +//! level of the span that generated them. Furthermore, they are are categorized +//! under a separate `log` target, "tracing::span" (and its sub-target, +//! "tracing::span::active", for the logs on entering and exiting a span), which +//! may be enabled or disabled separately from other `log` records emitted by +//! `tracing`. +//! +//! ### Consuming `log` Records +//! +//! The [`tracing-log`] crate provides a compatibility layer which +//! allows a `tracing` [`Subscriber`] to consume `log` records as though they +//! were `tracing` [events]. This allows applications using `tracing` to record +//! the logs emitted by dependencies using `log` as events within the context of +//! the application's trace tree. See [that crate's documentation][log-tracer] +//! for details. +//! +//! [log-tracer]: https://docs.rs/tracing-log/latest/tracing_log/#convert-log-records-to-tracing-events +//! +//! ## Related Crates +//! +//! In addition to `tracing` and `tracing-core`, the [`tokio-rs/tracing`] repository +//! contains several additional crates designed to be used with the `tracing` ecosystem. +//! This includes a collection of `Subscriber` implementations, as well as utility +//! and adapter crates to assist in writing `Subscriber`s and instrumenting +//! applications. +//! +//! In particular, the following crates are likely to be of interest: +//! +//! - [`tracing-futures`] provides a compatibility layer with the `futures` +//! crate, allowing spans to be attached to `Future`s, `Stream`s, and `Executor`s. +//! - [`tracing-subscriber`] provides `Subscriber` implementations and +//! utilities for working with `Subscriber`s. This includes a [`FmtSubscriber`] +//! `FmtSubscriber` for logging formatted trace data to stdout, with similar +//! filtering and formatting to the [`env_logger`] crate. +//! - [`tracing-log`] provides a compatibility layer with the [`log`] crate, +//! allowing log messages to be recorded as `tracing` `Event`s within the +//! trace tree. This is useful when a project using `tracing` have +//! dependencies which use `log`. Note that if you're using +//! `tracing-subscriber`'s `FmtSubscriber`, you don't need to depend on +//! `tracing-log` directly. +//! - [`tracing-appender`] provides utilities for outputting tracing data, +//! including a file appender and non blocking writer. +//! +//! Additionally, there are also several third-party crates which are not +//! maintained by the `tokio` project. These include: +//! +//! - [`tracing-timing`] implements inter-event timing metrics on top of `tracing`. +//! It provides a subscriber that records the time elapsed between pairs of +//! `tracing` events and generates histograms. +//! - [`tracing-opentelemetry`] provides a subscriber for emitting traces to +//! [OpenTelemetry]-compatible distributed tracing systems. +//! - [`tracing-honeycomb`] Provides a layer that reports traces spanning multiple machines to [honeycomb.io]. Backed by [`tracing-distributed`]. +//! - [`tracing-distributed`] Provides a generic implementation of a layer that reports traces spanning multiple machines to some backend. +//! - [`tracing-actix`] provides `tracing` integration for the `actix` actor +//! framework. +//! - [`tracing-gelf`] implements a subscriber for exporting traces in Greylog +//! GELF format. +//! - [`tracing-coz`] provides integration with the [coz] causal profiler +//! (Linux-only). +//! - [`tracing-bunyan-formatter`] provides a layer implementation that reports events and spans +//! in [bunyan] format, enriched with timing information. +//! - [`tracing-wasm`] provides a `Subscriber`/`Layer` implementation that reports +//! events and spans via browser `console.log` and [User Timing API (`window.performance`)]. +//! - [`tide-tracing`] provides a [tide] middleware to trace all incoming requests and responses. +//! - [`test-env-log`] takes care of initializing `tracing` for tests, based on +//! environment variables with an `env_logger` compatible syntax. +//! - [`tracing-unwrap`] provides convenience methods to report failed unwraps +//! on `Result` or `Option` types to a `Subscriber`. +//! - [`diesel-tracing`] provides integration with [`diesel`] database connections. +//! - [`tracing-tracy`] provides a way to collect [Tracy] profiles in instrumented +//! applications. +//! +//! If you're the maintainer of a `tracing` ecosystem crate not listed above, +//! please let us know! We'd love to add your project to the list! +//! +//! [`tracing-opentelemetry`]: https://crates.io/crates/tracing-opentelemetry +//! [OpenTelemetry]: https://opentelemetry.io/ +//! [`tracing-honeycomb`]: https://crates.io/crates/tracing-honeycomb +//! [`tracing-distributed`]: https://crates.io/crates/tracing-distributed +//! [honeycomb.io]: https://www.honeycomb.io/ +//! [`tracing-actix`]: https://crates.io/crates/tracing-actix +//! [`tracing-gelf`]: https://crates.io/crates/tracing-gelf +//! [`tracing-coz`]: https://crates.io/crates/tracing-coz +//! [coz]: https://github.com/plasma-umass/coz +//! [`tracing-bunyan-formatter`]: https://crates.io/crates/tracing-bunyan-formatter +//! [bunyan]: https://github.com/trentm/node-bunyan +//! [`tracing-wasm`]: https://docs.rs/tracing-wasm +//! [User Timing API (`window.performance`)]: https://developer.mozilla.org/en-US/docs/Web/API/User_Timing_API +//! [`tide-tracing`]: https://crates.io/crates/tide-tracing +//! [tide]: https://crates.io/crates/tide +//! [`test-env-log`]: https://crates.io/crates/test-env-log +//! [`tracing-unwrap`]: https://docs.rs/tracing-unwrap +//! [`diesel`]: https://crates.io/crates/diesel +//! [`diesel-tracing`]: https://crates.io/crates/diesel-tracing +//! [`tracing-tracy`]: https://crates.io/crates/tracing-tracy +//! [Tracy]: https://github.com/wolfpld/tracy +//! +//! <div class="information"> +//! <div class="tooltip ignore" style="">ⓘ<span class="tooltiptext">Note</span></div> +//! </div> +//! <div class="example-wrap" style="display:inline-block"> +//! <pre class="ignore" style="white-space:normal;font:inherit;"> +//! <strong>Note</strong>: Some of these ecosystem crates are currently +//! unreleased and/or in earlier stages of development. They may be less stable +//! than <code>tracing</code> and <code>tracing-core</code>. +//! </pre></div> +//! +//! ## Crate Feature Flags +//! +//! The following crate feature flags are available: +//! +//! * A set of features controlling the [static verbosity level]. +//! * `log`: causes trace instrumentation points to emit [`log`] records as well +//! as trace events, if a default `tracing` subscriber has not been set. This +//! is intended for use in libraries whose users may be using either `tracing` +//! or `log`. +//! * `log-always`: Emit `log` records from all `tracing` spans and events, even +//! if a `tracing` subscriber has been set. This should be set only by +//! applications which intend to collect traces and logs separately; if an +//! adapter is used to convert `log` records into `tracing` events, this will +//! cause duplicate events to occur. +//! * `attributes`: Includes support for the `#[instrument]` attribute. +//! This is on by default, but does bring in the `syn` crate as a dependency, +//! which may add to the compile time of crates that do not already use it. +//! * `std`: Depend on the Rust standard library (enabled by default). +//! +//! `no_std` users may disable this feature with `default-features = false`: +//! +//! ```toml +//! [dependencies] +//! tracing = { version = "0.1.21", default-features = false } +//! ``` +//! +//! <div class="information"> +//! <div class="tooltip ignore" style="">ⓘ<span class="tooltiptext">Note</span></div> +//! </div> +//! <div class="example-wrap" style="display:inline-block"> +//! <pre class="ignore" style="white-space:normal;font:inherit;"> +//! <strong>Note</strong>: <code>tracing</code>'s <code>no_std</code> support +//! requires <code>liballoc</code>. +//! </pre></div> +//! +//! ## Supported Rust Versions +//! +//! Tracing is built against the latest stable release. The minimum supported +//! version is 1.40. The current Tracing version is not guaranteed to build on +//! Rust versions earlier than the minimum supported version. +//! +//! Tracing follows the same compiler support policies as the rest of the Tokio +//! project. The current stable Rust compiler and the three most recent minor +//! versions before it will always be supported. For example, if the current +//! stable compiler version is 1.45, the minimum supported version will not be +//! increased past 1.42, three minor versions prior. Increasing the minimum +//! supported compiler version is not considered a semver breaking change as +//! long as doing so complies with this policy. +//! +//! [`log`]: https://docs.rs/log/0.4.6/log/ +//! [span]: mod@span +//! [spans]: mod@span +//! [`Span`]: span::Span +//! [`in_scope`]: span::Span::in_scope +//! [event]: Event +//! [events]: Event +//! [`Subscriber`]: subscriber::Subscriber +//! [Subscriber::event]: subscriber::Subscriber::event +//! [`enter`]: subscriber::Subscriber::enter +//! [`exit`]: subscriber::Subscriber::exit +//! [`enabled`]: subscriber::Subscriber::enabled +//! [metadata]: Metadata +//! [`field::display`]: field::display +//! [`field::debug`]: field::debug +//! [`set_global_default`]: subscriber::set_global_default +//! [`with_default`]: subscriber::with_default +//! [`tokio-rs/tracing`]: https://github.com/tokio-rs/tracing +//! [`tracing-futures`]: https://crates.io/crates/tracing-futures +//! [`tracing-subscriber`]: https://crates.io/crates/tracing-subscriber +//! [`tracing-log`]: https://crates.io/crates/tracing-log +//! [`tracing-timing`]: https://crates.io/crates/tracing-timing +//! [`tracing-appender`]: https://crates.io/crates/tracing-appender +//! [`env_logger`]: https://crates.io/crates/env_logger +//! [`FmtSubscriber`]: https://docs.rs/tracing-subscriber/latest/tracing_subscriber/fmt/struct.Subscriber.html +//! [static verbosity level]: level_filters/index.html#compile-time-filters +//! [instrument]: https://docs.rs/tracing-attributes/latest/tracing_attributes/attr.instrument.html +//! [flags]: #crate-feature-flags +#![cfg_attr(not(feature = "std"), no_std)] +#![cfg_attr(docsrs, feature(doc_cfg), deny(broken_intra_doc_links))] +#![doc(html_root_url = "https://docs.rs/tracing/0.1.21")] +#![doc( + html_logo_url = "https://raw.githubusercontent.com/tokio-rs/tracing/master/assets/logo-type.png", + issue_tracker_base_url = "https://github.com/tokio-rs/tracing/issues/" +)] +#![warn( + missing_debug_implementations, + missing_docs, + rust_2018_idioms, + unreachable_pub, + bad_style, + const_err, + dead_code, + improper_ctypes, + non_shorthand_field_patterns, + no_mangle_generic_items, + overflowing_literals, + path_statements, + patterns_in_fns_without_body, + private_in_public, + unconditional_recursion, + unused, + unused_allocation, + unused_comparisons, + unused_parens, + while_true +)] + +#[cfg(not(feature = "std"))] +extern crate alloc; + +#[macro_use] +extern crate cfg_if; + +#[cfg(feature = "log")] +#[doc(hidden)] +pub use log; + +// Somehow this `use` statement is necessary for us to re-export the `core` +// macros on Rust 1.26.0. I'm not sure how this makes it work, but it does. +#[allow(unused_imports)] +#[doc(hidden)] +use tracing_core::*; + +#[doc(inline)] +pub use self::instrument::Instrument; +pub use self::{dispatcher::Dispatch, event::Event, field::Value, subscriber::Subscriber}; + +#[doc(hidden)] +pub use self::span::Id; + +#[doc(hidden)] +pub use tracing_core::{ + callsite::{self, Callsite}, + metadata, +}; +pub use tracing_core::{event, Level, Metadata}; + +#[doc(inline)] +pub use self::span::Span; +#[cfg(feature = "attributes")] +#[cfg_attr(docsrs, doc(cfg(feature = "attributes")))] +#[doc(inline)] +pub use tracing_attributes::instrument; + +#[macro_use] +mod macros; + +pub mod dispatcher; +pub mod field; +/// Attach a span to a `std::future::Future`. +pub mod instrument; +pub mod level_filters; +pub mod span; +pub(crate) mod stdlib; +pub mod subscriber; + +#[doc(hidden)] +pub mod __macro_support { + pub use crate::callsite::Callsite; + use crate::stdlib::sync::atomic::{AtomicUsize, Ordering}; + use crate::{subscriber::Interest, Metadata}; + use tracing_core::Once; + + /// Callsite implementation used by macro-generated code. + /// + /// /!\ WARNING: This is *not* a stable API! /!\ + /// This type, and all code contained in the `__macro_support` module, is + /// a *private* API of `tracing`. It is exposed publicly because it is used + /// by the `tracing` macros, but it is not part of the stable versioned API. + /// Breaking changes to this module may occur in small-numbered versions + /// without warning. + #[derive(Debug)] + pub struct MacroCallsite { + interest: AtomicUsize, + meta: &'static Metadata<'static>, + registration: Once, + } + + impl MacroCallsite { + /// Returns a new `MacroCallsite` with the specified `Metadata`. + /// + /// /!\ WARNING: This is *not* a stable API! /!\ + /// This method, and all code contained in the `__macro_support` module, is + /// a *private* API of `tracing`. It is exposed publicly because it is used + /// by the `tracing` macros, but it is not part of the stable versioned API. + /// Breaking changes to this module may occur in small-numbered versions + /// without warning. + pub const fn new(meta: &'static Metadata<'static>) -> Self { + Self { + interest: AtomicUsize::new(0xDEADFACED), + meta, + registration: Once::new(), + } + } + + /// Registers this callsite with the global callsite registry. + /// + /// If the callsite is already registered, this does nothing. + /// + /// /!\ WARNING: This is *not* a stable API! /!\ + /// This method, and all code contained in the `__macro_support` module, is + /// a *private* API of `tracing`. It is exposed publicly because it is used + /// by the `tracing` macros, but it is not part of the stable versioned API. + /// Breaking changes to this module may occur in small-numbered versions + /// without warning. + #[inline(never)] + // This only happens once (or if the cached interest value was corrupted). + #[cold] + pub fn register(&'static self) -> Interest { + self.registration + .call_once(|| crate::callsite::register(self)); + match self.interest.load(Ordering::Relaxed) { + 0 => Interest::never(), + 2 => Interest::always(), + _ => Interest::sometimes(), + } + } + + /// Returns the callsite's cached Interest, or registers it for the + /// first time if it has not yet been registered. + /// + /// /!\ WARNING: This is *not* a stable API! /!\ + /// This method, and all code contained in the `__macro_support` module, is + /// a *private* API of `tracing`. It is exposed publicly because it is used + /// by the `tracing` macros, but it is not part of the stable versioned API. + /// Breaking changes to this module may occur in small-numbered versions + /// without warning. + #[inline] + pub fn interest(&'static self) -> Interest { + match self.interest.load(Ordering::Relaxed) { + 0 => Interest::never(), + 1 => Interest::sometimes(), + 2 => Interest::always(), + _ => self.register(), + } + } + + pub fn is_enabled(&self, interest: Interest) -> bool { + interest.is_always() + || crate::dispatcher::get_default(|default| default.enabled(self.meta)) + } + + #[inline] + #[cfg(feature = "log")] + pub fn disabled_span(&self) -> crate::Span { + crate::Span::new_disabled(self.meta) + } + + #[inline] + #[cfg(not(feature = "log"))] + pub fn disabled_span(&self) -> crate::Span { + crate::Span::none() + } + } + + impl Callsite for MacroCallsite { + fn set_interest(&self, interest: Interest) { + let interest = match () { + _ if interest.is_never() => 0, + _ if interest.is_always() => 2, + _ => 1, + }; + self.interest.store(interest, Ordering::SeqCst); + } + + #[inline(always)] + fn metadata(&self) -> &Metadata<'static> { + &self.meta + } + } +} + +mod sealed { + pub trait Sealed {} +} diff --git a/third_party/rust/tracing/src/macros.rs b/third_party/rust/tracing/src/macros.rs new file mode 100644 index 0000000000..3222abb741 --- /dev/null +++ b/third_party/rust/tracing/src/macros.rs @@ -0,0 +1,2369 @@ +/// Constructs a new span. +/// +/// See [the top-level documentation][lib] for details on the syntax accepted by +/// this macro. +/// +/// [lib]: index.html#using-the-macros +/// +/// # Examples +/// +/// Creating a new span: +/// ``` +/// # use tracing::{span, Level}; +/// # fn main() { +/// let span = span!(Level::TRACE, "my span"); +/// let _enter = span.enter(); +/// // do work inside the span... +/// # } +/// ``` +#[macro_export] +macro_rules! span { + (target: $target:expr, parent: $parent:expr, $lvl:expr, $name:expr) => { + $crate::span!(target: $target, parent: $parent, $lvl, $name,) + }; + (target: $target:expr, parent: $parent:expr, $lvl:expr, $name:expr, $($fields:tt)*) => { + { + use $crate::__macro_support::Callsite as _; + static CALLSITE: $crate::__macro_support::MacroCallsite = $crate::callsite2! { + name: $name, + kind: $crate::metadata::Kind::SPAN, + target: $target, + level: $lvl, + fields: $($fields)* + }; + let mut interest = $crate::subscriber::Interest::never(); + if $crate::level_enabled!($lvl) + && { interest = CALLSITE.interest(); !interest.is_never() } + && CALLSITE.is_enabled(interest) + { + let meta = CALLSITE.metadata(); + // span with explicit parent + $crate::Span::child_of( + $parent, + meta, + &$crate::valueset!(meta.fields(), $($fields)*), + ) + } else { + let span = CALLSITE.disabled_span(); + $crate::if_log_enabled! {{ + span.record_all(&$crate::valueset!(CALLSITE.metadata().fields(), $($fields)*)); + }}; + span + } + } + }; + (target: $target:expr, $lvl:expr, $name:expr, $($fields:tt)*) => { + { + use $crate::__macro_support::Callsite as _; + static CALLSITE: $crate::__macro_support::MacroCallsite = $crate::callsite2! { + name: $name, + kind: $crate::metadata::Kind::SPAN, + target: $target, + level: $lvl, + fields: $($fields)* + }; + let mut interest = $crate::subscriber::Interest::never(); + if $crate::level_enabled!($lvl) + && { interest = CALLSITE.interest(); !interest.is_never() } + && CALLSITE.is_enabled(interest) + { + let meta = CALLSITE.metadata(); + // span with contextual parent + $crate::Span::new( + meta, + &$crate::valueset!(meta.fields(), $($fields)*), + ) + } else { + let span = CALLSITE.disabled_span(); + $crate::if_log_enabled! {{ + span.record_all(&$crate::valueset!(CALLSITE.metadata().fields(), $($fields)*)); + }}; + span + } + } + }; + (target: $target:expr, parent: $parent:expr, $lvl:expr, $name:expr) => { + $crate::span!(target: $target, parent: $parent, $lvl, $name,) + }; + (parent: $parent:expr, $lvl:expr, $name:expr, $($fields:tt)*) => { + $crate::span!( + target: module_path!(), + parent: $parent, + $lvl, + $name, + $($fields)* + ) + }; + (parent: $parent:expr, $lvl:expr, $name:expr) => { + $crate::span!( + target: module_path!(), + parent: $parent, + $lvl, + $name, + ) + }; + (target: $target:expr, $lvl:expr, $name:expr, $($fields:tt)*) => { + $crate::span!( + target: $target, + $lvl, + $name, + $($fields)* + ) + }; + (target: $target:expr, $lvl:expr, $name:expr) => { + $crate::span!(target: $target, $lvl, $name,) + }; + ($lvl:expr, $name:expr, $($fields:tt)*) => { + $crate::span!( + target: module_path!(), + $lvl, + $name, + $($fields)* + ) + }; + ($lvl:expr, $name:expr) => { + $crate::span!( + target: module_path!(), + $lvl, + $name, + ) + }; +} + +/// Constructs a span at the trace level. +/// +/// [Fields] and [attributes] are set using the same syntax as the [`span!`] +/// macro. +/// +/// See [the top-level documentation][lib] for details on the syntax accepted by +/// this macro. +/// +/// [lib]: index.html#using-the-macros +/// [attributes]: index.html#configuring-attributes +/// [Fields]: index.html#recording-fields +/// [`span!`]: macro.span.html +/// +/// # Examples +/// +/// ```rust +/// # use tracing::{trace_span, span, Level}; +/// # fn main() { +/// trace_span!("my_span"); +/// // is equivalent to: +/// span!(Level::TRACE, "my_span"); +/// # } +/// ``` +/// +/// ```rust +/// # use tracing::{trace_span, span, Level}; +/// # fn main() { +/// let span = trace_span!("my span"); +/// span.in_scope(|| { +/// // do work inside the span... +/// }); +/// # } +/// ``` +#[macro_export] +macro_rules! trace_span { + (target: $target:expr, parent: $parent:expr, $name:expr, $($field:tt)*) => { + $crate::span!( + target: $target, + parent: $parent, + $crate::Level::TRACE, + $name, + $($field)* + ) + }; + (target: $target:expr, parent: $parent:expr, $name:expr) => { + $crate::trace_span!(target: $target, parent: $parent, $name,) + }; + (parent: $parent:expr, $name:expr, $($field:tt)*) => { + $crate::span!( + target: module_path!(), + parent: $parent, + $crate::Level::TRACE, + $name, + $($field)* + ) + }; + (parent: $parent:expr, $name:expr) => { + $crate::trace_span!(parent: $parent, $name,) + }; + (target: $target:expr, $name:expr, $($field:tt)*) => { + $crate::span!( + target: $target, + $crate::Level::TRACE, + $name, + $($field)* + ) + }; + (target: $target:expr, $name:expr) => { + $crate::trace_span!(target: $target, $name,) + }; + ($name:expr, $($field:tt)*) => { + $crate::span!( + target: module_path!(), + $crate::Level::TRACE, + $name, + $($field)* + ) + }; + ($name:expr) => { $crate::trace_span!($name,) }; +} + +/// Constructs a span at the debug level. +/// +/// [Fields] and [attributes] are set using the same syntax as the [`span!`] +/// macro. +/// +/// See [the top-level documentation][lib] for details on the syntax accepted by +/// this macro. +/// +/// [lib]: index.html#using-the-macros +/// [attributes]: index.html#configuring-attributes +/// [Fields]: index.html#recording-fields +/// [`span!`]: macro.span.html +/// +/// # Examples +/// +/// ```rust +/// # use tracing::{debug_span, span, Level}; +/// # fn main() { +/// debug_span!("my_span"); +/// // is equivalent to: +/// span!(Level::DEBUG, "my_span"); +/// # } +/// ``` +/// +/// ```rust +/// # use tracing::debug_span; +/// # fn main() { +/// let span = debug_span!("my span"); +/// span.in_scope(|| { +/// // do work inside the span... +/// }); +/// # } +/// ``` +#[macro_export] +macro_rules! debug_span { + (target: $target:expr, parent: $parent:expr, $name:expr, $($field:tt)*) => { + $crate::span!( + target: $target, + parent: $parent, + $crate::Level::DEBUG, + $name, + $($field)* + ) + }; + (target: $target:expr, parent: $parent:expr, $name:expr) => { + $crate::debug_span!(target: $target, parent: $parent, $name,) + }; + (parent: $parent:expr, $name:expr, $($field:tt)*) => { + $crate::span!( + target: module_path!(), + parent: $parent, + $crate::Level::DEBUG, + $name, + $($field)* + ) + }; + (parent: $parent:expr, $name:expr) => { + $crate::debug_span!(parent: $parent, $name,) + }; + (target: $target:expr, $name:expr, $($field:tt)*) => { + $crate::span!( + target: $target, + $crate::Level::DEBUG, + $name, + $($field)* + ) + }; + (target: $target:expr, $name:expr) => { + $crate::debug_span!(target: $target, $name,) + }; + ($name:expr, $($field:tt)*) => { + $crate::span!( + target: module_path!(), + $crate::Level::DEBUG, + $name, + $($field)* + ) + }; + ($name:expr) => {$crate::debug_span!($name,)}; +} + +/// Constructs a span at the info level. +/// +/// [Fields] and [attributes] are set using the same syntax as the [`span!`] +/// macro. +/// +/// See [the top-level documentation][lib] for details on the syntax accepted by +/// this macro. +/// +/// [lib]: index.html#using-the-macros +/// [attributes]: index.html#configuring-attributes +/// [Fields]: index.html#recording-fields +/// [`span!`]: macro.span.html +/// +/// # Examples +/// +/// ```rust +/// # use tracing::{span, info_span, Level}; +/// # fn main() { +/// info_span!("my_span"); +/// // is equivalent to: +/// span!(Level::INFO, "my_span"); +/// # } +/// ``` +/// +/// ```rust +/// # use tracing::info_span; +/// # fn main() { +/// let span = info_span!("my span"); +/// span.in_scope(|| { +/// // do work inside the span... +/// }); +/// # } +/// ``` +#[macro_export] +macro_rules! info_span { + (target: $target:expr, parent: $parent:expr, $name:expr, $($field:tt)*) => { + $crate::span!( + target: $target, + parent: $parent, + $crate::Level::INFO, + $name, + $($field)* + ) + }; + (target: $target:expr, parent: $parent:expr, $name:expr) => { + $crate::info_span!(target: $target, parent: $parent, $name,) + }; + (parent: $parent:expr, $name:expr, $($field:tt)*) => { + $crate::span!( + target: module_path!(), + parent: $parent, + $crate::Level::INFO, + $name, + $($field)* + ) + }; + (parent: $parent:expr, $name:expr) => { + $crate::info_span!(parent: $parent, $name,) + }; + (target: $target:expr, $name:expr, $($field:tt)*) => { + $crate::span!( + target: $target, + $crate::Level::INFO, + $name, + $($field)* + ) + }; + (target: $target:expr, $name:expr) => { + $crate::info_span!(target: $target, $name,) + }; + ($name:expr, $($field:tt)*) => { + $crate::span!( + target: module_path!(), + $crate::Level::INFO, + $name, + $($field)* + ) + }; + ($name:expr) => {$crate::info_span!($name,)}; +} + +/// Constructs a span at the warn level. +/// +/// [Fields] and [attributes] are set using the same syntax as the [`span!`] +/// macro. +/// +/// See [the top-level documentation][lib] for details on the syntax accepted by +/// this macro. +/// +/// [lib]: index.html#using-the-macros +/// [attributes]: index.html#configuring-attributes +/// [Fields]: index.html#recording-fields +/// [`span!`]: macro.span.html +/// +/// # Examples +/// +/// ```rust +/// # use tracing::{warn_span, span, Level}; +/// # fn main() { +/// warn_span!("my_span"); +/// // is equivalent to: +/// span!(Level::WARN, "my_span"); +/// # } +/// ``` +/// +/// ```rust +/// use tracing::warn_span; +/// # fn main() { +/// let span = warn_span!("my span"); +/// span.in_scope(|| { +/// // do work inside the span... +/// }); +/// # } +/// ``` +#[macro_export] +macro_rules! warn_span { + (target: $target:expr, parent: $parent:expr, $name:expr, $($field:tt)*) => { + $crate::span!( + target: $target, + parent: $parent, + $crate::Level::WARN, + $name, + $($field)* + ) + }; + (target: $target:expr, parent: $parent:expr, $name:expr) => { + $crate::warn_span!(target: $target, parent: $parent, $name,) + }; + (parent: $parent:expr, $name:expr, $($field:tt)*) => { + $crate::span!( + target: module_path!(), + parent: $parent, + $crate::Level::WARN, + $name, + $($field)* + ) + }; + (parent: $parent:expr, $name:expr) => { + $crate::warn_span!(parent: $parent, $name,) + }; + (target: $target:expr, $name:expr, $($field:tt)*) => { + $crate::span!( + target: $target, + $crate::Level::WARN, + $name, + $($field)* + ) + }; + (target: $target:expr, $name:expr) => { + $crate::warn_span!(target: $target, $name,) + }; + ($name:expr, $($field:tt)*) => { + $crate::span!( + target: module_path!(), + $crate::Level::WARN, + $name, + $($field)* + ) + }; + ($name:expr) => {$crate::warn_span!($name,)}; +} +/// Constructs a span at the error level. +/// +/// [Fields] and [attributes] are set using the same syntax as the [`span!`] +/// macro. +/// +/// See [the top-level documentation][lib] for details on the syntax accepted by +/// this macro. +/// +/// [lib]: index.html#using-the-macros +/// [attributes]: index.html#configuring-attributes +/// [Fields]: index.html#recording-fields +/// [`span!`]: macro.span.html +/// +/// # Examples +/// +/// ```rust +/// # use tracing::{span, error_span, Level}; +/// # fn main() { +/// error_span!("my_span"); +/// // is equivalent to: +/// span!(Level::ERROR, "my_span"); +/// # } +/// ``` +/// +/// ```rust +/// # use tracing::error_span; +/// # fn main() { +/// let span = error_span!("my span"); +/// span.in_scope(|| { +/// // do work inside the span... +/// }); +/// # } +/// ``` +#[macro_export] +macro_rules! error_span { + (target: $target:expr, parent: $parent:expr, $name:expr, $($field:tt)*) => { + $crate::span!( + target: $target, + parent: $parent, + $crate::Level::ERROR, + $name, + $($field)* + ) + }; + (target: $target:expr, parent: $parent:expr, $name:expr) => { + $crate::error_span!(target: $target, parent: $parent, $name,) + }; + (parent: $parent:expr, $name:expr, $($field:tt)*) => { + $crate::span!( + target: module_path!(), + parent: $parent, + $crate::Level::ERROR, + $name, + $($field)* + ) + }; + (parent: $parent:expr, $name:expr) => { + $crate::error_span!(parent: $parent, $name,) + }; + (target: $target:expr, $name:expr, $($field:tt)*) => { + $crate::span!( + target: $target, + $crate::Level::ERROR, + $name, + $($field)* + ) + }; + (target: $target:expr, $name:expr) => { + $crate::error_span!(target: $target, $name,) + }; + ($name:expr, $($field:tt)*) => { + $crate::span!( + target: module_path!(), + $crate::Level::ERROR, + $name, + $($field)* + ) + }; + ($name:expr) => {$crate::error_span!($name,)}; +} + +/// Constructs a new `Event`. +/// +/// The event macro is invoked with a `Level` and up to 32 key-value fields. +/// Optionally, a format string and arguments may follow the fields; this will +/// be used to construct an implicit field named "message". +/// +/// See [the top-level documentation][lib] for details on the syntax accepted by +/// this macro. +/// +/// [lib]: index.html#using-the-macros +/// +/// # Examples +/// +/// ```rust +/// use tracing::{event, Level}; +/// +/// # fn main() { +/// let data = (42, "forty-two"); +/// let private_data = "private"; +/// let error = "a bad error"; +/// +/// event!(Level::ERROR, %error, "Received error"); +/// event!( +/// target: "app_events", +/// Level::WARN, +/// private_data, +/// ?data, +/// "App warning: {}", +/// error +/// ); +/// event!(Level::INFO, the_answer = data.0); +/// # } +/// ``` +/// +// /// Note that *unlike `span!`*, `event!` requires a value for all fields. As +// /// events are recorded immediately when the macro is invoked, there is no +// /// opportunity for fields to be recorded later. A trailing comma on the final +// /// field is valid. +// /// +// /// For example, the following does not compile: +// /// ```rust,compile_fail +// /// # #[macro_use] +// /// # extern crate tracing; +// /// # use tracing::Level; +// /// # fn main() { +// /// event!(Level::INFO, foo = 5, bad_field, bar = "hello") +// /// #} +// /// ``` +#[macro_export] +macro_rules! event { + (target: $target:expr, parent: $parent:expr, $lvl:expr, { $($fields:tt)* } )=> ( + $crate::__tracing_log!( + target: $target, + $lvl, + $($fields)* + ); + + if $crate::level_enabled!($lvl) { + use $crate::__macro_support::*; + static CALLSITE: $crate::__macro_support::MacroCallsite = $crate::callsite2! { + name: concat!( + "event ", + file!(), + ":", + line!() + ), + kind: $crate::metadata::Kind::EVENT, + target: $target, + level: $lvl, + fields: $($fields)* + }; + let interest = CALLSITE.interest(); + if !interest.is_never() && CALLSITE.is_enabled(interest) { + let meta = CALLSITE.metadata(); + // event with explicit parent + $crate::Event::child_of( + $parent, + meta, + &$crate::valueset!(meta.fields(), $($fields)*) + ); + } + } + ); + + (target: $target:expr, parent: $parent:expr, $lvl:expr, { $($fields:tt)* }, $($arg:tt)+ ) => ( + $crate::event!( + target: $target, + parent: $parent, + $lvl, + { message = format_args!($($arg)+), $($fields)* } + ) + ); + (target: $target:expr, parent: $parent:expr, $lvl:expr, $($k:ident).+ = $($fields:tt)* ) => ( + $crate::event!(target: $target, parent: $parent, $lvl, { $($k).+ = $($fields)* }) + ); + (target: $target:expr, parent: $parent:expr, $lvl:expr, $($arg:tt)+) => ( + $crate::event!(target: $target, parent: $parent, $lvl, { $($arg)+ }) + ); + (target: $target:expr, $lvl:expr, { $($fields:tt)* } )=> ({ + $crate::__tracing_log!( + target: $target, + $lvl, + $($fields)* + ); + if $crate::level_enabled!($lvl) { + use $crate::__macro_support::*; + static CALLSITE: $crate::__macro_support::MacroCallsite = $crate::callsite2! { + name: concat!( + "event ", + file!(), + ":", + line!() + ), + kind: $crate::metadata::Kind::EVENT, + target: $target, + level: $lvl, + fields: $($fields)* + }; + let interest = CALLSITE.interest(); + if !interest.is_never() && CALLSITE.is_enabled(interest) { + let meta = CALLSITE.metadata(); + // event with contextual parent + $crate::Event::dispatch( + meta, + &$crate::valueset!(meta.fields(), $($fields)*) + ); + } + } + }); + (target: $target:expr, $lvl:expr, { $($fields:tt)* }, $($arg:tt)+ ) => ( + $crate::event!( + target: $target, + $lvl, + { message = format_args!($($arg)+), $($fields)* } + ) + ); + (target: $target:expr, $lvl:expr, $($k:ident).+ = $($fields:tt)* ) => ( + $crate::event!(target: $target, $lvl, { $($k).+ = $($fields)* }) + ); + (target: $target:expr, $lvl:expr, $($arg:tt)+ ) => ( + $crate::event!(target: $target, $lvl, { $($arg)+ }) + ); + (parent: $parent:expr, $lvl:expr, { $($fields:tt)* }, $($arg:tt)+ ) => ( + $crate::event!( + target: module_path!(), + parent: $parent, + $lvl, + { message = format_args!($($arg)+), $($fields)* } + ) + ); + (parent: $parent:expr, $lvl:expr, { $($fields:tt)* }, $($arg:tt)+ ) => ( + $crate::event!( + target: module_path!(), + $lvl, + parent: $parent, + { message = format_args!($($arg)+), $($fields)* } + ) + ); + (parent: $parent:expr, $lvl:expr, $($k:ident).+ = $($field:tt)*) => ( + $crate::event!( + target: module_path!(), + parent: $parent, + $lvl, + { $($k).+ = $($field)*} + ) + ); + (parent: $parent:expr, $lvl:expr, ?$($k:ident).+ = $($field:tt)*) => ( + $crate::event!( + target: module_path!(), + parent: $parent, + $lvl, + { ?$($k).+ = $($field)*} + ) + ); + (parent: $parent:expr, $lvl:expr, %$($k:ident).+ = $($field:tt)*) => ( + $crate::event!( + target: module_path!(), + parent: $parent, + $lvl, + { %$($k).+ = $($field)*} + ) + ); + (parent: $parent:expr, $lvl:expr, $($k:ident).+, $($field:tt)*) => ( + $crate::event!( + target: module_path!(), + parent: $parent, + $lvl, + { $($k).+, $($field)*} + ) + ); + (parent: $parent:expr, $lvl:expr, %$($k:ident).+, $($field:tt)*) => ( + $crate::event!( + target: module_path!(), + parent: $parent, + $lvl, + { %$($k).+, $($field)*} + ) + ); + (parent: $parent:expr, $lvl:expr, ?$($k:ident).+, $($field:tt)*) => ( + $crate::event!( + target: module_path!(), + parent: $parent, + $lvl, + { ?$($k).+, $($field)*} + ) + ); + (parent: $parent:expr, $lvl:expr, $($arg:tt)+ ) => ( + $crate::event!(target: module_path!(), parent: $parent, $lvl, { $($arg)+ }) + ); + ( $lvl:expr, { $($fields:tt)* }, $($arg:tt)+ ) => ( + $crate::event!( + target: module_path!(), + $lvl, + { message = format_args!($($arg)+), $($fields)* } + ) + ); + ( $lvl:expr, { $($fields:tt)* }, $($arg:tt)+ ) => ( + $crate::event!( + target: module_path!(), + $lvl, + { message = format_args!($($arg)+), $($fields)* } + ) + ); + ($lvl:expr, $($k:ident).+ = $($field:tt)*) => ( + $crate::event!( + target: module_path!(), + $lvl, + { $($k).+ = $($field)*} + ) + ); + ($lvl:expr, $($k:ident).+, $($field:tt)*) => ( + $crate::event!( + target: module_path!(), + $lvl, + { $($k).+, $($field)*} + ) + ); + ($lvl:expr, ?$($k:ident).+, $($field:tt)*) => ( + $crate::event!( + target: module_path!(), + $lvl, + { ?$($k).+, $($field)*} + ) + ); + ($lvl:expr, %$($k:ident).+, $($field:tt)*) => ( + $crate::event!( + target: module_path!(), + $lvl, + { %$($k).+, $($field)*} + ) + ); + ($lvl:expr, ?$($k:ident).+) => ( + $crate::event!($lvl, ?$($k).+,) + ); + ($lvl:expr, %$($k:ident).+) => ( + $crate::event!($lvl, %$($k).+,) + ); + ($lvl:expr, $($k:ident).+) => ( + $crate::event!($lvl, $($k).+,) + ); + ( $lvl:expr, $($arg:tt)+ ) => ( + $crate::event!(target: module_path!(), $lvl, { $($arg)+ }) + ); +} + +/// Constructs an event at the trace level. +/// +/// This functions similarly to the [`event!`] macro. See [the top-level +/// documentation][lib] for details on the syntax accepted by +/// this macro. +/// +/// [`event!`]: macro.event.html +/// [lib]: index.html#using-the-macros +/// +/// # Examples +/// +/// ```rust +/// use tracing::trace; +/// # #[derive(Debug, Copy, Clone)] struct Position { x: f32, y: f32 } +/// # impl Position { +/// # const ORIGIN: Self = Self { x: 0.0, y: 0.0 }; +/// # fn dist(&self, other: Position) -> f32 { +/// # let x = (other.x - self.x).exp2(); let y = (self.y - other.y).exp2(); +/// # (x + y).sqrt() +/// # } +/// # } +/// # fn main() { +/// let pos = Position { x: 3.234, y: -1.223 }; +/// let origin_dist = pos.dist(Position::ORIGIN); +/// +/// trace!(position = ?pos, ?origin_dist); +/// trace!( +/// target: "app_events", +/// position = ?pos, +/// "x is {} and y is {}", +/// if pos.x >= 0.0 { "positive" } else { "negative" }, +/// if pos.y >= 0.0 { "positive" } else { "negative" } +/// ); +/// # } +/// ``` +#[macro_export] +macro_rules! trace { + (target: $target:expr, parent: $parent:expr, { $($field:tt)* }, $($arg:tt)* ) => ( + $crate::event!(target: $target, parent: $parent, $crate::Level::TRACE, { $($field)* }, $($arg)*) + ); + (target: $target:expr, parent: $parent:expr, $($k:ident).+ $($field:tt)+ ) => ( + $crate::event!(target: $target, parent: $parent, $crate::Level::TRACE, { $($k).+ $($field)+ }) + ); + (target: $target:expr, parent: $parent:expr, ?$($k:ident).+ $($field:tt)+ ) => ( + $crate::event!(target: $target, parent: $parent, $crate::Level::TRACE, { $($k).+ $($field)+ }) + ); + (target: $target:expr, parent: $parent:expr, %$($k:ident).+ $($field:tt)+ ) => ( + $crate::event!(target: $target, parent: $parent, $crate::Level::TRACE, { $($k).+ $($field)+ }) + ); + (target: $target:expr, parent: $parent:expr, $($arg:tt)+ ) => ( + $crate::event!(target: $target, parent: $parent, $crate::Level::TRACE, {}, $($arg)+) + ); + (parent: $parent:expr, { $($field:tt)+ }, $($arg:tt)+ ) => ( + $crate::event!( + target: module_path!(), + parent: $parent, + $crate::Level::TRACE, + { $($field)+ }, + $($arg)+ + ) + ); + (parent: $parent:expr, $($k:ident).+ = $($field:tt)*) => ( + $crate::event!( + target: module_path!(), + parent: $parent, + $crate::Level::TRACE, + { $($k).+ = $($field)*} + ) + ); + (parent: $parent:expr, ?$($k:ident).+ = $($field:tt)*) => ( + $crate::event!( + target: module_path!(), + parent: $parent, + $crate::Level::TRACE, + { ?$($k).+ = $($field)*} + ) + ); + (parent: $parent:expr, %$($k:ident).+ = $($field:tt)*) => ( + $crate::event!( + target: module_path!(), + parent: $parent, + $crate::Level::TRACE, + { %$($k).+ = $($field)*} + ) + ); + (parent: $parent:expr, $($k:ident).+, $($field:tt)*) => ( + $crate::event!( + target: module_path!(), + parent: $parent, + $crate::Level::TRACE, + { $($k).+, $($field)*} + ) + ); + (parent: $parent:expr, ?$($k:ident).+, $($field:tt)*) => ( + $crate::event!( + target: module_path!(), + parent: $parent, + $crate::Level::TRACE, + { ?$($k).+, $($field)*} + ) + ); + (parent: $parent:expr, %$($k:ident).+, $($field:tt)*) => ( + $crate::event!( + target: module_path!(), + parent: $parent, + $crate::Level::TRACE, + { %$($k).+, $($field)*} + ) + ); + (parent: $parent:expr, $($arg:tt)+) => ( + $crate::event!( + target: module_path!(), + parent: $parent, + $crate::Level::TRACE, + {}, + $($arg)+ + ) + ); + (target: $target:expr, { $($field:tt)* }, $($arg:tt)* ) => ( + $crate::event!(target: $target, $crate::Level::TRACE, { $($field)* }, $($arg)*) + ); + (target: $target:expr, $($k:ident).+ $($field:tt)+ ) => ( + $crate::event!(target: $target, $crate::Level::TRACE, { $($k).+ $($field)+ }) + ); + (target: $target:expr, ?$($k:ident).+ $($field:tt)+ ) => ( + $crate::event!(target: $target, $crate::Level::TRACE, { $($k).+ $($field)+ }) + ); + (target: $target:expr, %$($k:ident).+ $($field:tt)+ ) => ( + $crate::event!(target: $target, $crate::Level::TRACE, { $($k).+ $($field)+ }) + ); + (target: $target:expr, $($arg:tt)+ ) => ( + $crate::event!(target: $target, $crate::Level::TRACE, {}, $($arg)+) + ); + ({ $($field:tt)+ }, $($arg:tt)+ ) => ( + $crate::event!( + target: module_path!(), + $crate::Level::TRACE, + { $($field)+ }, + $($arg)+ + ) + ); + ($($k:ident).+ = $($field:tt)*) => ( + $crate::event!( + target: module_path!(), + $crate::Level::TRACE, + { $($k).+ = $($field)*} + ) + ); + ($($k:ident).+, $($field:tt)*) => ( + $crate::event!( + target: module_path!(), + $crate::Level::TRACE, + { $($k).+, $($field)*} + ) + ); + (?$($k:ident).+, $($field:tt)*) => ( + $crate::event!( + target: module_path!(), + $crate::Level::TRACE, + { ?$($k).+, $($field)*} + ) + ); + (%$($k:ident).+, $($field:tt)*) => ( + $crate::event!( + target: module_path!(), + $crate::Level::TRACE, + { %$($k).+, $($field)*} + ) + ); + (?$($k:ident).+) => ( + $crate::event!( + target: module_path!(), + $crate::Level::TRACE, + { ?$($k).+ } + ) + ); + (%$($k:ident).+) => ( + $crate::event!( + target: module_path!(), + $crate::Level::TRACE, + { %$($k).+ } + ) + ); + ($($k:ident).+) => ( + $crate::event!( + target: module_path!(), + $crate::Level::TRACE, + { $($k).+ } + ) + ); + ($($arg:tt)+) => ( + $crate::event!( + target: module_path!(), + $crate::Level::TRACE, + {}, + $($arg)+ + ) + ); +} + +/// Constructs an event at the debug level. +/// +/// This functions similarly to the [`event!`] macro. See [the top-level +/// documentation][lib] for details on the syntax accepted by +/// this macro. +/// +/// [`event!`]: macro.event.html +/// [lib]: index.html#using-the-macros +/// +/// # Examples +/// +/// ```rust +/// use tracing::debug; +/// # fn main() { +/// # #[derive(Debug)] struct Position { x: f32, y: f32 } +/// +/// let pos = Position { x: 3.234, y: -1.223 }; +/// +/// debug!(?pos.x, ?pos.y); +/// debug!(target: "app_events", position = ?pos, "New position"); +/// # } +/// ``` +#[macro_export] +macro_rules! debug { + (target: $target:expr, parent: $parent:expr, { $($field:tt)* }, $($arg:tt)* ) => ( + $crate::event!(target: $target, parent: $parent, $crate::Level::DEBUG, { $($field)* }, $($arg)*) + ); + (target: $target:expr, parent: $parent:expr, $($k:ident).+ $($field:tt)+ ) => ( + $crate::event!(target: $target, parent: $parent, $crate::Level::DEBUG, { $($k).+ $($field)+ }) + ); + (target: $target:expr, parent: $parent:expr, ?$($k:ident).+ $($field:tt)+ ) => ( + $crate::event!(target: $target, parent: $parent, $crate::Level::DEBUG, { $($k).+ $($field)+ }) + ); + (target: $target:expr, parent: $parent:expr, %$($k:ident).+ $($field:tt)+ ) => ( + $crate::event!(target: $target, parent: $parent, $crate::Level::DEBUG, { $($k).+ $($field)+ }) + ); + (target: $target:expr, parent: $parent:expr, $($arg:tt)+ ) => ( + $crate::event!(target: $target, parent: $parent, $crate::Level::DEBUG, {}, $($arg)+) + ); + (parent: $parent:expr, { $($field:tt)+ }, $($arg:tt)+ ) => ( + $crate::event!( + target: module_path!(), + parent: $parent, + $crate::Level::DEBUG, + { $($field)+ }, + $($arg)+ + ) + ); + (parent: $parent:expr, $($k:ident).+ = $($field:tt)*) => ( + $crate::event!( + target: module_path!(), + parent: $parent, + $crate::Level::DEBUG, + { $($k).+ = $($field)*} + ) + ); + (parent: $parent:expr, ?$($k:ident).+ = $($field:tt)*) => ( + $crate::event!( + target: module_path!(), + parent: $parent, + $crate::Level::DEBUG, + { ?$($k).+ = $($field)*} + ) + ); + (parent: $parent:expr, %$($k:ident).+ = $($field:tt)*) => ( + $crate::event!( + target: module_path!(), + parent: $parent, + $crate::Level::DEBUG, + { %$($k).+ = $($field)*} + ) + ); + (parent: $parent:expr, $($k:ident).+, $($field:tt)*) => ( + $crate::event!( + target: module_path!(), + parent: $parent, + $crate::Level::DEBUG, + { $($k).+, $($field)*} + ) + ); + (parent: $parent:expr, ?$($k:ident).+, $($field:tt)*) => ( + $crate::event!( + target: module_path!(), + parent: $parent, + $crate::Level::DEBUG, + { ?$($k).+, $($field)*} + ) + ); + (parent: $parent:expr, %$($k:ident).+, $($field:tt)*) => ( + $crate::event!( + target: module_path!(), + parent: $parent, + $crate::Level::DEBUG, + { %$($k).+, $($field)*} + ) + ); + (parent: $parent:expr, $($arg:tt)+) => ( + $crate::event!( + target: module_path!(), + parent: $parent, + $crate::Level::DEBUG, + {}, + $($arg)+ + ) + ); + (target: $target:expr, { $($field:tt)* }, $($arg:tt)* ) => ( + $crate::event!(target: $target, $crate::Level::DEBUG, { $($field)* }, $($arg)*) + ); + (target: $target:expr, $($k:ident).+ $($field:tt)+ ) => ( + $crate::event!(target: $target, $crate::Level::DEBUG, { $($k).+ $($field)+ }) + ); + (target: $target:expr, ?$($k:ident).+ $($field:tt)+ ) => ( + $crate::event!(target: $target, $crate::Level::DEBUG, { $($k).+ $($field)+ }) + ); + (target: $target:expr, %$($k:ident).+ $($field:tt)+ ) => ( + $crate::event!(target: $target, $crate::Level::DEBUG, { $($k).+ $($field)+ }) + ); + (target: $target:expr, $($arg:tt)+ ) => ( + $crate::event!(target: $target, $crate::Level::DEBUG, {}, $($arg)+) + ); + ({ $($field:tt)+ }, $($arg:tt)+ ) => ( + $crate::event!( + target: module_path!(), + $crate::Level::DEBUG, + { $($field)+ }, + $($arg)+ + ) + ); + ($($k:ident).+ = $($field:tt)*) => ( + $crate::event!( + target: module_path!(), + $crate::Level::DEBUG, + { $($k).+ = $($field)*} + ) + ); + (?$($k:ident).+ = $($field:tt)*) => ( + $crate::event!( + target: module_path!(), + $crate::Level::DEBUG, + { ?$($k).+ = $($field)*} + ) + ); + (%$($k:ident).+ = $($field:tt)*) => ( + $crate::event!( + target: module_path!(), + $crate::Level::DEBUG, + { %$($k).+ = $($field)*} + ) + ); + ($($k:ident).+, $($field:tt)*) => ( + $crate::event!( + target: module_path!(), + $crate::Level::DEBUG, + { $($k).+, $($field)*} + ) + ); + (?$($k:ident).+, $($field:tt)*) => ( + $crate::event!( + target: module_path!(), + $crate::Level::DEBUG, + { ?$($k).+, $($field)*} + ) + ); + (%$($k:ident).+, $($field:tt)*) => ( + $crate::event!( + target: module_path!(), + $crate::Level::DEBUG, + { %$($k).+, $($field)*} + ) + ); + (?$($k:ident).+) => ( + $crate::event!( + target: module_path!(), + $crate::Level::DEBUG, + { ?$($k).+ } + ) + ); + (%$($k:ident).+) => ( + $crate::event!( + target: module_path!(), + $crate::Level::DEBUG, + { %$($k).+ } + ) + ); + ($($k:ident).+) => ( + $crate::event!( + target: module_path!(), + $crate::Level::DEBUG, + { $($k).+ } + ) + ); + ($($arg:tt)+) => ( + $crate::event!( + target: module_path!(), + $crate::Level::DEBUG, + {}, + $($arg)+ + ) + ); +} + +/// Constructs an event at the info level. +/// +/// This functions similarly to the [`event!`] macro. See [the top-level +/// documentation][lib] for details on the syntax accepted by +/// this macro. +/// +/// [`event!`]: macro.event.html +/// [lib]: index.html#using-the-macros +/// +/// # Examples +/// +/// ```rust +/// use tracing::info; +/// # // this is so the test will still work in no-std mode +/// # #[derive(Debug)] +/// # pub struct Ipv4Addr; +/// # impl Ipv4Addr { fn new(o1: u8, o2: u8, o3: u8, o4: u8) -> Self { Self } } +/// # fn main() { +/// # struct Connection { port: u32, speed: f32 } +/// use tracing::field; +/// +/// let addr = Ipv4Addr::new(127, 0, 0, 1); +/// let conn = Connection { port: 40, speed: 3.20 }; +/// +/// info!(conn.port, "connected to {:?}", addr); +/// info!( +/// target: "connection_events", +/// ip = ?addr, +/// conn.port, +/// ?conn.speed, +/// ); +/// # } +/// ``` +#[macro_export] +macro_rules! info { + (target: $target:expr, parent: $parent:expr, { $($field:tt)* }, $($arg:tt)* ) => ( + $crate::event!(target: $target, parent: $parent, $crate::Level::INFO, { $($field)* }, $($arg)*) + ); + (target: $target:expr, parent: $parent:expr, $($k:ident).+ $($field:tt)+ ) => ( + $crate::event!(target: $target, parent: $parent, $crate::Level::INFO, { $($k).+ $($field)+ }) + ); + (target: $target:expr, parent: $parent:expr, ?$($k:ident).+ $($field:tt)+ ) => ( + $crate::event!(target: $target, parent: $parent, $crate::Level::INFO, { $($k).+ $($field)+ }) + ); + (target: $target:expr, parent: $parent:expr, %$($k:ident).+ $($field:tt)+ ) => ( + $crate::event!(target: $target, parent: $parent, $crate::Level::INFO, { $($k).+ $($field)+ }) + ); + (target: $target:expr, parent: $parent:expr, $($arg:tt)+ ) => ( + $crate::event!(target: $target, parent: $parent, $crate::Level::INFO, {}, $($arg)+) + ); + (parent: $parent:expr, { $($field:tt)+ }, $($arg:tt)+ ) => ( + $crate::event!( + target: module_path!(), + parent: $parent, + $crate::Level::INFO, + { $($field)+ }, + $($arg)+ + ) + ); + (parent: $parent:expr, $($k:ident).+ = $($field:tt)*) => ( + $crate::event!( + target: module_path!(), + parent: $parent, + $crate::Level::INFO, + { $($k).+ = $($field)*} + ) + ); + (parent: $parent:expr, ?$($k:ident).+ = $($field:tt)*) => ( + $crate::event!( + target: module_path!(), + parent: $parent, + $crate::Level::INFO, + { ?$($k).+ = $($field)*} + ) + ); + (parent: $parent:expr, %$($k:ident).+ = $($field:tt)*) => ( + $crate::event!( + target: module_path!(), + parent: $parent, + $crate::Level::INFO, + { %$($k).+ = $($field)*} + ) + ); + (parent: $parent:expr, $($k:ident).+, $($field:tt)*) => ( + $crate::event!( + target: module_path!(), + parent: $parent, + $crate::Level::INFO, + { $($k).+, $($field)*} + ) + ); + (parent: $parent:expr, ?$($k:ident).+, $($field:tt)*) => ( + $crate::event!( + target: module_path!(), + parent: $parent, + $crate::Level::INFO, + { ?$($k).+, $($field)*} + ) + ); + (parent: $parent:expr, %$($k:ident).+, $($field:tt)*) => ( + $crate::event!( + target: module_path!(), + parent: $parent, + $crate::Level::INFO, + { %$($k).+, $($field)*} + ) + ); + (parent: $parent:expr, $($arg:tt)+) => ( + $crate::event!( + target: module_path!(), + parent: $parent, + $crate::Level::INFO, + {}, + $($arg)+ + ) + ); + (target: $target:expr, { $($field:tt)* }, $($arg:tt)* ) => ( + $crate::event!(target: $target, $crate::Level::INFO, { $($field)* }, $($arg)*) + ); + (target: $target:expr, $($k:ident).+ $($field:tt)+ ) => ( + $crate::event!(target: $target, $crate::Level::INFO, { $($k).+ $($field)+ }) + ); + (target: $target:expr, ?$($k:ident).+ $($field:tt)+ ) => ( + $crate::event!(target: $target, $crate::Level::INFO, { $($k).+ $($field)+ }) + ); + (target: $target:expr, %$($k:ident).+ $($field:tt)+ ) => ( + $crate::event!(target: $target, $crate::Level::INFO, { $($k).+ $($field)+ }) + ); + (target: $target:expr, $($arg:tt)+ ) => ( + $crate::event!(target: $target, $crate::Level::INFO, {}, $($arg)+) + ); + ({ $($field:tt)+ }, $($arg:tt)+ ) => ( + $crate::event!( + target: module_path!(), + $crate::Level::INFO, + { $($field)+ }, + $($arg)+ + ) + ); + ($($k:ident).+ = $($field:tt)*) => ( + $crate::event!( + target: module_path!(), + $crate::Level::INFO, + { $($k).+ = $($field)*} + ) + ); + (?$($k:ident).+ = $($field:tt)*) => ( + $crate::event!( + target: module_path!(), + $crate::Level::INFO, + { ?$($k).+ = $($field)*} + ) + ); + (%$($k:ident).+ = $($field:tt)*) => ( + $crate::event!( + target: module_path!(), + $crate::Level::TRACE, + { %$($k).+ = $($field)*} + ) + ); + ($($k:ident).+, $($field:tt)*) => ( + $crate::event!( + target: module_path!(), + $crate::Level::INFO, + { $($k).+, $($field)*} + ) + ); + (?$($k:ident).+, $($field:tt)*) => ( + $crate::event!( + target: module_path!(), + $crate::Level::INFO, + { ?$($k).+, $($field)*} + ) + ); + (%$($k:ident).+, $($field:tt)*) => ( + $crate::event!( + target: module_path!(), + $crate::Level::INFO, + { %$($k).+, $($field)*} + ) + ); + (?$($k:ident).+) => ( + $crate::event!( + target: module_path!(), + $crate::Level::INFO, + { ?$($k).+ } + ) + ); + (%$($k:ident).+) => ( + $crate::event!( + target: module_path!(), + $crate::Level::INFO, + { %$($k).+ } + ) + ); + ($($k:ident).+) => ( + $crate::event!( + target: module_path!(), + $crate::Level::INFO, + { $($k).+ } + ) + ); + ($($arg:tt)+) => ( + $crate::event!( + target: module_path!(), + $crate::Level::INFO, + {}, + $($arg)+ + ) + ); +} + +/// Constructs an event at the warn level. +/// +/// This functions similarly to the [`event!`] macro. See [the top-level +/// documentation][lib] for details on the syntax accepted by +/// this macro. +/// +/// [`event!`]: macro.event.html +/// [lib]: index.html#using-the-macros +/// +/// # Examples +/// +/// ```rust +/// use tracing::warn; +/// # fn main() { +/// +/// let warn_description = "Invalid Input"; +/// let input = &[0x27, 0x45]; +/// +/// warn!(?input, warning = warn_description); +/// warn!( +/// target: "input_events", +/// warning = warn_description, +/// "Received warning for input: {:?}", input, +/// ); +/// # } +/// ``` +#[macro_export] +macro_rules! warn { + (target: $target:expr, parent: $parent:expr, { $($field:tt)* }, $($arg:tt)* ) => ( + $crate::event!(target: $target, parent: $parent, $crate::Level::WARN, { $($field)* }, $($arg)*) + ); + (target: $target:expr, parent: $parent:expr, $($k:ident).+ $($field:tt)+ ) => ( + $crate::event!(target: $target, parent: $parent, $crate::Level::WARN, { $($k).+ $($field)+ }) + ); + (target: $target:expr, parent: $parent:expr, ?$($k:ident).+ $($field:tt)+ ) => ( + $crate::event!(target: $target, parent: $parent, $crate::Level::WARN, { $($k).+ $($field)+ }) + ); + (target: $target:expr, parent: $parent:expr, %$($k:ident).+ $($field:tt)+ ) => ( + $crate::event!(target: $target, parent: $parent, $crate::Level::WARN, { $($k).+ $($field)+ }) + ); + (target: $target:expr, parent: $parent:expr, $($arg:tt)+ ) => ( + $crate::event!(target: $target, parent: $parent, $crate::Level::WARN, {}, $($arg)+) + ); + (parent: $parent:expr, { $($field:tt)+ }, $($arg:tt)+ ) => ( + $crate::event!( + target: module_path!(), + parent: $parent, + $crate::Level::WARN, + { $($field)+ }, + $($arg)+ + ) + ); + (parent: $parent:expr, $($k:ident).+ = $($field:tt)*) => ( + $crate::event!( + target: module_path!(), + parent: $parent, + $crate::Level::WARN, + { $($k).+ = $($field)*} + ) + ); + (parent: $parent:expr, ?$($k:ident).+ = $($field:tt)*) => ( + $crate::event!( + target: module_path!(), + parent: $parent, + $crate::Level::WARN, + { ?$($k).+ = $($field)*} + ) + ); + (parent: $parent:expr, %$($k:ident).+ = $($field:tt)*) => ( + $crate::event!( + target: module_path!(), + parent: $parent, + $crate::Level::WARN, + { %$($k).+ = $($field)*} + ) + ); + (parent: $parent:expr, $($k:ident).+, $($field:tt)*) => ( + $crate::event!( + target: module_path!(), + parent: $parent, + $crate::Level::WARN, + { $($k).+, $($field)*} + ) + ); + (parent: $parent:expr, ?$($k:ident).+, $($field:tt)*) => ( + $crate::event!( + target: module_path!(), + parent: $parent, + $crate::Level::WARN, + { ?$($k).+, $($field)*} + ) + ); + (parent: $parent:expr, %$($k:ident).+, $($field:tt)*) => ( + $crate::event!( + target: module_path!(), + parent: $parent, + $crate::Level::WARN, + { %$($k).+, $($field)*} + ) + ); + (parent: $parent:expr, $($arg:tt)+) => ( + $crate::event!( + target: module_path!(), + parent: $parent, + $crate::Level::WARN, + {}, + $($arg)+ + ) + ); + (target: $target:expr, { $($field:tt)* }, $($arg:tt)* ) => ( + $crate::event!(target: $target, $crate::Level::WARN, { $($field)* }, $($arg)*) + ); + (target: $target:expr, $($k:ident).+ $($field:tt)+ ) => ( + $crate::event!(target: $target, $crate::Level::WARN, { $($k).+ $($field)+ }) + ); + (target: $target:expr, ?$($k:ident).+ $($field:tt)+ ) => ( + $crate::event!(target: $target, $crate::Level::WARN, { $($k).+ $($field)+ }) + ); + (target: $target:expr, %$($k:ident).+ $($field:tt)+ ) => ( + $crate::event!(target: $target, $crate::Level::WARN, { $($k).+ $($field)+ }) + ); + (target: $target:expr, $($arg:tt)+ ) => ( + $crate::event!(target: $target, $crate::Level::WARN, {}, $($arg)+) + ); + ({ $($field:tt)+ }, $($arg:tt)+ ) => ( + $crate::event!( + target: module_path!(), + $crate::Level::WARN, + { $($field)+ }, + $($arg)+ + ) + ); + ($($k:ident).+ = $($field:tt)*) => ( + $crate::event!( + target: module_path!(), + $crate::Level::WARN, + { $($k).+ = $($field)*} + ) + ); + (?$($k:ident).+ = $($field:tt)*) => ( + $crate::event!( + target: module_path!(), + $crate::Level::WARN, + { ?$($k).+ = $($field)*} + ) + ); + (%$($k:ident).+ = $($field:tt)*) => ( + $crate::event!( + target: module_path!(), + $crate::Level::TRACE, + { %$($k).+ = $($field)*} + ) + ); + ($($k:ident).+, $($field:tt)*) => ( + $crate::event!( + target: module_path!(), + $crate::Level::WARN, + { $($k).+, $($field)*} + ) + ); + (?$($k:ident).+, $($field:tt)*) => ( + $crate::event!( + target: module_path!(), + $crate::Level::WARN, + { ?$($k).+, $($field)*} + ) + ); + (%$($k:ident).+, $($field:tt)*) => ( + $crate::event!( + target: module_path!(), + $crate::Level::WARN, + { %$($k).+, $($field)*} + ) + ); + (?$($k:ident).+) => ( + $crate::event!( + target: module_path!(), + $crate::Level::WARN, + { ?$($k).+ } + ) + ); + (%$($k:ident).+) => ( + $crate::event!( + target: module_path!(), + $crate::Level::WARN, + { %$($k).+ } + ) + ); + ($($k:ident).+) => ( + $crate::event!( + target: module_path!(), + $crate::Level::WARN, + { $($k).+ } + ) + ); + ($($arg:tt)+) => ( + $crate::event!( + target: module_path!(), + $crate::Level::WARN, + {}, + $($arg)+ + ) + ); +} + +/// Constructs an event at the error level. +/// +/// This functions similarly to the [`event!`] macro. See [the top-level +/// documentation][lib] for details on the syntax accepted by +/// this macro. +/// +/// [`event!`]: macro.event.html +/// [lib]: index.html#using-the-macros +/// +/// # Examples +/// +/// ```rust +/// use tracing::error; +/// # fn main() { +/// +/// let (err_info, port) = ("No connection", 22); +/// +/// error!(port, error = %err_info); +/// error!(target: "app_events", "App Error: {}", err_info); +/// error!({ info = err_info }, "error on port: {}", port); +/// # } +/// ``` +#[macro_export] +macro_rules! error { + (target: $target:expr, parent: $parent:expr, { $($field:tt)* }, $($arg:tt)* ) => ( + $crate::event!(target: $target, parent: $parent, $crate::Level::ERROR, { $($field)* }, $($arg)*) + ); + (target: $target:expr, parent: $parent:expr, $($k:ident).+ $($field:tt)+ ) => ( + $crate::event!(target: $target, parent: $parent, $crate::Level::ERROR, { $($k).+ $($field)+ }) + ); + (target: $target:expr, parent: $parent:expr, ?$($k:ident).+ $($field:tt)+ ) => ( + $crate::event!(target: $target, parent: $parent, $crate::Level::ERROR, { $($k).+ $($field)+ }) + ); + (target: $target:expr, parent: $parent:expr, %$($k:ident).+ $($field:tt)+ ) => ( + $crate::event!(target: $target, parent: $parent, $crate::Level::ERROR, { $($k).+ $($field)+ }) + ); + (target: $target:expr, parent: $parent:expr, $($arg:tt)+ ) => ( + $crate::event!(target: $target, parent: $parent, $crate::Level::ERROR, {}, $($arg)+) + ); + (parent: $parent:expr, { $($field:tt)+ }, $($arg:tt)+ ) => ( + $crate::event!( + target: module_path!(), + parent: $parent, + $crate::Level::ERROR, + { $($field)+ }, + $($arg)+ + ) + ); + (parent: $parent:expr, $($k:ident).+ = $($field:tt)*) => ( + $crate::event!( + target: module_path!(), + parent: $parent, + $crate::Level::ERROR, + { $($k).+ = $($field)*} + ) + ); + (parent: $parent:expr, ?$($k:ident).+ = $($field:tt)*) => ( + $crate::event!( + target: module_path!(), + parent: $parent, + $crate::Level::ERROR, + { ?$($k).+ = $($field)*} + ) + ); + (parent: $parent:expr, %$($k:ident).+ = $($field:tt)*) => ( + $crate::event!( + target: module_path!(), + parent: $parent, + $crate::Level::ERROR, + { %$($k).+ = $($field)*} + ) + ); + (parent: $parent:expr, $($k:ident).+, $($field:tt)*) => ( + $crate::event!( + target: module_path!(), + parent: $parent, + $crate::Level::ERROR, + { $($k).+, $($field)*} + ) + ); + (parent: $parent:expr, ?$($k:ident).+, $($field:tt)*) => ( + $crate::event!( + target: module_path!(), + parent: $parent, + $crate::Level::ERROR, + { ?$($k).+, $($field)*} + ) + ); + (parent: $parent:expr, %$($k:ident).+, $($field:tt)*) => ( + $crate::event!( + target: module_path!(), + parent: $parent, + $crate::Level::ERROR, + { %$($k).+, $($field)*} + ) + ); + (parent: $parent:expr, $($arg:tt)+) => ( + $crate::event!( + target: module_path!(), + parent: $parent, + $crate::Level::ERROR, + {}, + $($arg)+ + ) + ); + (target: $target:expr, { $($field:tt)* }, $($arg:tt)* ) => ( + $crate::event!(target: $target, $crate::Level::ERROR, { $($field)* }, $($arg)*) + ); + (target: $target:expr, $($k:ident).+ $($field:tt)+ ) => ( + $crate::event!(target: $target, $crate::Level::ERROR, { $($k).+ $($field)+ }) + ); + (target: $target:expr, ?$($k:ident).+ $($field:tt)+ ) => ( + $crate::event!(target: $target, $crate::Level::ERROR, { $($k).+ $($field)+ }) + ); + (target: $target:expr, %$($k:ident).+ $($field:tt)+ ) => ( + $crate::event!(target: $target, $crate::Level::ERROR, { $($k).+ $($field)+ }) + ); + (target: $target:expr, $($arg:tt)+ ) => ( + $crate::event!(target: $target, $crate::Level::ERROR, {}, $($arg)+) + ); + ({ $($field:tt)+ }, $($arg:tt)+ ) => ( + $crate::event!( + target: module_path!(), + $crate::Level::ERROR, + { $($field)+ }, + $($arg)+ + ) + ); + ($($k:ident).+ = $($field:tt)*) => ( + $crate::event!( + target: module_path!(), + $crate::Level::ERROR, + { $($k).+ = $($field)*} + ) + ); + (?$($k:ident).+ = $($field:tt)*) => ( + $crate::event!( + target: module_path!(), + $crate::Level::ERROR, + { ?$($k).+ = $($field)*} + ) + ); + (%$($k:ident).+ = $($field:tt)*) => ( + $crate::event!( + target: module_path!(), + $crate::Level::TRACE, + { %$($k).+ = $($field)*} + ) + ); + ($($k:ident).+, $($field:tt)*) => ( + $crate::event!( + target: module_path!(), + $crate::Level::ERROR, + { $($k).+, $($field)*} + ) + ); + (?$($k:ident).+, $($field:tt)*) => ( + $crate::event!( + target: module_path!(), + $crate::Level::ERROR, + { ?$($k).+, $($field)*} + ) + ); + (%$($k:ident).+, $($field:tt)*) => ( + $crate::event!( + target: module_path!(), + $crate::Level::ERROR, + { %$($k).+, $($field)*} + ) + ); + (?$($k:ident).+) => ( + $crate::event!( + target: module_path!(), + $crate::Level::ERROR, + { ?$($k).+ } + ) + ); + (%$($k:ident).+) => ( + $crate::event!( + target: module_path!(), + $crate::Level::ERROR, + { %$($k).+ } + ) + ); + ($($k:ident).+) => ( + $crate::event!( + target: module_path!(), + $crate::Level::ERROR, + { $($k).+ } + ) + ); + ($($arg:tt)+) => ( + $crate::event!( + target: module_path!(), + $crate::Level::ERROR, + {}, + $($arg)+ + ) + ); +} + +/// Constructs a new static callsite for a span or event. +#[doc(hidden)] +#[macro_export] +macro_rules! callsite { + (name: $name:expr, kind: $kind:expr, fields: $($fields:tt)*) => {{ + $crate::callsite! { + name: $name, + kind: $kind, + target: module_path!(), + level: $crate::Level::TRACE, + fields: $($fields)* + } + }}; + ( + name: $name:expr, + kind: $kind:expr, + level: $lvl:expr, + fields: $($fields:tt)* + ) => {{ + $crate::callsite! { + name: $name, + kind: $kind, + target: module_path!(), + level: $lvl, + fields: $($fields)* + } + }}; + ( + name: $name:expr, + kind: $kind:expr, + target: $target:expr, + level: $lvl:expr, + fields: $($fields:tt)* + ) => {{ + use $crate::__macro_support::MacroCallsite; + static META: $crate::Metadata<'static> = { + $crate::metadata! { + name: $name, + target: $target, + level: $lvl, + fields: $crate::fieldset!( $($fields)* ), + callsite: &CALLSITE, + kind: $kind, + } + }; + static CALLSITE: MacroCallsite = MacroCallsite::new(&META); + CALLSITE.register(); + &CALLSITE + }}; +} + +/// Constructs a new static callsite for a span or event. +#[doc(hidden)] +#[macro_export] +macro_rules! callsite2 { + (name: $name:expr, kind: $kind:expr, fields: $($fields:tt)*) => {{ + $crate::callsite2! { + name: $name, + kind: $kind, + target: module_path!(), + level: $crate::Level::TRACE, + fields: $($fields)* + } + }}; + ( + name: $name:expr, + kind: $kind:expr, + level: $lvl:expr, + fields: $($fields:tt)* + ) => {{ + $crate::callsite2! { + name: $name, + kind: $kind, + target: module_path!(), + level: $lvl, + fields: $($fields)* + } + }}; + ( + name: $name:expr, + kind: $kind:expr, + target: $target:expr, + level: $lvl:expr, + fields: $($fields:tt)* + ) => {{ + use $crate::__macro_support::MacroCallsite; + static META: $crate::Metadata<'static> = { + $crate::metadata! { + name: $name, + target: $target, + level: $lvl, + fields: $crate::fieldset!( $($fields)* ), + callsite: &CALLSITE, + kind: $kind, + } + }; + MacroCallsite::new(&META) + }}; +} + +#[macro_export] +// TODO: determine if this ought to be public API?` +#[doc(hidden)] +macro_rules! level_enabled { + ($lvl:expr) => { + $lvl <= $crate::level_filters::STATIC_MAX_LEVEL + && $lvl <= $crate::level_filters::LevelFilter::current() + }; +} + +#[doc(hidden)] +#[macro_export] +macro_rules! valueset { + + // === base case === + (@ { $(,)* $($val:expr),* $(,)* }, $next:expr $(,)*) => { + &[ $($val),* ] + }; + + // === recursive case (more tts) === + + // TODO(#1138): determine a new syntax for uninitialized span fields, and + // re-enable this. + // (@{ $(,)* $($out:expr),* }, $next:expr, $($k:ident).+ = _, $($rest:tt)*) => { + // $crate::valueset!(@ { $($out),*, (&$next, None) }, $next, $($rest)*) + // }; + (@ { $(,)* $($out:expr),* }, $next:expr, $($k:ident).+ = ?$val:expr, $($rest:tt)*) => { + $crate::valueset!( + @ { $($out),*, (&$next, Some(&debug(&$val) as &Value)) }, + $next, + $($rest)* + ) + }; + (@ { $(,)* $($out:expr),* }, $next:expr, $($k:ident).+ = %$val:expr, $($rest:tt)*) => { + $crate::valueset!( + @ { $($out),*, (&$next, Some(&display(&$val) as &Value)) }, + $next, + $($rest)* + ) + }; + (@ { $(,)* $($out:expr),* }, $next:expr, $($k:ident).+ = $val:expr, $($rest:tt)*) => { + $crate::valueset!( + @ { $($out),*, (&$next, Some(&$val as &Value)) }, + $next, + $($rest)* + ) + }; + (@ { $(,)* $($out:expr),* }, $next:expr, $($k:ident).+, $($rest:tt)*) => { + $crate::valueset!( + @ { $($out),*, (&$next, Some(&$($k).+ as &Value)) }, + $next, + $($rest)* + ) + }; + (@ { $(,)* $($out:expr),* }, $next:expr, ?$($k:ident).+, $($rest:tt)*) => { + $crate::valueset!( + @ { $($out),*, (&$next, Some(&debug(&$($k).+) as &Value)) }, + $next, + $($rest)* + ) + }; + (@ { $(,)* $($out:expr),* }, $next:expr, %$($k:ident).+, $($rest:tt)*) => { + $crate::valueset!( + @ { $($out),*, (&$next, Some(&display(&$($k).+) as &Value)) }, + $next, + $($rest)* + ) + }; + (@ { $(,)* $($out:expr),* }, $next:expr, $($k:ident).+ = ?$val:expr) => { + $crate::valueset!( + @ { $($out),*, (&$next, Some(&debug(&$val) as &Value)) }, + $next, + ) + }; + (@ { $(,)* $($out:expr),* }, $next:expr, $($k:ident).+ = %$val:expr) => { + $crate::valueset!( + @ { $($out),*, (&$next, Some(&display(&$val) as &Value)) }, + $next, + ) + }; + (@ { $(,)* $($out:expr),* }, $next:expr, $($k:ident).+ = $val:expr) => { + $crate::valueset!( + @ { $($out),*, (&$next, Some(&$val as &Value)) }, + $next, + ) + }; + (@ { $(,)* $($out:expr),* }, $next:expr, $($k:ident).+) => { + $crate::valueset!( + @ { $($out),*, (&$next, Some(&$($k).+ as &Value)) }, + $next, + ) + }; + (@ { $(,)* $($out:expr),* }, $next:expr, ?$($k:ident).+) => { + $crate::valueset!( + @ { $($out),*, (&$next, Some(&debug(&$($k).+) as &Value)) }, + $next, + ) + }; + (@ { $(,)* $($out:expr),* }, $next:expr, %$($k:ident).+) => { + $crate::valueset!( + @ { $($out),*, (&$next, Some(&display(&$($k).+) as &Value)) }, + $next, + ) + }; + + // Handle literal names + (@ { $(,)* $($out:expr),* }, $next:expr, $k:literal = ?$val:expr, $($rest:tt)*) => { + $crate::valueset!( + @ { $($out),*, (&$next, Some(&debug(&$val) as &Value)) }, + $next, + $($rest)* + ) + }; + (@ { $(,)* $($out:expr),* }, $next:expr, $k:literal = %$val:expr, $($rest:tt)*) => { + $crate::valueset!( + @ { $($out),*, (&$next, Some(&display(&$val) as &Value)) }, + $next, + $($rest)* + ) + }; + (@ { $(,)* $($out:expr),* }, $next:expr, $k:literal = $val:expr, $($rest:tt)*) => { + $crate::valueset!( + @ { $($out),*, (&$next, Some(&$val as &Value)) }, + $next, + $($rest)* + ) + }; + (@ { $(,)* $($out:expr),* }, $next:expr, $k:literal = ?$val:expr) => { + $crate::valueset!( + @ { $($out),*, (&$next, Some(&debug(&$val) as &Value)) }, + $next, + ) + }; + (@ { $(,)* $($out:expr),* }, $next:expr, $k:literal = %$val:expr) => { + $crate::valueset!( + @ { $($out),*, (&$next, Some(&display(&$val) as &Value)) }, + $next, + ) + }; + (@ { $(,)* $($out:expr),* }, $next:expr, $k:literal = $val:expr) => { + $crate::valueset!( + @ { $($out),*, (&$next, Some(&$val as &Value)) }, + $next, + ) + }; + + // Remainder is unparseable, but exists --- must be format args! + (@ { $(,)* $($out:expr),* }, $next:expr, $($rest:tt)+) => { + $crate::valueset!(@ { (&$next, Some(&format_args!($($rest)+) as &Value)), $($out),* }, $next, ) + }; + + // === entry === + ($fields:expr, $($kvs:tt)+) => { + { + #[allow(unused_imports)] + use $crate::field::{debug, display, Value}; + let mut iter = $fields.iter(); + $fields.value_set($crate::valueset!( + @ { }, + iter.next().expect("FieldSet corrupted (this is a bug)"), + $($kvs)+ + )) + } + }; + ($fields:expr,) => { + { + $fields.value_set(&[]) + } + }; +} + +#[doc(hidden)] +#[macro_export] +macro_rules! fieldset { + // == base case == + (@ { $(,)* $($out:expr),* $(,)* } $(,)*) => { + &[ $($out),* ] + }; + + // == recursive cases (more tts) == + (@ { $(,)* $($out:expr),* } $($k:ident).+ = ?$val:expr, $($rest:tt)*) => { + $crate::fieldset!(@ { $($out),*, $crate::__tracing_stringify!($($k).+) } $($rest)*) + }; + (@ { $(,)* $($out:expr),* } $($k:ident).+ = %$val:expr, $($rest:tt)*) => { + $crate::fieldset!(@ { $($out),*, $crate::__tracing_stringify!($($k).+) } $($rest)*) + }; + (@ { $(,)* $($out:expr),* } $($k:ident).+ = $val:expr, $($rest:tt)*) => { + $crate::fieldset!(@ { $($out),*, $crate::__tracing_stringify!($($k).+) } $($rest)*) + }; + // TODO(#1138): determine a new syntax for uninitialized span fields, and + // re-enable this. + // (@ { $($out:expr),* } $($k:ident).+ = _, $($rest:tt)*) => { + // $crate::fieldset!(@ { $($out),*, $crate::__tracing_stringify!($($k).+) } $($rest)*) + // }; + (@ { $(,)* $($out:expr),* } ?$($k:ident).+, $($rest:tt)*) => { + $crate::fieldset!(@ { $($out),*, $crate::__tracing_stringify!($($k).+) } $($rest)*) + }; + (@ { $(,)* $($out:expr),* } %$($k:ident).+, $($rest:tt)*) => { + $crate::fieldset!(@ { $($out),*, $crate::__tracing_stringify!($($k).+) } $($rest)*) + }; + (@ { $(,)* $($out:expr),* } $($k:ident).+, $($rest:tt)*) => { + $crate::fieldset!(@ { $($out),*, $crate::__tracing_stringify!($($k).+) } $($rest)*) + }; + + // Handle literal names + (@ { $(,)* $($out:expr),* } $k:literal = ?$val:expr, $($rest:tt)*) => { + $crate::fieldset!(@ { $($out),*, $k } $($rest)*) + }; + (@ { $(,)* $($out:expr),* } $k:literal = %$val:expr, $($rest:tt)*) => { + $crate::fieldset!(@ { $($out),*, $k } $($rest)*) + }; + (@ { $(,)* $($out:expr),* } $k:literal = $val:expr, $($rest:tt)*) => { + $crate::fieldset!(@ { $($out),*, $k } $($rest)*) + }; + + // Remainder is unparseable, but exists --- must be format args! + (@ { $(,)* $($out:expr),* } $($rest:tt)+) => { + $crate::fieldset!(@ { "message", $($out),*, }) + }; + + // == entry == + ($($args:tt)*) => { + $crate::fieldset!(@ { } $($args)*,) + }; + +} + +#[cfg(feature = "log")] +#[doc(hidden)] +#[macro_export] +macro_rules! level_to_log { + ($level:expr) => { + match $level { + $crate::Level::ERROR => $crate::log::Level::Error, + $crate::Level::WARN => $crate::log::Level::Warn, + $crate::Level::INFO => $crate::log::Level::Info, + $crate::Level::DEBUG => $crate::log::Level::Debug, + _ => $crate::log::Level::Trace, + } + }; +} + +#[doc(hidden)] +#[macro_export] +macro_rules! __tracing_stringify { + ($s:expr) => { + stringify!($s) + }; +} + +#[cfg(not(feature = "log"))] +#[doc(hidden)] +#[macro_export] +macro_rules! __tracing_log { + (target: $target:expr, $level:expr, $($field:tt)+ ) => {}; +} + +#[cfg(feature = "log")] +#[doc(hidden)] +#[macro_export] +macro_rules! __mk_format_string { + // === base case === + (@ { $(,)* $($out:expr),* $(,)* } $(,)*) => { + concat!( $($out),*) + }; + + // === recursive case (more tts), === + // ====== shorthand field syntax === + (@ { $(,)* $($out:expr),* }, ?$($k:ident).+, $($rest:tt)*) => { + $crate::__mk_format_string!(@ { $($out),*, $crate::__tracing_stringify!($($k).+), "={:?} " }, $($rest)*) + }; + (@ { $(,)* $($out:expr),* }, %$($k:ident).+, $($rest:tt)*) => { + $crate::__mk_format_string!(@ { $($out),*, $crate::__tracing_stringify!($($k).+), "={} " }, $($rest)*) + }; + (@ { $(,)* $($out:expr),* }, $($k:ident).+, $($rest:tt)*) => { + $crate::__mk_format_string!(@ { $($out),*, $crate::__tracing_stringify!($($k).+), "={:?} " }, $($rest)*) + }; + // ====== kv field syntax === + (@ { $(,)* $($out:expr),* }, message = $val:expr, $($rest:tt)*) => { + $crate::__mk_format_string!(@ { $($out),*, "{} " }, $($rest)*) + }; + (@ { $(,)* $($out:expr),* }, $($k:ident).+ = ?$val:expr, $($rest:tt)*) => { + $crate::__mk_format_string!(@ { $($out),*, $crate::__tracing_stringify!($($k).+), "={:?} " }, $($rest)*) + }; + (@ { $(,)* $($out:expr),* }, $($k:ident).+ = %$val:expr, $($rest:tt)*) => { + $crate::__mk_format_string!(@ { $($out),*, $crate::__tracing_stringify!($($k).+), "={} " }, $($rest)*) + }; + (@ { $(,)* $($out:expr),* }, $($k:ident).+ = $val:expr, $($rest:tt)*) => { + $crate::__mk_format_string!(@ { $($out),*, $crate::__tracing_stringify!($($k).+), "={:?} " }, $($rest)*) + }; + + // === rest is unparseable --- must be fmt args === + (@ { $(,)* $($out:expr),* }, $($rest:tt)+) => { + $crate::__mk_format_string!(@ { "{} ", $($out),* }, ) + }; + + // === entry === + ($($kvs:tt)+) => { + $crate::__mk_format_string!(@ { }, $($kvs)+,) + }; + () => { + "" + } +} + +#[cfg(feature = "log")] +#[doc(hidden)] +#[macro_export] +macro_rules! __mk_format_args { + // === finished --- called into by base cases === + (@ { $(,)* $($out:expr),* $(,)* }, $fmt:expr, fields: $(,)*) => { + format_args!($fmt, $($out),*) + }; + + // === base case (no more tts) === + (@ { $(,)* $($out:expr),* }, $fmt:expr, fields: $($k:ident).+ = ?$val:expr $(,)*) => { + $crate::__mk_format_args!(@ { $($out),*, $val }, $fmt, fields: ) + }; + (@ { $(,)* $($out:expr),* }, $fmt:expr, fields: $($k:ident).+ = %$val:expr $(,)*) => { + $crate::__mk_format_args!(@ { $($out),*, $val }, $fmt, fields: ) + }; + (@ { $(,)* $($out:expr),* }, $fmt:expr, fields: $($k:ident).+ = $val:expr $(,)*) => { + $crate::__mk_format_args!(@ { $($out),*, $val }, $fmt, fields: ) + }; + // ====== shorthand field syntax === + (@ { $(,)* $($out:expr),* }, $fmt:expr, fields: ?$($k:ident).+ $(,)*) => { + $crate::__mk_format_args!(@ { $($out),*, &$($k).+ }, $fmt, fields:) + }; + (@ { $(,)* $($out:expr),* }, $fmt:expr, fields: %$($k:ident).+ $(,)*) => { + $crate::__mk_format_args!(@ { $($out),*, &$($k).+ }, $fmt, fields: ) + }; + (@ { $(,)* $($out:expr),* }, $fmt:expr, fields: $($k:ident).+ $(,)*) => { + $crate::__mk_format_args!(@ { $($out),*, &$($k).+ }, $fmt, fields: ) + }; + + // === recursive case (more tts) === + (@ { $(,)* $($out:expr),* }, $fmt:expr, fields: $($k:ident).+ = ?$val:expr, $($rest:tt)+) => { + $crate::__mk_format_args!(@ { $($out),*, $val }, $fmt, fields: $($rest)+) + }; + (@ { $(,)* $($out:expr),* }, $fmt:expr, fields: $($k:ident).+ = %$val:expr, $($rest:tt)+) => { + $crate::__mk_format_args!(@ { $($out),*, $val }, $fmt, fields: $($rest)+) + }; + (@ { $(,)* $($out:expr),* }, $fmt:expr, fields: $($k:ident).+ = $val:expr, $($rest:tt)+) => { + $crate::__mk_format_args!(@ { $($out),*, $val }, $fmt, fields: $($rest)+) + }; + // ====== shorthand field syntax === + (@ { $(,)* $($out:expr),* }, $fmt:expr, fields: ?$($k:ident).+, $($rest:tt)+) => { + $crate::__mk_format_args!(@ { $($out),*, &$($k).+ }, $fmt, fields: $($rest)+) + }; + (@ { $(,)* $($out:expr),* }, $fmt:expr, fields: %$($k:ident).+, $($rest:tt)+) => { + $crate::__mk_format_args!(@ { $($out),*, &$($k).+ }, $fmt, fields: $($rest)+) + }; + (@ { $(,)* $($out:expr),* }, $fmt:expr, fields: $($k:ident).+, $($rest:tt)+) => { + $crate::__mk_format_args!(@ { $($out),*, &$($k).+ }, $fmt, fields: $($rest)+) + }; + + // === rest is unparseable --- must be fmt args === + (@ { $(,)* $($out:expr),* }, $fmt:expr, fields: $($rest:tt)+) => { + $crate::__mk_format_args!(@ { format_args!($($rest)+), $($out),* }, $fmt, fields: ) + }; + + // === entry === + ($($kv:tt)*) => { + { + #[allow(unused_imports)] + use $crate::field::{debug, display}; + // use $crate::__mk_format_string; + $crate::__mk_format_args!(@ { }, $crate::__mk_format_string!($($kv)*), fields: $($kv)*) + } + }; +} + +#[cfg(feature = "log")] +#[doc(hidden)] +#[macro_export] +macro_rules! __tracing_log { + (target: $target:expr, $level:expr, $($field:tt)+ ) => { + $crate::if_log_enabled! {{ + use $crate::log; + let level = $crate::level_to_log!($level); + if level <= log::STATIC_MAX_LEVEL && level <= log::max_level() { + let log_meta = log::Metadata::builder() + .level(level) + .target($target) + .build(); + let logger = log::logger(); + if logger.enabled(&log_meta) { + logger.log(&log::Record::builder() + .file(Some(file!())) + .module_path(Some(module_path!())) + .line(Some(line!())) + .metadata(log_meta) + .args($crate::__mk_format_args!($($field)+)) + .build()); + } + } + }} + }; +} + +#[cfg(not(feature = "log"))] +#[doc(hidden)] +#[macro_export] +macro_rules! if_log_enabled { + ($e:expr;) => { + $crate::if_log_enabled! { $e } + }; + ($if_log:block) => { + $crate::if_log_enabled! { $if_log else {} } + }; + ($if_log:block else $else_block:block) => { + $else_block + }; +} + +#[cfg(all(feature = "log", not(feature = "log-always")))] +#[doc(hidden)] +#[macro_export] +macro_rules! if_log_enabled { + ($e:expr;) => { + $crate::if_log_enabled! { $e } + }; + ($if_log:block) => { + $crate::if_log_enabled! { $if_log else {} } + }; + ($if_log:block else $else_block:block) => { + if !$crate::dispatcher::has_been_set() { + $if_log + } else { + $else_block + } + }; +} + +#[cfg(all(feature = "log", feature = "log-always"))] +#[doc(hidden)] +#[macro_export] +macro_rules! if_log_enabled { + ($e:expr;) => { + $crate::if_log_enabled! { $e } + }; + ($if_log:block) => { + $crate::if_log_enabled! { $if_log else {} } + }; + ($if_log:block else $else_block:block) => { + #[allow(unused_braces)] + $if_log + }; +} diff --git a/third_party/rust/tracing/src/span.rs b/third_party/rust/tracing/src/span.rs new file mode 100644 index 0000000000..c1e0ee1a0c --- /dev/null +++ b/third_party/rust/tracing/src/span.rs @@ -0,0 +1,1283 @@ +//! Spans represent periods of time in which a program was executing in a +//! particular context. +//! +//! A span consists of [fields], user-defined key-value pairs of arbitrary data +//! that describe the context the span represents, and a set of fixed attributes +//! that describe all `tracing` spans and events. Attributes describing spans +//! include: +//! +//! - An [`Id`] assigned by the subscriber that uniquely identifies it in relation +//! to other spans. +//! - The span's [parent] in the trace tree. +//! - [Metadata] that describes static characteristics of all spans +//! originating from that callsite, such as its name, source code location, +//! [verbosity level], and the names of its fields. +//! +//! # Creating Spans +//! +//! Spans are created using the [`span!`] macro. This macro is invoked with the +//! following arguments, in order: +//! +//! - The [`target`] and/or [`parent`][parent] attributes, if the user wishes to +//! override their default values. +//! - The span's [verbosity level] +//! - A string literal providing the span's name. +//! - Finally, between zero and 32 arbitrary key/value fields. +//! +//! [`target`]: ../struct.Metadata.html#method.target +//! +//! For example: +//! ```rust +//! use tracing::{span, Level}; +//! +//! /// Construct a new span at the `INFO` level named "my_span", with a single +//! /// field named answer , with the value `42`. +//! let my_span = span!(Level::INFO, "my_span", answer = 42); +//! ``` +//! +//! The documentation for the [`span!`] macro provides additional examples of +//! the various options that exist when creating spans. +//! +//! The [`trace_span!`], [`debug_span!`], [`info_span!`], [`warn_span!`], and +//! [`error_span!`] exist as shorthand for constructing spans at various +//! verbosity levels. +//! +//! ## Recording Span Creation +//! +//! The [`Attributes`] type contains data associated with a span, and is +//! provided to the [`Subscriber`] when a new span is created. It contains +//! the span's metadata, the ID of [the span's parent][parent] if one was +//! explicitly set, and any fields whose values were recorded when the span was +//! constructed. The subscriber, which is responsible for recording `tracing` +//! data, can then store or record these values. +//! +//! # The Span Lifecycle +//! +//! ## Entering a Span +//! +//! A thread of execution is said to _enter_ a span when it begins executing, +//! and _exit_ the span when it switches to another context. Spans may be +//! entered through the [`enter`] and [`in_scope`] methods. +//! +//! The `enter` method enters a span, returning a [guard] that exits the span +//! when dropped +//! ``` +//! # #[macro_use] extern crate tracing; +//! # use tracing::Level; +//! let my_var: u64 = 5; +//! let my_span = span!(Level::TRACE, "my_span", my_var); +//! +//! // `my_span` exists but has not been entered. +//! +//! // Enter `my_span`... +//! let _enter = my_span.enter(); +//! +//! // Perform some work inside of the context of `my_span`... +//! // Dropping the `_enter` guard will exit the span. +//!``` +//! +//! <div class="information"> +//! <div class="tooltip compile_fail" style="">⚠ ️<span class="tooltiptext">Warning</span></div> +//! </div><div class="example-wrap" style="display:inline-block"><pre class="compile_fail" style="white-space:normal;font:inherit;"> +//! <strong>Warning</strong>: In asynchronous code that uses async/await syntax, +//! <code>Span::enter</code> may produce incorrect traces if the returned drop +//! guard is held across an await point. See +//! <a href="struct.Span.html#in-asynchronous-code">the method documentation</a> +//! for details. +//! </pre></div> +//! +//! `in_scope` takes a closure or function pointer and executes it inside the +//! span. +//! ``` +//! # #[macro_use] extern crate tracing; +//! # use tracing::Level; +//! let my_var: u64 = 5; +//! let my_span = span!(Level::TRACE, "my_span", my_var = &my_var); +//! +//! my_span.in_scope(|| { +//! // perform some work in the context of `my_span`... +//! }); +//! +//! // Perform some work outside of the context of `my_span`... +//! +//! my_span.in_scope(|| { +//! // Perform some more work in the context of `my_span`. +//! }); +//! ``` +//! +//! <div class="information"> +//! <div class="tooltip ignore" style="">ⓘ<span class="tooltiptext">Note</span></div> +//! </div> +//! <div class="example-wrap" style="display:inline-block"> +//! <pre class="ignore" style="white-space:normal;font:inherit;"> +//! <strong>Note</strong>: Since entering a span takes <code>&self</code<, and +//! <code>Span</code>s are <code>Clone</code>, <code>Send</code>, and +//! <code>Sync</code>, it is entirely valid for multiple threads to enter the +//! same span concurrently. +//! </pre></div> +//! +//! ## Span Relationships +//! +//! Spans form a tree structure — unless it is a root span, all spans have a +//! _parent_, and may have one or more _children_. When a new span is created, +//! the current span becomes the new span's parent. The total execution time of +//! a span consists of the time spent in that span and in the entire subtree +//! represented by its children. Thus, a parent span always lasts for at least +//! as long as the longest-executing span in its subtree. +//! +//! ``` +//! # #[macro_use] extern crate tracing; +//! # use tracing::Level; +//! // this span is considered the "root" of a new trace tree: +//! span!(Level::INFO, "root").in_scope(|| { +//! // since we are now inside "root", this span is considered a child +//! // of "root": +//! span!(Level::DEBUG, "outer_child").in_scope(|| { +//! // this span is a child of "outer_child", which is in turn a +//! // child of "root": +//! span!(Level::TRACE, "inner_child").in_scope(|| { +//! // and so on... +//! }); +//! }); +//! // another span created here would also be a child of "root". +//! }); +//!``` +//! +//! In addition, the parent of a span may be explicitly specified in +//! the `span!` macro. For example: +//! +//! ```rust +//! # #[macro_use] extern crate tracing; +//! # use tracing::Level; +//! // Create, but do not enter, a span called "foo". +//! let foo = span!(Level::INFO, "foo"); +//! +//! // Create and enter a span called "bar". +//! let bar = span!(Level::INFO, "bar"); +//! let _enter = bar.enter(); +//! +//! // Although we have currently entered "bar", "baz"'s parent span +//! // will be "foo". +//! let baz = span!(parent: &foo, Level::INFO, "baz"); +//! ``` +//! +//! A child span should typically be considered _part_ of its parent. For +//! example, if a subscriber is recording the length of time spent in various +//! spans, it should generally include the time spent in a span's children as +//! part of that span's duration. +//! +//! In addition to having zero or one parent, a span may also _follow from_ any +//! number of other spans. This indicates a causal relationship between the span +//! and the spans that it follows from, but a follower is *not* typically +//! considered part of the duration of the span it follows. Unlike the parent, a +//! span may record that it follows from another span after it is created, using +//! the [`follows_from`] method. +//! +//! As an example, consider a listener task in a server. As the listener accepts +//! incoming connections, it spawns new tasks that handle those connections. We +//! might want to have a span representing the listener, and instrument each +//! spawned handler task with its own span. We would want our instrumentation to +//! record that the handler tasks were spawned as a result of the listener task. +//! However, we might not consider the handler tasks to be _part_ of the time +//! spent in the listener task, so we would not consider those spans children of +//! the listener span. Instead, we would record that the handler tasks follow +//! from the listener, recording the causal relationship but treating the spans +//! as separate durations. +//! +//! ## Closing Spans +//! +//! Execution may enter and exit a span multiple times before that span is +//! _closed_. Consider, for example, a future which has an associated +//! span and enters that span every time it is polled: +//! ```rust +//! # extern crate tracing; +//! # extern crate futures; +//! # use futures::{Future, Poll, Async}; +//! struct MyFuture { +//! // data +//! span: tracing::Span, +//! } +//! +//! impl Future for MyFuture { +//! type Item = (); +//! type Error = (); +//! +//! fn poll(&mut self) -> Poll<Self::Item, Self::Error> { +//! let _enter = self.span.enter(); +//! // Do actual future work... +//! # Ok(Async::Ready(())) +//! } +//! } +//! ``` +//! +//! If this future was spawned on an executor, it might yield one or more times +//! before `poll` returns `Ok(Async::Ready)`. If the future were to yield, then +//! the executor would move on to poll the next future, which may _also_ enter +//! an associated span or series of spans. Therefore, it is valid for a span to +//! be entered repeatedly before it completes. Only the time when that span or +//! one of its children was the current span is considered to be time spent in +//! that span. A span which is not executing and has not yet been closed is said +//! to be _idle_. +//! +//! Because spans may be entered and exited multiple times before they close, +//! [`Subscriber`]s have separate trait methods which are called to notify them +//! of span exits and when span handles are dropped. When execution exits a +//! span, [`exit`] will always be called with that span's ID to notify the +//! subscriber that the span has been exited. When span handles are dropped, the +//! [`drop_span`] method is called with that span's ID. The subscriber may use +//! this to determine whether or not the span will be entered again. +//! +//! If there is only a single handle with the capacity to exit a span, dropping +//! that handle "closes" the span, since the capacity to enter it no longer +//! exists. For example: +//! ``` +//! # #[macro_use] extern crate tracing; +//! # use tracing::Level; +//! { +//! span!(Level::TRACE, "my_span").in_scope(|| { +//! // perform some work in the context of `my_span`... +//! }); // --> Subscriber::exit(my_span) +//! +//! // The handle to `my_span` only lives inside of this block; when it is +//! // dropped, the subscriber will be informed via `drop_span`. +//! +//! } // --> Subscriber::drop_span(my_span) +//! ``` +//! +//! However, if multiple handles exist, the span can still be re-entered even if +//! one or more is dropped. For determining when _all_ handles to a span have +//! been dropped, `Subscriber`s have a [`clone_span`] method, which is called +//! every time a span handle is cloned. Combined with `drop_span`, this may be +//! used to track the number of handles to a given span — if `drop_span` has +//! been called one more time than the number of calls to `clone_span` for a +//! given ID, then no more handles to the span with that ID exist. The +//! subscriber may then treat it as closed. +//! +//! # When to use spans +//! +//! As a rule of thumb, spans should be used to represent discrete units of work +//! (e.g., a given request's lifetime in a server) or periods of time spent in a +//! given context (e.g., time spent interacting with an instance of an external +//! system, such as a database). +//! +//! Which scopes in a program correspond to new spans depend somewhat on user +//! intent. For example, consider the case of a loop in a program. Should we +//! construct one span and perform the entire loop inside of that span, like: +//! +//! ```rust +//! # #[macro_use] extern crate tracing; +//! # use tracing::Level; +//! # let n = 1; +//! let span = span!(Level::TRACE, "my_loop"); +//! let _enter = span.enter(); +//! for i in 0..n { +//! # let _ = i; +//! // ... +//! } +//! ``` +//! Or, should we create a new span for each iteration of the loop, as in: +//! ```rust +//! # #[macro_use] extern crate tracing; +//! # use tracing::Level; +//! # let n = 1u64; +//! for i in 0..n { +//! let span = span!(Level::TRACE, "my_loop", iteration = i); +//! let _enter = span.enter(); +//! // ... +//! } +//! ``` +//! +//! Depending on the circumstances, we might want to do either, or both. For +//! example, if we want to know how long was spent in the loop overall, we would +//! create a single span around the entire loop; whereas if we wanted to know how +//! much time was spent in each individual iteration, we would enter a new span +//! on every iteration. +//! +//! [fields]: ../field/index.html +//! [Metadata]: ../struct.Metadata.html +//! [`Id`]: struct.Id.html +//! [verbosity level]: ../struct.Level.html +//! [`span!`]: ../macro.span.html +//! [`trace_span!`]: ../macro.trace_span.html +//! [`debug_span!`]: ../macro.debug_span.html +//! [`info_span!`]: ../macro.info_span.html +//! [`warn_span!`]: ../macro.warn_span.html +//! [`error_span!`]: ../macro.error_span.html +//! [`clone_span`]: ../subscriber/trait.Subscriber.html#method.clone_span +//! [`drop_span`]: ../subscriber/trait.Subscriber.html#method.drop_span +//! [`exit`]: ../subscriber/trait.Subscriber.html#tymethod.exit +//! [`Subscriber`]: ../subscriber/trait.Subscriber.html +//! [`Attributes`]: struct.Attributes.html +//! [`enter`]: struct.Span.html#method.enter +//! [`in_scope`]: struct.Span.html#method.in_scope +//! [`follows_from`]: struct.Span.html#method.follows_from +//! [guard]: struct.Entered.html +//! [parent]: #span-relationships +pub use tracing_core::span::{Attributes, Id, Record}; + +use crate::stdlib::{ + cmp, fmt, + hash::{Hash, Hasher}, +}; +use crate::{ + dispatcher::{self, Dispatch}, + field, Metadata, +}; + +/// Trait implemented by types which have a span `Id`. +pub trait AsId: crate::sealed::Sealed { + /// Returns the `Id` of the span that `self` corresponds to, or `None` if + /// this corresponds to a disabled span. + fn as_id(&self) -> Option<&Id>; +} + +/// A handle representing a span, with the capability to enter the span if it +/// exists. +/// +/// If the span was rejected by the current `Subscriber`'s filter, entering the +/// span will silently do nothing. Thus, the handle can be used in the same +/// manner regardless of whether or not the trace is currently being collected. +#[derive(Clone)] +pub struct Span { + /// A handle used to enter the span when it is not executing. + /// + /// If this is `None`, then the span has either closed or was never enabled. + inner: Option<Inner>, + /// Metadata describing the span. + /// + /// This might be `Some` even if `inner` is `None`, in the case that the + /// span is disabled but the metadata is needed for `log` support. + meta: Option<&'static Metadata<'static>>, +} + +/// A handle representing the capacity to enter a span which is known to exist. +/// +/// Unlike `Span`, this type is only constructed for spans which _have_ been +/// enabled by the current filter. This type is primarily used for implementing +/// span handles; users should typically not need to interact with it directly. +#[derive(Debug)] +pub(crate) struct Inner { + /// The span's ID, as provided by `subscriber`. + id: Id, + + /// The subscriber that will receive events relating to this span. + /// + /// This should be the same subscriber that provided this span with its + /// `id`. + subscriber: Dispatch, +} + +/// A guard representing a span which has been entered and is currently +/// executing. +/// +/// When the guard is dropped, the span will be exited. +/// +/// This is returned by the [`Span::enter`] function. +/// +/// [`Span::enter`]: ../struct.Span.html#method.enter +#[derive(Debug)] +#[must_use = "once a span has been entered, it should be exited"] +pub struct Entered<'a> { + span: &'a Span, +} + +/// `log` target for all span lifecycle (creation/enter/exit/close) records. +#[cfg(feature = "log")] +const LIFECYCLE_LOG_TARGET: &str = "tracing::span"; +/// `log` target for span activity (enter/exit) records. +#[cfg(feature = "log")] +const ACTIVITY_LOG_TARGET: &str = "tracing::span::active"; + +// ===== impl Span ===== + +impl Span { + /// Constructs a new `Span` with the given [metadata] and set of + /// [field values]. + /// + /// The new span will be constructed by the currently-active [`Subscriber`], + /// with the current span as its parent (if one exists). + /// + /// After the span is constructed, [field values] and/or [`follows_from`] + /// annotations may be added to it. + /// + /// [metadata]: ../metadata + /// [`Subscriber`]: ../subscriber/trait.Subscriber.html + /// [field values]: ../field/struct.ValueSet.html + /// [`follows_from`]: ../struct.Span.html#method.follows_from + pub fn new(meta: &'static Metadata<'static>, values: &field::ValueSet<'_>) -> Span { + dispatcher::get_default(|dispatch| Self::new_with(meta, values, dispatch)) + } + + #[inline] + #[doc(hidden)] + pub fn new_with( + meta: &'static Metadata<'static>, + values: &field::ValueSet<'_>, + dispatch: &Dispatch, + ) -> Span { + let new_span = Attributes::new(meta, values); + Self::make_with(meta, new_span, dispatch) + } + + /// Constructs a new `Span` as the root of its own trace tree, with the + /// given [metadata] and set of [field values]. + /// + /// After the span is constructed, [field values] and/or [`follows_from`] + /// annotations may be added to it. + /// + /// [metadata]: ../metadata + /// [field values]: ../field/struct.ValueSet.html + /// [`follows_from`]: ../struct.Span.html#method.follows_from + pub fn new_root(meta: &'static Metadata<'static>, values: &field::ValueSet<'_>) -> Span { + dispatcher::get_default(|dispatch| Self::new_root_with(meta, values, dispatch)) + } + + #[inline] + #[doc(hidden)] + pub fn new_root_with( + meta: &'static Metadata<'static>, + values: &field::ValueSet<'_>, + dispatch: &Dispatch, + ) -> Span { + let new_span = Attributes::new_root(meta, values); + Self::make_with(meta, new_span, dispatch) + } + + /// Constructs a new `Span` as child of the given parent span, with the + /// given [metadata] and set of [field values]. + /// + /// After the span is constructed, [field values] and/or [`follows_from`] + /// annotations may be added to it. + /// + /// [metadata]: ../metadata + /// [field values]: ../field/struct.ValueSet.html + /// [`follows_from`]: ../struct.Span.html#method.follows_from + pub fn child_of( + parent: impl Into<Option<Id>>, + meta: &'static Metadata<'static>, + values: &field::ValueSet<'_>, + ) -> Span { + let mut parent = parent.into(); + dispatcher::get_default(move |dispatch| { + Self::child_of_with(Option::take(&mut parent), meta, values, dispatch) + }) + } + + #[inline] + #[doc(hidden)] + pub fn child_of_with( + parent: impl Into<Option<Id>>, + meta: &'static Metadata<'static>, + values: &field::ValueSet<'_>, + dispatch: &Dispatch, + ) -> Span { + let new_span = match parent.into() { + Some(parent) => Attributes::child_of(parent, meta, values), + None => Attributes::new_root(meta, values), + }; + Self::make_with(meta, new_span, dispatch) + } + + /// Constructs a new disabled span with the given `Metadata`. + /// + /// This should be used when a span is constructed from a known callsite, + /// but the subscriber indicates that it is disabled. + /// + /// Entering, exiting, and recording values on this span will not notify the + /// `Subscriber` but _may_ record log messages if the `log` feature flag is + /// enabled. + #[inline(always)] + pub fn new_disabled(meta: &'static Metadata<'static>) -> Span { + Self { + inner: None, + meta: Some(meta), + } + } + + /// Constructs a new span that is *completely disabled*. + /// + /// This can be used rather than `Option<Span>` to represent cases where a + /// span is not present. + /// + /// Entering, exiting, and recording values on this span will do nothing. + #[inline(always)] + pub const fn none() -> Span { + Self { + inner: None, + meta: None, + } + } + + /// Returns a handle to the span [considered by the `Subscriber`] to be the + /// current span. + /// + /// If the subscriber indicates that it does not track the current span, or + /// that the thread from which this function is called is not currently + /// inside a span, the returned span will be disabled. + /// + /// [considered by the `Subscriber`]: ../subscriber/trait.Subscriber.html#method.current + pub fn current() -> Span { + dispatcher::get_default(|dispatch| { + if let Some((id, meta)) = dispatch.current_span().into_inner() { + let id = dispatch.clone_span(&id); + Self { + inner: Some(Inner::new(id, dispatch)), + meta: Some(meta), + } + } else { + Self::none() + } + }) + } + + fn make_with( + meta: &'static Metadata<'static>, + new_span: Attributes<'_>, + dispatch: &Dispatch, + ) -> Span { + let attrs = &new_span; + let id = dispatch.new_span(attrs); + let inner = Some(Inner::new(id, dispatch)); + + let span = Self { + inner, + meta: Some(meta), + }; + + if_log_enabled! {{ + let target = if attrs.is_empty() { + LIFECYCLE_LOG_TARGET + } else { + meta.target() + }; + span.log(target, level_to_log!(*meta.level()), format_args!("++ {}{}", meta.name(), FmtAttrs(attrs))); + }} + + span + } + /// Enters this span, returning a guard that will exit the span when dropped. + /// + /// If this span is enabled by the current subscriber, then this function will + /// call [`Subscriber::enter`] with the span's [`Id`], and dropping the guard + /// will call [`Subscriber::exit`]. If the span is disabled, this does + /// nothing. + /// + /// # In Asynchronous Code + /// + /// **Warning**: in asynchronous code that uses [async/await syntax][syntax], + /// `Span::enter` should be used very carefully or avoided entirely. Holding + /// the drop guard returned by `Span::enter` across `.await` points will + /// result in incorrect traces. + /// + /// For example, + /// + /// ``` + /// # use tracing::info_span; + /// # async fn some_other_async_function() {} + /// async fn my_async_function() { + /// let span = info_span!("my_async_function"); + /// + /// // THIS WILL RESULT IN INCORRECT TRACES + /// let _enter = span.enter(); + /// some_other_async_function().await; + /// + /// // ... + /// } + /// ``` + /// + /// The drop guard returned by `Span::enter` exits the span when it is + /// dropped. When an async function or async block yields at an `.await` + /// point, the current scope is _exited_, but values in that scope are + /// **not** dropped (because the async block will eventually resume + /// execution from that await point). This means that _another_ task will + /// begin executing while _remaining_ in the entered span. This results in + /// an incorrect trace. + /// + /// Instead of using `Span::enter` in asynchronous code, prefer the + /// following: + /// + /// * To enter a span for a synchronous section of code within an async + /// block or function, prefer [`Span::in_scope`]. Since `in_scope` takes a + /// synchronous closure and exits the span when the closure returns, the + /// span will always be exited before the next await point. For example: + /// ``` + /// # use tracing::info_span; + /// # async fn some_other_async_function(_: ()) {} + /// async fn my_async_function() { + /// let span = info_span!("my_async_function"); + /// + /// let some_value = span.in_scope(|| { + /// // run some synchronous code inside the span... + /// }); + /// + /// // This is okay! The span has already been exited before we reach + /// // the await point. + /// some_other_async_function(some_value).await; + /// + /// // ... + /// } + /// ``` + /// * For instrumenting asynchronous code, `tracing` provides the + /// [`Future::instrument` combinator][instrument] for + /// attaching a span to a future (async function or block). This will + /// enter the span _every_ time the future is polled, and exit it whenever + /// the future yields. + /// + /// `Instrument` can be used with an async block inside an async function: + /// ```ignore + /// # use tracing::info_span; + /// use tracing::Instrument; + /// + /// # async fn some_other_async_function() {} + /// async fn my_async_function() { + /// let span = info_span!("my_async_function"); + /// async move { + /// // This is correct! If we yield here, the span will be exited, + /// // and re-entered when we resume. + /// some_other_async_function().await; + /// + /// //more asynchronous code inside the span... + /// + /// } + /// // instrument the async block with the span... + /// .instrument(span) + /// // ...and await it. + /// .await + /// } + /// ``` + /// + /// It can also be used to instrument calls to async functions at the + /// callsite: + /// ```ignore + /// # use tracing::debug_span; + /// use tracing::Instrument; + /// + /// # async fn some_other_async_function() {} + /// async fn my_async_function() { + /// let some_value = some_other_async_function() + /// .instrument(debug_span!("some_other_async_function")) + /// .await; + /// + /// // ... + /// } + /// ``` + /// + /// * The [`#[instrument]` attribute macro][attr] can automatically generate + /// correct code when used on an async function: + /// + /// ```ignore + /// # async fn some_other_async_function() {} + /// #[tracing::instrument(level = "info")] + /// async fn my_async_function() { + /// + /// // This is correct! If we yield here, the span will be exited, + /// // and re-entered when we resume. + /// some_other_async_function().await; + /// + /// // ... + /// + /// } + /// ``` + /// + /// [syntax]: https://rust-lang.github.io/async-book/01_getting_started/04_async_await_primer.html + /// [`Span::in_scope`]: #method.in_scope + /// [instrument]: https://docs.rs/tracing/latest/tracing/trait.Instrument.html + /// [attr]: ../../attr.instrument.html + /// + /// # Examples + /// + /// ``` + /// #[macro_use] extern crate tracing; + /// # use tracing::Level; + /// let span = span!(Level::INFO, "my_span"); + /// let guard = span.enter(); + /// + /// // code here is within the span + /// + /// drop(guard); + /// + /// // code here is no longer within the span + /// + /// ``` + /// + /// Guards need not be explicitly dropped: + /// + /// ``` + /// #[macro_use] extern crate tracing; + /// fn my_function() -> String { + /// // enter a span for the duration of this function. + /// let span = trace_span!("my_function"); + /// let _enter = span.enter(); + /// + /// // anything happening in functions we call is still inside the span... + /// my_other_function(); + /// + /// // returning from the function drops the guard, exiting the span. + /// return "Hello world".to_owned(); + /// } + /// + /// fn my_other_function() { + /// // ... + /// } + /// ``` + /// + /// Sub-scopes may be created to limit the duration for which the span is + /// entered: + /// + /// ``` + /// #[macro_use] extern crate tracing; + /// let span = info_span!("my_great_span"); + /// + /// { + /// let _enter = span.enter(); + /// + /// // this event occurs inside the span. + /// info!("i'm in the span!"); + /// + /// // exiting the scope drops the guard, exiting the span. + /// } + /// + /// // this event is not inside the span. + /// info!("i'm outside the span!") + /// ``` + /// + /// [`Subscriber::enter`]: ../subscriber/trait.Subscriber.html#method.enter + /// [`Subscriber::exit`]: ../subscriber/trait.Subscriber.html#method.exit + /// [`Id`]: ../struct.Id.html + pub fn enter(&self) -> Entered<'_> { + if let Some(ref inner) = self.inner.as_ref() { + inner.subscriber.enter(&inner.id); + } + + if_log_enabled! {{ + if let Some(ref meta) = self.meta { + self.log(ACTIVITY_LOG_TARGET, log::Level::Trace, format_args!("-> {}", meta.name())); + } + }} + + Entered { span: self } + } + + /// Executes the given function in the context of this span. + /// + /// If this span is enabled, then this function enters the span, invokes `f` + /// and then exits the span. If the span is disabled, `f` will still be + /// invoked, but in the context of the currently-executing span (if there is + /// one). + /// + /// Returns the result of evaluating `f`. + /// + /// # Examples + /// + /// ``` + /// # #[macro_use] extern crate tracing; + /// # use tracing::Level; + /// let my_span = span!(Level::TRACE, "my_span"); + /// + /// my_span.in_scope(|| { + /// // this event occurs within the span. + /// trace!("i'm in the span!"); + /// }); + /// + /// // this event occurs outside the span. + /// trace!("i'm not in the span!"); + /// ``` + /// + /// Calling a function and returning the result: + /// ``` + /// # use tracing::{info_span, Level}; + /// fn hello_world() -> String { + /// "Hello world!".to_owned() + /// } + /// + /// let span = info_span!("hello_world"); + /// // the span will be entered for the duration of the call to + /// // `hello_world`. + /// let a_string = span.in_scope(hello_world); + /// + pub fn in_scope<F: FnOnce() -> T, T>(&self, f: F) -> T { + let _enter = self.enter(); + f() + } + + /// Returns a [`Field`](../field/struct.Field.html) for the field with the + /// given `name`, if one exists, + pub fn field<Q: ?Sized>(&self, field: &Q) -> Option<field::Field> + where + Q: field::AsField, + { + self.metadata().and_then(|meta| field.as_field(meta)) + } + + /// Returns true if this `Span` has a field for the given + /// [`Field`](../field/struct.Field.html) or field name. + #[inline] + pub fn has_field<Q: ?Sized>(&self, field: &Q) -> bool + where + Q: field::AsField, + { + self.field(field).is_some() + } + + /// Records that the field described by `field` has the value `value`. + /// + /// This may be used with [`field::Empty`] to declare fields whose values + /// are not known when the span is created, and record them later: + /// ``` + /// use tracing::{trace_span, field}; + /// + /// // Create a span with two fields: `greeting`, with the value "hello world", and + /// // `parting`, without a value. + /// let span = trace_span!("my_span", greeting = "hello world", parting = field::Empty); + /// + /// // ... + /// + /// // Now, record a value for parting as well. + /// // (note that the field name is passed as a string slice) + /// span.record("parting", &"goodbye world!"); + /// ``` + /// However, it may also be used to record a _new_ value for a field whose + /// value was already recorded: + /// ``` + /// use tracing::info_span; + /// # fn do_something() -> Result<(), ()> { Err(()) } + /// + /// // Initially, let's assume that our attempt to do something is going okay... + /// let span = info_span!("doing_something", is_okay = true); + /// let _e = span.enter(); + /// + /// match do_something() { + /// Ok(something) => { + /// // ... + /// } + /// Err(_) => { + /// // Things are no longer okay! + /// span.record("is_okay", &false); + /// } + /// } + /// ``` + /// + /// <div class="information"> + /// <div class="tooltip ignore" style="">ⓘ<span class="tooltiptext">Note</span></div> + /// </div> + /// <div class="example-wrap" style="display:inline-block"> + /// <pre class="ignore" style="white-space:normal;font:inherit;"> + /// <strong>Note</strong>: The fields associated with a span are part of its + /// <a href="../struct.Metadata.html"><code>Metadata</code></a>. + /// The <a href="../struct.Metadata.html"><code>Metadata</code></a>. describing a particular + /// span is constructed statically when the span is created and cannot be extended later to + /// add new fields. Therefore, you cannot record a value for a field that was not specified + /// when the span was created:</pre></div> + /// + /// ``` + /// use tracing::{trace_span, field}; + /// + /// // Create a span with two fields: `greeting`, with the value "hello world", and + /// // `parting`, without a value. + /// let span = trace_span!("my_span", greeting = "hello world", parting = field::Empty); + /// + /// // ... + /// + /// // Now, you try to record a value for a new field, `new_field`, which was not + /// // declared as `Empty` or populated when you created `span`. + /// // You won't get any error, but the assignment will have no effect! + /// span.record("new_field", &"interesting_value_you_really_need"); + /// + /// // Instead, all fields that may be recorded after span creation should be declared up front, + /// // using field::Empty when a value is not known, as we did for `parting`. + /// // This `record` call will indeed replace field::Empty with "you will be remembered". + /// span.record("parting", &"you will be remembered"); + /// ``` + /// + /// [`field::Empty`]: ../field/struct.Empty.html + /// [`Metadata`]: ../struct.Metadata.html + pub fn record<Q: ?Sized, V>(&self, field: &Q, value: &V) -> &Self + where + Q: field::AsField, + V: field::Value, + { + if let Some(ref meta) = self.meta { + if let Some(field) = field.as_field(meta) { + self.record_all( + &meta + .fields() + .value_set(&[(&field, Some(value as &dyn field::Value))]), + ); + } + } + + self + } + + /// Records all the fields in the provided `ValueSet`. + pub fn record_all(&self, values: &field::ValueSet<'_>) -> &Self { + let record = Record::new(values); + if let Some(ref inner) = self.inner { + inner.record(&record); + } + + if_log_enabled! {{ + if let Some(ref meta) = self.meta { + let target = if record.is_empty() { + LIFECYCLE_LOG_TARGET + } else { + meta.target() + }; + self.log(target, level_to_log!(*meta.level()), format_args!("{}{}", meta.name(), FmtValues(&record))); + } + }} + + self + } + + /// Returns `true` if this span was disabled by the subscriber and does not + /// exist. + /// + /// See also [`is_none`]. + /// + /// [`is_none`]: #method.is_none + #[inline] + pub fn is_disabled(&self) -> bool { + self.inner.is_none() + } + + /// Returns `true` if this span was constructed by [`Span::none`] and is + /// empty. + /// + /// If `is_none` returns `true` for a given span, then [`is_disabled`] will + /// also return `true`. However, when a span is disabled by the subscriber + /// rather than constructed by `Span::none`, this method will return + /// `false`, while `is_disabled` will return `true`. + /// + /// [`Span::none`]: #method.none + /// [`is_disabled`]: #method.is_disabled + #[inline] + pub fn is_none(&self) -> bool { + self.is_disabled() && self.meta.is_none() + } + + /// Indicates that the span with the given ID has an indirect causal + /// relationship with this span. + /// + /// This relationship differs somewhat from the parent-child relationship: a + /// span may have any number of prior spans, rather than a single one; and + /// spans are not considered to be executing _inside_ of the spans they + /// follow from. This means that a span may close even if subsequent spans + /// that follow from it are still open, and time spent inside of a + /// subsequent span should not be included in the time its precedents were + /// executing. This is used to model causal relationships such as when a + /// single future spawns several related background tasks, et cetera. + /// + /// If this span is disabled, or the resulting follows-from relationship + /// would be invalid, this function will do nothing. + /// + /// # Examples + /// + /// Setting a `follows_from` relationship with a `Span`: + /// ``` + /// # use tracing::{span, Id, Level, Span}; + /// let span1 = span!(Level::INFO, "span_1"); + /// let span2 = span!(Level::DEBUG, "span_2"); + /// span2.follows_from(span1); + /// ``` + /// + /// Setting a `follows_from` relationship with the current span: + /// ``` + /// # use tracing::{span, Id, Level, Span}; + /// let span = span!(Level::INFO, "hello!"); + /// span.follows_from(Span::current()); + /// ``` + /// + /// Setting a `follows_from` relationship with a `Span` reference: + /// ``` + /// # use tracing::{span, Id, Level, Span}; + /// let span = span!(Level::INFO, "hello!"); + /// let curr = Span::current(); + /// span.follows_from(&curr); + /// ``` + /// + /// Setting a `follows_from` relationship with an `Id`: + /// ``` + /// # use tracing::{span, Id, Level, Span}; + /// let span = span!(Level::INFO, "hello!"); + /// let id = span.id(); + /// span.follows_from(id); + /// ``` + pub fn follows_from(&self, from: impl Into<Option<Id>>) -> &Self { + if let Some(ref inner) = self.inner { + if let Some(from) = from.into() { + inner.follows_from(&from); + } + } + self + } + + /// Returns this span's `Id`, if it is enabled. + pub fn id(&self) -> Option<Id> { + self.inner.as_ref().map(Inner::id) + } + + /// Returns this span's `Metadata`, if it is enabled. + pub fn metadata(&self) -> Option<&'static Metadata<'static>> { + self.meta + } + + #[cfg(feature = "log")] + #[inline] + fn log(&self, target: &str, level: log::Level, message: fmt::Arguments<'_>) { + if let Some(ref meta) = self.meta { + if level_to_log!(*meta.level()) <= log::max_level() { + let logger = log::logger(); + let log_meta = log::Metadata::builder().level(level).target(target).build(); + if logger.enabled(&log_meta) { + if let Some(ref inner) = self.inner { + logger.log( + &log::Record::builder() + .metadata(log_meta) + .module_path(meta.module_path()) + .file(meta.file()) + .line(meta.line()) + .args(format_args!("{}; span={}", message, inner.id.into_u64())) + .build(), + ); + } else { + logger.log( + &log::Record::builder() + .metadata(log_meta) + .module_path(meta.module_path()) + .file(meta.file()) + .line(meta.line()) + .args(message) + .build(), + ); + } + } + } + } + } + + /// Invokes a function with a reference to this span's ID and subscriber. + /// + /// if this span is enabled, the provided function is called, and the result is returned. + /// If the span is disabled, the function is not called, and this method returns `None` + /// instead. + pub fn with_subscriber<T>(&self, f: impl FnOnce((&Id, &Dispatch)) -> T) -> Option<T> { + self.inner + .as_ref() + .map(|inner| f((&inner.id, &inner.subscriber))) + } +} + +impl cmp::PartialEq for Span { + fn eq(&self, other: &Self) -> bool { + match (&self.meta, &other.meta) { + (Some(this), Some(that)) => { + this.callsite() == that.callsite() && self.inner == other.inner + } + _ => false, + } + } +} + +impl Hash for Span { + fn hash<H: Hasher>(&self, hasher: &mut H) { + self.inner.hash(hasher); + } +} + +impl fmt::Debug for Span { + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + let mut span = f.debug_struct("Span"); + if let Some(ref meta) = self.meta { + span.field("name", &meta.name()) + .field("level", &meta.level()) + .field("target", &meta.target()); + + if let Some(ref inner) = self.inner { + span.field("id", &inner.id()); + } else { + span.field("disabled", &true); + } + + if let Some(ref path) = meta.module_path() { + span.field("module_path", &path); + } + + if let Some(ref line) = meta.line() { + span.field("line", &line); + } + + if let Some(ref file) = meta.file() { + span.field("file", &file); + } + } else { + span.field("none", &true); + } + + span.finish() + } +} + +impl<'a> Into<Option<&'a Id>> for &'a Span { + fn into(self) -> Option<&'a Id> { + self.inner.as_ref().map(|inner| &inner.id) + } +} + +impl<'a> Into<Option<Id>> for &'a Span { + fn into(self) -> Option<Id> { + self.inner.as_ref().map(Inner::id) + } +} + +impl Into<Option<Id>> for Span { + fn into(self) -> Option<Id> { + self.inner.as_ref().map(Inner::id) + } +} + +impl Drop for Span { + fn drop(&mut self) { + if let Some(Inner { + ref id, + ref subscriber, + }) = self.inner + { + subscriber.try_close(id.clone()); + } + + if_log_enabled!({ + if let Some(ref meta) = self.meta { + self.log( + LIFECYCLE_LOG_TARGET, + log::Level::Trace, + format_args!("-- {}", meta.name()), + ); + } + }) + } +} + +// ===== impl Inner ===== + +impl Inner { + /// Indicates that the span with the given ID has an indirect causal + /// relationship with this span. + /// + /// This relationship differs somewhat from the parent-child relationship: a + /// span may have any number of prior spans, rather than a single one; and + /// spans are not considered to be executing _inside_ of the spans they + /// follow from. This means that a span may close even if subsequent spans + /// that follow from it are still open, and time spent inside of a + /// subsequent span should not be included in the time its precedents were + /// executing. This is used to model causal relationships such as when a + /// single future spawns several related background tasks, et cetera. + /// + /// If this span is disabled, this function will do nothing. Otherwise, it + /// returns `Ok(())` if the other span was added as a precedent of this + /// span, or an error if this was not possible. + fn follows_from(&self, from: &Id) { + self.subscriber.record_follows_from(&self.id, &from) + } + + /// Returns the span's ID. + fn id(&self) -> Id { + self.id.clone() + } + + fn record(&self, values: &Record<'_>) { + self.subscriber.record(&self.id, values) + } + + fn new(id: Id, subscriber: &Dispatch) -> Self { + Inner { + id, + subscriber: subscriber.clone(), + } + } +} + +impl cmp::PartialEq for Inner { + fn eq(&self, other: &Self) -> bool { + self.id == other.id + } +} + +impl Hash for Inner { + fn hash<H: Hasher>(&self, state: &mut H) { + self.id.hash(state); + } +} + +impl Clone for Inner { + fn clone(&self) -> Self { + Inner { + id: self.subscriber.clone_span(&self.id), + subscriber: self.subscriber.clone(), + } + } +} + +// ===== impl Entered ===== + +impl<'a> Drop for Entered<'a> { + #[inline] + fn drop(&mut self) { + // Dropping the guard exits the span. + // + // Running this behaviour on drop rather than with an explicit function + // call means that spans may still be exited when unwinding. + if let Some(inner) = self.span.inner.as_ref() { + inner.subscriber.exit(&inner.id); + } + + if_log_enabled! {{ + if let Some(ref meta) = self.span.meta { + self.span.log(ACTIVITY_LOG_TARGET, log::Level::Trace, format_args!("<- {}", meta.name())); + } + }} + } +} + +#[cfg(feature = "log")] +struct FmtValues<'a>(&'a Record<'a>); + +#[cfg(feature = "log")] +impl<'a> fmt::Display for FmtValues<'a> { + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + let mut res = Ok(()); + let mut is_first = true; + self.0.record(&mut |k: &field::Field, v: &dyn fmt::Debug| { + res = write!(f, "{} {}={:?}", if is_first { ";" } else { "" }, k, v); + is_first = false; + }); + res + } +} + +#[cfg(feature = "log")] +struct FmtAttrs<'a>(&'a Attributes<'a>); + +#[cfg(feature = "log")] +impl<'a> fmt::Display for FmtAttrs<'a> { + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + let mut res = Ok(()); + let mut is_first = true; + self.0.record(&mut |k: &field::Field, v: &dyn fmt::Debug| { + res = write!(f, "{} {}={:?}", if is_first { ";" } else { "" }, k, v); + is_first = false; + }); + res + } +} + +#[cfg(test)] +mod test { + use super::*; + + trait AssertSend: Send {} + impl AssertSend for Span {} + + trait AssertSync: Sync {} + impl AssertSync for Span {} +} diff --git a/third_party/rust/tracing/src/stdlib.rs b/third_party/rust/tracing/src/stdlib.rs new file mode 100644 index 0000000000..12b54084d4 --- /dev/null +++ b/third_party/rust/tracing/src/stdlib.rs @@ -0,0 +1,55 @@ +//! Re-exports either the Rust `std` library or `core` and `alloc` when `std` is +//! disabled. +//! +//! `crate::stdlib::...` should be used rather than `std::` when adding code that +//! will be available with the standard library disabled. +//! +//! Note that this module is called `stdlib` rather than `std`, as Rust 1.34.0 +//! does not permit redefining the name `stdlib` (although this works on the +//! latest stable Rust). +#[cfg(feature = "std")] +pub(crate) use std::*; + +#[cfg(not(feature = "std"))] +pub(crate) use self::no_std::*; + +#[cfg(not(feature = "std"))] +mod no_std { + // We pre-emptively export everything from libcore/liballoc, (even modules + // we aren't using currently) to make adding new code easier. Therefore, + // some of these imports will be unused. + #![allow(unused_imports)] + + pub(crate) use core::{ + any, array, ascii, cell, char, clone, cmp, convert, default, f32, f64, ffi, future, hash, + hint, i128, i16, i8, isize, iter, marker, mem, num, ops, option, pin, ptr, result, task, + time, u128, u16, u32, u8, usize, + }; + + pub(crate) use alloc::{boxed, collections, rc, string, vec}; + + pub(crate) mod borrow { + pub(crate) use alloc::borrow::*; + pub(crate) use core::borrow::*; + } + + pub(crate) mod fmt { + pub(crate) use alloc::fmt::*; + pub(crate) use core::fmt::*; + } + + pub(crate) mod slice { + pub(crate) use alloc::slice::*; + pub(crate) use core::slice::*; + } + + pub(crate) mod str { + pub(crate) use alloc::str::*; + pub(crate) use core::str::*; + } + + pub(crate) mod sync { + pub(crate) use alloc::sync::*; + pub(crate) use core::sync::*; + } +} diff --git a/third_party/rust/tracing/src/subscriber.rs b/third_party/rust/tracing/src/subscriber.rs new file mode 100644 index 0000000000..8f35d84e09 --- /dev/null +++ b/third_party/rust/tracing/src/subscriber.rs @@ -0,0 +1,68 @@ +//! Collects and records trace data. +pub use tracing_core::subscriber::*; + +#[cfg(feature = "std")] +#[cfg_attr(docsrs, doc(cfg(feature = "std")))] +pub use tracing_core::dispatcher::DefaultGuard; + +/// Sets this subscriber as the default for the duration of a closure. +/// +/// The default subscriber is used when creating a new [`Span`] or +/// [`Event`], _if no span is currently executing_. If a span is currently +/// executing, new spans or events are dispatched to the subscriber that +/// tagged that span, instead. +/// +/// [`Span`]: ../span/struct.Span.html +/// [`Subscriber`]: ../subscriber/trait.Subscriber.html +/// [`Event`]: :../event/struct.Event.html +#[cfg(feature = "std")] +#[cfg_attr(docsrs, doc(cfg(feature = "std")))] +pub fn with_default<T, S>(subscriber: S, f: impl FnOnce() -> T) -> T +where + S: Subscriber + Send + Sync + 'static, +{ + crate::dispatcher::with_default(&crate::Dispatch::new(subscriber), f) +} + +/// Sets this subscriber as the global default for the duration of the entire program. +/// Will be used as a fallback if no thread-local subscriber has been set in a thread (using `with_default`.) +/// +/// Can only be set once; subsequent attempts to set the global default will fail. +/// Returns whether the initialization was successful. +/// +/// Note: Libraries should *NOT* call `set_global_default()`! That will cause conflicts when +/// executables try to set them later. +/// +/// [span]: ../span/index.html +/// [`Subscriber`]: ../subscriber/trait.Subscriber.html +/// [`Event`]: ../event/struct.Event.html +pub fn set_global_default<S>(subscriber: S) -> Result<(), SetGlobalDefaultError> +where + S: Subscriber + Send + Sync + 'static, +{ + crate::dispatcher::set_global_default(crate::Dispatch::new(subscriber)) +} + +/// Sets the subscriber as the default for the duration of the lifetime of the +/// returned [`DefaultGuard`] +/// +/// The default subscriber is used when creating a new [`Span`] or +/// [`Event`], _if no span is currently executing_. If a span is currently +/// executing, new spans or events are dispatched to the subscriber that +/// tagged that span, instead. +/// +/// [`Span`]: ../span/struct.Span.html +/// [`Subscriber`]: ../subscriber/trait.Subscriber.html +/// [`Event`]: :../event/struct.Event.html +/// [`DefaultGuard`]: ../dispatcher/struct.DefaultGuard.html +#[cfg(feature = "std")] +#[cfg_attr(docsrs, doc(cfg(feature = "std")))] +#[must_use = "Dropping the guard unregisters the subscriber."] +pub fn set_default<S>(subscriber: S) -> DefaultGuard +where + S: Subscriber + Send + Sync + 'static, +{ + crate::dispatcher::set_default(&crate::Dispatch::new(subscriber)) +} + +pub use tracing_core::dispatcher::SetGlobalDefaultError; diff --git a/third_party/rust/tracing/tests/event.rs b/third_party/rust/tracing/tests/event.rs new file mode 100644 index 0000000000..d61ef748b8 --- /dev/null +++ b/third_party/rust/tracing/tests/event.rs @@ -0,0 +1,375 @@ +// These tests require the thread-local scoped dispatcher, which only works when +// we have a standard library. The behaviour being tested should be the same +// with the standard lib disabled. +// +// The alternative would be for each of these tests to be defined in a separate +// file, which is :( +#![cfg(feature = "std")] + +#[macro_use] +extern crate tracing; +mod support; + +use self::support::*; + +use tracing::{ + field::{debug, display}, + subscriber::with_default, + Level, +}; + +macro_rules! event_without_message { + ($name:ident: $e:expr) => { + #[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)] + #[test] + fn $name() { + let (subscriber, handle) = subscriber::mock() + .event( + event::mock().with_fields( + field::mock("answer") + .with_value(&42) + .and( + field::mock("to_question") + .with_value(&"life, the universe, and everything"), + ) + .only(), + ), + ) + .done() + .run_with_handle(); + + with_default(subscriber, || { + info!( + answer = $e, + to_question = "life, the universe, and everything" + ); + }); + + handle.assert_finished(); + } + }; +} + +event_without_message! {event_without_message: 42} +event_without_message! {wrapping_event_without_message: std::num::Wrapping(42)} +event_without_message! {nonzeroi32_event_without_message: std::num::NonZeroI32::new(42).unwrap()} +// needs API breakage +//event_without_message!{nonzerou128_event_without_message: std::num::NonZeroU128::new(42).unwrap()} + +#[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)] +#[test] +fn event_with_message() { + let (subscriber, handle) = subscriber::mock() + .event(event::mock().with_fields(field::mock("message").with_value( + &tracing::field::debug(format_args!("hello from my event! yak shaved = {:?}", true)), + ))) + .done() + .run_with_handle(); + + with_default(subscriber, || { + debug!("hello from my event! yak shaved = {:?}", true); + }); + + handle.assert_finished(); +} + +#[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)] +#[test] +fn message_without_delims() { + let (subscriber, handle) = subscriber::mock() + .event( + event::mock().with_fields( + field::mock("answer") + .with_value(&42) + .and(field::mock("question").with_value(&"life, the universe, and everything")) + .and( + field::mock("message").with_value(&tracing::field::debug(format_args!( + "hello from my event! tricky? {:?}!", + true + ))), + ) + .only(), + ), + ) + .done() + .run_with_handle(); + + with_default(subscriber, || { + let question = "life, the universe, and everything"; + debug!(answer = 42, question, "hello from {where}! tricky? {:?}!", true, where = "my event"); + }); + + handle.assert_finished(); +} + +#[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)] +#[test] +fn string_message_without_delims() { + let (subscriber, handle) = subscriber::mock() + .event( + event::mock().with_fields( + field::mock("answer") + .with_value(&42) + .and(field::mock("question").with_value(&"life, the universe, and everything")) + .and( + field::mock("message").with_value(&tracing::field::debug(format_args!( + "hello from my event" + ))), + ) + .only(), + ), + ) + .done() + .run_with_handle(); + + with_default(subscriber, || { + let question = "life, the universe, and everything"; + debug!(answer = 42, question, "hello from my event"); + }); + + handle.assert_finished(); +} + +#[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)] +#[test] +fn one_with_everything() { + let (subscriber, handle) = subscriber::mock() + .event( + event::mock() + .with_fields( + field::mock("message") + .with_value(&tracing::field::debug(format_args!( + "{:#x} make me one with{what:.>20}", + 4_277_009_102u64, + what = "everything" + ))) + .and(field::mock("foo").with_value(&666)) + .and(field::mock("bar").with_value(&false)) + .only(), + ) + .at_level(Level::ERROR) + .with_target("whatever"), + ) + .done() + .run_with_handle(); + + with_default(subscriber, || { + event!( + target: "whatever", + Level::ERROR, + { foo = 666, bar = false }, + "{:#x} make me one with{what:.>20}", 4_277_009_102u64, what = "everything" + ); + }); + + handle.assert_finished(); +} + +#[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)] +#[test] +fn moved_field() { + let (subscriber, handle) = subscriber::mock() + .event( + event::mock().with_fields( + field::mock("foo") + .with_value(&display("hello from my event")) + .only(), + ), + ) + .done() + .run_with_handle(); + with_default(subscriber, || { + let from = "my event"; + event!(Level::INFO, foo = display(format!("hello from {}", from))) + }); + + handle.assert_finished(); +} + +#[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)] +#[test] +fn dotted_field_name() { + let (subscriber, handle) = subscriber::mock() + .event( + event::mock().with_fields( + field::mock("foo.bar") + .with_value(&true) + .and(field::mock("foo.baz").with_value(&false)) + .only(), + ), + ) + .done() + .run_with_handle(); + with_default(subscriber, || { + event!(Level::INFO, foo.bar = true, foo.baz = false); + }); + + handle.assert_finished(); +} + +#[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)] +#[test] +fn borrowed_field() { + let (subscriber, handle) = subscriber::mock() + .event( + event::mock().with_fields( + field::mock("foo") + .with_value(&display("hello from my event")) + .only(), + ), + ) + .done() + .run_with_handle(); + with_default(subscriber, || { + let from = "my event"; + let mut message = format!("hello from {}", from); + event!(Level::INFO, foo = display(&message)); + message.push_str(", which happened!"); + }); + + handle.assert_finished(); +} + +#[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)] +#[test] +// If emitting log instrumentation, this gets moved anyway, breaking the test. +#[cfg(not(feature = "log"))] +fn move_field_out_of_struct() { + use tracing::field::debug; + + #[derive(Debug)] + struct Position { + x: f32, + y: f32, + } + + let pos = Position { + x: 3.234, + y: -1.223, + }; + let (subscriber, handle) = subscriber::mock() + .event( + event::mock().with_fields( + field::mock("x") + .with_value(&debug(3.234)) + .and(field::mock("y").with_value(&debug(-1.223))) + .only(), + ), + ) + .event(event::mock().with_fields(field::mock("position").with_value(&debug(&pos)))) + .done() + .run_with_handle(); + + with_default(subscriber, || { + let pos = Position { + x: 3.234, + y: -1.223, + }; + debug!(x = debug(pos.x), y = debug(pos.y)); + debug!(target: "app_events", { position = debug(pos) }, "New position"); + }); + handle.assert_finished(); +} + +#[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)] +#[test] +fn display_shorthand() { + let (subscriber, handle) = subscriber::mock() + .event( + event::mock().with_fields( + field::mock("my_field") + .with_value(&display("hello world")) + .only(), + ), + ) + .done() + .run_with_handle(); + with_default(subscriber, || { + event!(Level::TRACE, my_field = %"hello world"); + }); + + handle.assert_finished(); +} + +#[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)] +#[test] +fn debug_shorthand() { + let (subscriber, handle) = subscriber::mock() + .event( + event::mock().with_fields( + field::mock("my_field") + .with_value(&debug("hello world")) + .only(), + ), + ) + .done() + .run_with_handle(); + with_default(subscriber, || { + event!(Level::TRACE, my_field = ?"hello world"); + }); + + handle.assert_finished(); +} + +#[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)] +#[test] +fn both_shorthands() { + let (subscriber, handle) = subscriber::mock() + .event( + event::mock().with_fields( + field::mock("display_field") + .with_value(&display("hello world")) + .and(field::mock("debug_field").with_value(&debug("hello world"))) + .only(), + ), + ) + .done() + .run_with_handle(); + with_default(subscriber, || { + event!(Level::TRACE, display_field = %"hello world", debug_field = ?"hello world"); + }); + + handle.assert_finished(); +} + +#[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)] +#[test] +fn explicit_child() { + let (subscriber, handle) = subscriber::mock() + .new_span(span::mock().named("foo")) + .event(event::mock().with_explicit_parent(Some("foo"))) + .done() + .run_with_handle(); + + with_default(subscriber, || { + let foo = span!(Level::TRACE, "foo"); + event!(parent: foo.id(), Level::TRACE, "bar"); + }); + + handle.assert_finished(); +} + +#[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)] +#[test] +fn explicit_child_at_levels() { + let (subscriber, handle) = subscriber::mock() + .new_span(span::mock().named("foo")) + .event(event::mock().with_explicit_parent(Some("foo"))) + .event(event::mock().with_explicit_parent(Some("foo"))) + .event(event::mock().with_explicit_parent(Some("foo"))) + .event(event::mock().with_explicit_parent(Some("foo"))) + .event(event::mock().with_explicit_parent(Some("foo"))) + .done() + .run_with_handle(); + + with_default(subscriber, || { + let foo = span!(Level::TRACE, "foo"); + trace!(parent: foo.id(), "a"); + debug!(parent: foo.id(), "b"); + info!(parent: foo.id(), "c"); + warn!(parent: foo.id(), "d"); + error!(parent: foo.id(), "e"); + }); + + handle.assert_finished(); +} diff --git a/third_party/rust/tracing/tests/filter_caching_is_lexically_scoped.rs b/third_party/rust/tracing/tests/filter_caching_is_lexically_scoped.rs new file mode 100644 index 0000000000..9b997a0c6b --- /dev/null +++ b/third_party/rust/tracing/tests/filter_caching_is_lexically_scoped.rs @@ -0,0 +1,69 @@ +// Tests that depend on a count of the number of times their filter is evaluated +// can't exist in the same file with other tests that add subscribers to the +// registry. The registry was changed so that each time a new dispatcher is +// added all filters are re-evaluated. The tests being run only in separate +// threads with shared global state lets them interfere with each other + +#[cfg(not(feature = "std"))] +extern crate std; + +#[macro_use] +extern crate tracing; +mod support; + +use self::support::*; +use tracing::Level; + +use std::sync::{ + atomic::{AtomicUsize, Ordering}, + Arc, +}; + +#[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)] +#[test] +fn filter_caching_is_lexically_scoped() { + pub fn my_great_function() -> bool { + span!(Level::TRACE, "emily").in_scope(|| true) + } + + pub fn my_other_function() -> bool { + span!(Level::TRACE, "frank").in_scope(|| true) + } + + let count = Arc::new(AtomicUsize::new(0)); + let count2 = count.clone(); + + let subscriber = subscriber::mock() + .with_filter(move |meta| match meta.name() { + "emily" | "frank" => { + count2.fetch_add(1, Ordering::Relaxed); + true + } + _ => false, + }) + .run(); + + // Since this test is in its own file anyway, we can do this. Thus, this + // test will work even with no-std. + tracing::subscriber::set_global_default(subscriber).unwrap(); + + // Call the function once. The filter should be re-evaluated. + assert!(my_great_function()); + assert_eq!(count.load(Ordering::Relaxed), 1); + + // Call the function again. The cached result should be used. + assert!(my_great_function()); + assert_eq!(count.load(Ordering::Relaxed), 1); + + assert!(my_other_function()); + assert_eq!(count.load(Ordering::Relaxed), 2); + + assert!(my_great_function()); + assert_eq!(count.load(Ordering::Relaxed), 2); + + assert!(my_other_function()); + assert_eq!(count.load(Ordering::Relaxed), 2); + + assert!(my_great_function()); + assert_eq!(count.load(Ordering::Relaxed), 2); +} diff --git a/third_party/rust/tracing/tests/filters_are_not_reevaluated_for_the_same_span.rs b/third_party/rust/tracing/tests/filters_are_not_reevaluated_for_the_same_span.rs new file mode 100644 index 0000000000..53e11ef448 --- /dev/null +++ b/third_party/rust/tracing/tests/filters_are_not_reevaluated_for_the_same_span.rs @@ -0,0 +1,74 @@ +// Tests that depend on a count of the number of times their filter is evaluated +// cant exist in the same file with other tests that add subscribers to the +// registry. The registry was changed so that each time a new dispatcher is +// added all filters are re-evaluated. The tests being run only in separate +// threads with shared global state lets them interfere with each other +#[cfg(not(feature = "std"))] +extern crate std; + +#[macro_use] +extern crate tracing; +mod support; + +use self::support::*; +use tracing::Level; + +use std::sync::{ + atomic::{AtomicUsize, Ordering}, + Arc, +}; + +#[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)] +#[test] +fn filters_are_not_reevaluated_for_the_same_span() { + // Asserts that the `span!` macro caches the result of calling + // `Subscriber::enabled` for each span. + let alice_count = Arc::new(AtomicUsize::new(0)); + let bob_count = Arc::new(AtomicUsize::new(0)); + let alice_count2 = alice_count.clone(); + let bob_count2 = bob_count.clone(); + + let (subscriber, handle) = subscriber::mock() + .with_filter(move |meta| match meta.name() { + "alice" => { + alice_count2.fetch_add(1, Ordering::Relaxed); + false + } + "bob" => { + bob_count2.fetch_add(1, Ordering::Relaxed); + true + } + _ => false, + }) + .run_with_handle(); + + // Since this test is in its own file anyway, we can do this. Thus, this + // test will work even with no-std. + tracing::subscriber::set_global_default(subscriber).unwrap(); + + // Enter "alice" and then "bob". The dispatcher expects to see "bob" but + // not "alice." + let alice = span!(Level::TRACE, "alice"); + let bob = alice.in_scope(|| { + let bob = span!(Level::TRACE, "bob"); + bob.in_scope(|| ()); + bob + }); + + // The filter should have seen each span a single time. + assert_eq!(alice_count.load(Ordering::Relaxed), 1); + assert_eq!(bob_count.load(Ordering::Relaxed), 1); + + alice.in_scope(|| bob.in_scope(|| {})); + + // The subscriber should see "bob" again, but the filter should not have + // been called. + assert_eq!(alice_count.load(Ordering::Relaxed), 1); + assert_eq!(bob_count.load(Ordering::Relaxed), 1); + + bob.in_scope(|| {}); + assert_eq!(alice_count.load(Ordering::Relaxed), 1); + assert_eq!(bob_count.load(Ordering::Relaxed), 1); + + handle.assert_finished(); +} diff --git a/third_party/rust/tracing/tests/filters_are_reevaluated_for_different_call_sites.rs b/third_party/rust/tracing/tests/filters_are_reevaluated_for_different_call_sites.rs new file mode 100644 index 0000000000..5675e4e678 --- /dev/null +++ b/third_party/rust/tracing/tests/filters_are_reevaluated_for_different_call_sites.rs @@ -0,0 +1,84 @@ +// Tests that depend on a count of the number of times their filter is evaluated +// cant exist in the same file with other tests that add subscribers to the +// registry. The registry was changed so that each time a new dispatcher is +// added all filters are re-evaluated. The tests being run only in separate +// threads with shared global state lets them interfere with each other +#[cfg(not(feature = "std"))] +extern crate std; + +#[macro_use] +extern crate tracing; +mod support; + +use self::support::*; +use tracing::Level; + +use std::sync::{ + atomic::{AtomicUsize, Ordering}, + Arc, +}; + +#[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)] +#[test] +fn filters_are_reevaluated_for_different_call_sites() { + // Asserts that the `span!` macro caches the result of calling + // `Subscriber::enabled` for each span. + let charlie_count = Arc::new(AtomicUsize::new(0)); + let dave_count = Arc::new(AtomicUsize::new(0)); + let charlie_count2 = charlie_count.clone(); + let dave_count2 = dave_count.clone(); + + let subscriber = subscriber::mock() + .with_filter(move |meta| { + println!("Filter: {:?}", meta.name()); + match meta.name() { + "charlie" => { + charlie_count2.fetch_add(1, Ordering::Relaxed); + false + } + "dave" => { + dave_count2.fetch_add(1, Ordering::Relaxed); + true + } + _ => false, + } + }) + .run(); + + // Since this test is in its own file anyway, we can do this. Thus, this + // test will work even with no-std. + tracing::subscriber::set_global_default(subscriber).unwrap(); + + // Enter "charlie" and then "dave". The dispatcher expects to see "dave" but + // not "charlie." + let charlie = span!(Level::TRACE, "charlie"); + let dave = charlie.in_scope(|| { + let dave = span!(Level::TRACE, "dave"); + dave.in_scope(|| {}); + dave + }); + + // The filter should have seen each span a single time. + assert_eq!(charlie_count.load(Ordering::Relaxed), 1); + assert_eq!(dave_count.load(Ordering::Relaxed), 1); + + charlie.in_scope(|| dave.in_scope(|| {})); + + // The subscriber should see "dave" again, but the filter should not have + // been called. + assert_eq!(charlie_count.load(Ordering::Relaxed), 1); + assert_eq!(dave_count.load(Ordering::Relaxed), 1); + + // A different span with the same name has a different call site, so it + // should cause the filter to be reapplied. + let charlie2 = span!(Level::TRACE, "charlie"); + charlie.in_scope(|| {}); + assert_eq!(charlie_count.load(Ordering::Relaxed), 2); + assert_eq!(dave_count.load(Ordering::Relaxed), 1); + + // But, the filter should not be re-evaluated for the new "charlie" span + // when it is re-entered. + charlie2.in_scope(|| span!(Level::TRACE, "dave").in_scope(|| {})); + assert_eq!(charlie_count.load(Ordering::Relaxed), 2); + assert_eq!(dave_count.load(Ordering::Relaxed), 2); +} diff --git a/third_party/rust/tracing/tests/filters_dont_leak.rs b/third_party/rust/tracing/tests/filters_dont_leak.rs new file mode 100644 index 0000000000..666335a8a4 --- /dev/null +++ b/third_party/rust/tracing/tests/filters_dont_leak.rs @@ -0,0 +1,82 @@ +#![cfg(feature = "std")] + +mod support; +use self::support::*; + +#[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)] +#[test] +fn spans_dont_leak() { + fn do_span() { + let span = tracing::debug_span!("alice"); + let _e = span.enter(); + } + + let (subscriber, handle) = subscriber::mock() + .named("spans/subscriber1") + .with_filter(|_| false) + .done() + .run_with_handle(); + + let _guard = tracing::subscriber::set_default(subscriber); + + do_span(); + + let alice = span::mock().named("alice"); + let (subscriber2, handle2) = subscriber::mock() + .named("spans/subscriber2") + .with_filter(|_| true) + .new_span(alice.clone()) + .enter(alice.clone()) + .exit(alice.clone()) + .drop_span(alice) + .done() + .run_with_handle(); + + tracing::subscriber::with_default(subscriber2, || { + println!("--- subscriber 2 is default ---"); + do_span() + }); + + println!("--- subscriber 1 is default ---"); + do_span(); + + handle.assert_finished(); + handle2.assert_finished(); +} + +#[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)] +#[test] +fn events_dont_leak() { + fn do_event() { + tracing::debug!("alice"); + } + + let (subscriber, handle) = subscriber::mock() + .named("events/subscriber1") + .with_filter(|_| false) + .done() + .run_with_handle(); + + let _guard = tracing::subscriber::set_default(subscriber); + + do_event(); + + let (subscriber2, handle2) = subscriber::mock() + .named("events/subscriber2") + .with_filter(|_| true) + .event(event::mock()) + .done() + .run_with_handle(); + + tracing::subscriber::with_default(subscriber2, || { + println!("--- subscriber 2 is default ---"); + do_event() + }); + + println!("--- subscriber 1 is default ---"); + + do_event(); + + handle.assert_finished(); + handle2.assert_finished(); +} diff --git a/third_party/rust/tracing/tests/macro_imports.rs b/third_party/rust/tracing/tests/macro_imports.rs new file mode 100644 index 0000000000..2d0a9d6528 --- /dev/null +++ b/third_party/rust/tracing/tests/macro_imports.rs @@ -0,0 +1,23 @@ +use tracing::Level; + +#[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)] +#[test] +fn prefixed_span_macros() { + tracing::span!(Level::DEBUG, "foo"); + tracing::trace_span!("foo"); + tracing::debug_span!("foo"); + tracing::info_span!("foo"); + tracing::warn_span!("foo"); + tracing::error_span!("foo"); +} + +#[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)] +#[test] +fn prefixed_event_macros() { + tracing::event!(Level::DEBUG, "foo"); + tracing::trace!("foo"); + tracing::debug!("foo"); + tracing::info!("foo"); + tracing::warn!("foo"); + tracing::error!("foo"); +} diff --git a/third_party/rust/tracing/tests/macros.rs b/third_party/rust/tracing/tests/macros.rs new file mode 100644 index 0000000000..39642667f7 --- /dev/null +++ b/third_party/rust/tracing/tests/macros.rs @@ -0,0 +1,890 @@ +#![deny(warnings)] +use tracing::Level; + +#[macro_use] +extern crate tracing; +// Tests that macros work across various invocation syntax. +// +// These are quite repetitive, and _could_ be generated by a macro. However, +// they're compile-time tests, so I want to get line numbers etc out of +// failures, and producing them with a macro would muddy the waters a bit. + +#[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)] +#[test] +fn span() { + span!(target: "foo_events", Level::DEBUG, "foo", bar.baz = ?2, quux = %3, quuux = 4); + span!(target: "foo_events", Level::DEBUG, "foo", bar.baz = 2, quux = 3); + span!(target: "foo_events", Level::DEBUG, "foo", bar.baz = 2, quux = 4,); + span!(target: "foo_events", Level::DEBUG, "foo"); + span!(target: "foo_events", Level::DEBUG, "bar",); + span!(Level::DEBUG, "foo", bar.baz = 2, quux = 3); + span!(Level::DEBUG, "foo", bar.baz = 2, quux = 4,); + span!(Level::DEBUG, "foo", bar.baz = 2, quux = 3); + span!(Level::DEBUG, "foo", bar.baz = 2, quux = 4,); + span!(Level::DEBUG, "foo", bar.baz = ?2); + span!(Level::DEBUG, "foo", bar.baz = %2); + span!(Level::DEBUG, "foo"); + span!(Level::DEBUG, "bar",); +} + +#[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)] +#[test] +fn trace_span() { + trace_span!(target: "foo_events", "foo", bar.baz = ?2, quux = %3, quuux = 4); + trace_span!(target: "foo_events", "foo", bar.baz = 2, quux = 3); + trace_span!(target: "foo_events", "foo", bar.baz = 2, quux = 4,); + trace_span!(target: "foo_events", "foo"); + trace_span!(target: "foo_events", "bar",); + trace_span!("foo", bar.baz = 2, quux = 3); + trace_span!("foo", bar.baz = 2, quux = 4,); + trace_span!("foo", bar.baz = ?2); + trace_span!("foo", bar.baz = %2); + trace_span!("bar"); + trace_span!("bar",); +} + +#[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)] +#[test] +fn debug_span() { + debug_span!(target: "foo_events", "foo", bar.baz = ?2, quux = %3, quuux = 4); + debug_span!(target: "foo_events", "foo", bar.baz = 2, quux = 3); + debug_span!(target: "foo_events", "foo", bar.baz = 2, quux = 4,); + debug_span!(target: "foo_events", "foo"); + debug_span!(target: "foo_events", "bar",); + debug_span!("foo", bar.baz = 2, quux = 3); + debug_span!("foo", bar.baz = 2, quux = 4,); + debug_span!("foo", bar.baz = ?2); + debug_span!("foo", bar.baz = %2); + debug_span!("bar"); + debug_span!("bar",); +} + +#[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)] +#[test] +fn info_span() { + info_span!(target: "foo_events", "foo", bar.baz = ?2, quux = %3, quuux = 4); + info_span!(target: "foo_events", "foo", bar.baz = 2, quux = 3); + info_span!(target: "foo_events", "foo", bar.baz = 2, quux = 4,); + info_span!(target: "foo_events", "foo"); + info_span!(target: "foo_events", "bar",); + info_span!("foo", bar.baz = 2, quux = 3); + info_span!("foo", bar.baz = 2, quux = 4,); + info_span!("foo", bar.baz = ?2); + info_span!("foo", bar.baz = %2); + info_span!("bar"); + info_span!("bar",); +} + +#[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)] +#[test] +fn warn_span() { + warn_span!(target: "foo_events", "foo", bar.baz = ?2, quux = %3, quuux = 4); + warn_span!(target: "foo_events", "foo", bar.baz = 2, quux = 3); + warn_span!(target: "foo_events", "foo", bar.baz = 2, quux = 4,); + warn_span!(target: "foo_events", "foo"); + warn_span!(target: "foo_events", "bar",); + warn_span!("foo", bar.baz = 2, quux = 3); + warn_span!("foo", bar.baz = 2, quux = 4,); + warn_span!("foo", bar.baz = ?2); + warn_span!("foo", bar.baz = %2); + warn_span!("bar"); + warn_span!("bar",); +} + +#[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)] +#[test] +fn error_span() { + error_span!(target: "foo_events", "foo", bar.baz = ?2, quux = %3, quuux = 4); + error_span!(target: "foo_events", "foo", bar.baz = 2, quux = 3); + error_span!(target: "foo_events", "foo", bar.baz = 2, quux = 4,); + error_span!(target: "foo_events", "foo"); + error_span!(target: "foo_events", "bar",); + error_span!("foo", bar.baz = 2, quux = 3); + error_span!("foo", bar.baz = 2, quux = 4,); + error_span!("foo", bar.baz = ?2); + error_span!("foo", bar.baz = %2); + error_span!("bar"); + error_span!("bar",); +} + +#[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)] +#[test] +fn span_root() { + span!(target: "foo_events", parent: None, Level::TRACE, "foo", bar.baz = 2, quux = 3); + span!(target: "foo_events", parent: None, Level::TRACE, "foo", bar.baz = 2, quux = 3); + span!(target: "foo_events", parent: None, Level::TRACE, "foo", bar.baz = 2, quux = 4,); + span!(target: "foo_events", parent: None, Level::TRACE, "foo"); + span!(target: "foo_events", parent: None, Level::TRACE, "bar",); + span!(parent: None, Level::DEBUG, "foo", bar.baz = 2, quux = 3); + span!(parent: None, Level::DEBUG, "foo", bar.baz = 2, quux = 4,); + span!(parent: None, Level::DEBUG, "foo"); + span!(parent: None, Level::DEBUG, "bar",); +} + +#[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)] +#[test] +fn trace_span_root() { + trace_span!(target: "foo_events", parent: None, "foo", bar.baz = 2, quux = 3); + trace_span!(target: "foo_events", parent: None, "foo", bar.baz = 2, quux = 4,); + trace_span!(target: "foo_events", parent: None, "foo"); + trace_span!(target: "foo_events", parent: None, "bar",); + trace_span!(parent: None, "foo", bar.baz = 2, quux = 3); + trace_span!(parent: None, "foo", bar.baz = 2, quux = 4,); + trace_span!(parent: None, "foo"); + trace_span!(parent: None, "bar",); +} + +#[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)] +#[test] +fn debug_span_root() { + debug_span!(target: "foo_events", parent: None, "foo", bar.baz = 2, quux = 3); + debug_span!(target: "foo_events", parent: None, "foo", bar.baz = 2, quux = 4,); + debug_span!(target: "foo_events", parent: None, "foo"); + debug_span!(target: "foo_events", parent: None, "bar",); + debug_span!(parent: None, "foo", bar.baz = 2, quux = 3); + debug_span!(parent: None, "foo", bar.baz = 2, quux = 4,); + debug_span!(parent: None, "foo"); + debug_span!(parent: None, "bar",); +} + +#[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)] +#[test] +fn info_span_root() { + info_span!(target: "foo_events", parent: None, "foo", bar.baz = 2, quux = 3); + info_span!(target: "foo_events", parent: None, "foo", bar.baz = 2, quux = 4,); + info_span!(target: "foo_events", parent: None, "foo"); + info_span!(target: "foo_events", parent: None, "bar",); + info_span!(parent: None, "foo", bar.baz = 2, quux = 3); + info_span!(parent: None, "foo", bar.baz = 2, quux = 4,); + info_span!(parent: None, "foo"); + info_span!(parent: None, "bar",); +} + +#[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)] +#[test] +fn warn_span_root() { + warn_span!(target: "foo_events", parent: None, "foo", bar.baz = 2, quux = 3); + warn_span!(target: "foo_events", parent: None, "foo", bar.baz = 2, quux = 4,); + warn_span!(target: "foo_events", parent: None, "foo"); + warn_span!(target: "foo_events", parent: None, "bar",); + warn_span!(parent: None, "foo", bar.baz = 2, quux = 3); + warn_span!(parent: None, "foo", bar.baz = 2, quux = 4,); + warn_span!(parent: None, "foo"); + warn_span!(parent: None, "bar",); +} + +#[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)] +#[test] +fn error_span_root() { + error_span!(target: "foo_events", parent: None, "foo", bar.baz = 2, quux = 3); + error_span!(target: "foo_events", parent: None, "foo", bar.baz = 2, quux = 4,); + error_span!(target: "foo_events", parent: None, "foo"); + error_span!(target: "foo_events", parent: None, "bar",); + error_span!(parent: None, "foo", bar.baz = 2, quux = 3); + error_span!(parent: None, "foo", bar.baz = 2, quux = 4,); + error_span!(parent: None, "foo"); + error_span!(parent: None, "bar",); +} + +#[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)] +#[test] +fn span_with_parent() { + let p = span!(Level::TRACE, "im_a_parent!"); + span!(target: "foo_events", parent: &p, Level::TRACE, "foo", bar.baz = 2, quux = 3); + span!(target: "foo_events", parent: &p, Level::TRACE, "foo", bar.baz = 2, quux = 4,); + span!(target: "foo_events", parent: &p, Level::TRACE, "foo"); + span!(target: "foo_events", parent: &p, Level::TRACE, "bar",); + span!(parent: &p, Level::DEBUG, "foo", bar.baz = 2, quux = 3); + span!(parent: &p, Level::DEBUG, "foo", bar.baz = 2, quux = 4,); + span!(parent: &p, Level::DEBUG, "foo"); + span!(parent: &p, Level::DEBUG, "bar",); +} + +#[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)] +#[test] +fn trace_span_with_parent() { + let p = span!(Level::TRACE, "im_a_parent!"); + trace_span!(target: "foo_events", parent: &p, "foo", bar.baz = 2, quux = 3); + trace_span!(target: "foo_events", parent: &p, "foo", bar.baz = 2, quux = 4,); + trace_span!(target: "foo_events", parent: &p, "foo"); + trace_span!(target: "foo_events", parent: &p, "bar",); + + trace_span!(parent: &p, "foo", bar.baz = 2, quux = 3); + trace_span!(parent: &p, "foo", bar.baz = 2, quux = 4,); + + trace_span!(parent: &p, "foo"); + trace_span!(parent: &p, "bar",); +} + +#[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)] +#[test] +fn debug_span_with_parent() { + let p = span!(Level::TRACE, "im_a_parent!"); + debug_span!(target: "foo_events", parent: &p, "foo", bar.baz = 2, quux = 3); + debug_span!(target: "foo_events", parent: &p, "foo", bar.baz = 2, quux = 4,); + debug_span!(target: "foo_events", parent: &p, "foo"); + debug_span!(target: "foo_events", parent: &p, "bar",); + + debug_span!(parent: &p, "foo", bar.baz = 2, quux = 3); + debug_span!(parent: &p, "foo", bar.baz = 2, quux = 4,); + + debug_span!(parent: &p, "foo"); + debug_span!(parent: &p, "bar",); +} + +#[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)] +#[test] +fn info_span_with_parent() { + let p = span!(Level::TRACE, "im_a_parent!"); + info_span!(target: "foo_events", parent: &p, "foo", bar.baz = 2, quux = 3); + info_span!(target: "foo_events", parent: &p, "foo", bar.baz = 2, quux = 4,); + info_span!(target: "foo_events", parent: &p, "foo"); + info_span!(target: "foo_events", parent: &p, "bar",); + + info_span!(parent: &p, "foo", bar.baz = 2, quux = 3); + info_span!(parent: &p, "foo", bar.baz = 2, quux = 4,); + + info_span!(parent: &p, "foo"); + info_span!(parent: &p, "bar",); +} + +#[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)] +#[test] +fn warn_span_with_parent() { + let p = span!(Level::TRACE, "im_a_parent!"); + warn_span!(target: "foo_events", parent: &p, "foo", bar.baz = 2, quux = 3); + warn_span!(target: "foo_events", parent: &p, "foo", bar.baz = 2, quux = 4,); + warn_span!(target: "foo_events", parent: &p, "foo"); + warn_span!(target: "foo_events", parent: &p, "bar",); + + warn_span!(parent: &p, "foo", bar.baz = 2, quux = 3); + warn_span!(parent: &p, "foo", bar.baz = 2, quux = 4,); + + warn_span!(parent: &p, "foo"); + warn_span!(parent: &p, "bar",); +} + +#[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)] +#[test] +fn error_span_with_parent() { + let p = span!(Level::TRACE, "im_a_parent!"); + error_span!(target: "foo_events", parent: &p, "foo", bar.baz = 2, quux = 3); + error_span!(target: "foo_events", parent: &p, "foo", bar.baz = 2, quux = 4,); + error_span!(target: "foo_events", parent: &p, "foo"); + error_span!(target: "foo_events", parent: &p, "bar",); + + error_span!(parent: &p, "foo", bar.baz = 2, quux = 3); + error_span!(parent: &p, "foo", bar.baz = 2, quux = 4,); + + error_span!(parent: &p, "foo"); + error_span!(parent: &p, "bar",); +} + +#[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)] +#[test] +fn span_with_non_rust_symbol() { + span!(Level::TRACE, "non-rust", "guid:x-request-id" = ?"abcdef", "more {}", 42); + span!(Level::TRACE, "non-rust", "guid:x-request-id" = %"abcdef", "more {}", 51); + span!( + Level::TRACE, + "non-rust", + "guid:x-request-id" = "abcdef", + "more {}", + 60 + ); + span!(Level::TRACE, "non-rust", "guid:x-request-id" = ?"abcdef"); + span!(Level::TRACE, "non-rust", "guid:x-request-id" = %"abcdef"); + span!(Level::TRACE, "non-rust", "guid:x-request-id" = "abcdef"); +} + +#[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)] +#[test] +fn event() { + event!(Level::DEBUG, foo = ?3, bar.baz = %2, quux = false); + event!(Level::DEBUG, foo = 3, bar.baz = 2, quux = false); + event!(Level::DEBUG, foo = 3, bar.baz = 3,); + event!(Level::DEBUG, "foo"); + event!(Level::DEBUG, "foo: {}", 3); + event!(Level::INFO, foo = ?3, bar.baz = %2, quux = false, "hello world {:?}", 42); + event!( + Level::INFO, + foo = 3, + bar.baz = 2, + quux = false, + "hello world {:?}", + 42 + ); + event!(Level::INFO, foo = 3, bar.baz = 3, "hello world {:?}", 42,); + event!(Level::DEBUG, { foo = 3, bar.baz = 80 }, "quux"); + event!(Level::DEBUG, { foo = 2, bar.baz = 79 }, "quux {:?}", true); + event!(Level::DEBUG, { foo = 2, bar.baz = 79 }, "quux {:?}, {quux}", true, quux = false); + event!(Level::DEBUG, { foo = ?2, bar.baz = %78 }, "quux"); + event!(target: "foo_events", Level::DEBUG, foo = 3, bar.baz = 2, quux = false); + event!(target: "foo_events", Level::DEBUG, foo = 3, bar.baz = 3,); + event!(target: "foo_events", Level::DEBUG, "foo"); + event!(target: "foo_events", Level::DEBUG, "foo: {}", 3); + event!(target: "foo_events", Level::DEBUG, { foo = 3, bar.baz = 80 }, "quux"); + event!(target: "foo_events", Level::DEBUG, { foo = 2, bar.baz = 79 }, "quux {:?}", true); + event!(target: "foo_events", Level::DEBUG, { foo = 2, bar.baz = 79 }, "quux {:?}, {quux}", true, quux = false); + event!(target: "foo_events", Level::DEBUG, { foo = 2, bar.baz = 78, }, "quux"); + let foo = 1; + event!(Level::DEBUG, ?foo); + event!(Level::DEBUG, %foo); + event!(Level::DEBUG, foo); +} + +#[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)] +#[test] +fn locals_with_message() { + let data = (42, "forty-two"); + let private_data = "private"; + let error = "a bad error"; + event!(Level::ERROR, %error, "Received error"); + event!( + target: "app_events", + Level::WARN, + private_data, + ?data, + "App warning: {}", + error + ); +} + +#[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)] +#[test] +fn locals_no_message() { + let data = (42, "forty-two"); + let private_data = "private"; + let error = "a bad error"; + event!( + target: "app_events", + Level::WARN, + private_data, + ?data, + ); + event!( + target: "app_events", + Level::WARN, + private_data, + ?data, + error, + ); + event!( + target: "app_events", + Level::WARN, + private_data, + ?data, + error + ); + event!(Level::WARN, private_data, ?data, error,); +} + +#[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)] +#[test] +fn trace() { + trace!(foo = ?3, bar.baz = %2, quux = false); + trace!(foo = 3, bar.baz = 2, quux = false); + trace!(foo = 3, bar.baz = 3,); + trace!("foo"); + trace!("foo: {}", 3); + trace!(foo = ?3, bar.baz = %2, quux = false, "hello world {:?}", 42); + trace!(foo = 3, bar.baz = 2, quux = false, "hello world {:?}", 42); + trace!(foo = 3, bar.baz = 3, "hello world {:?}", 42,); + trace!({ foo = 3, bar.baz = 80 }, "quux"); + trace!({ foo = 2, bar.baz = 79 }, "quux {:?}", true); + trace!({ foo = 2, bar.baz = 79 }, "quux {:?}, {quux}", true, quux = false); + trace!({ foo = 2, bar.baz = 78 }, "quux"); + trace!({ foo = ?2, bar.baz = %78 }, "quux"); + trace!(target: "foo_events", foo = 3, bar.baz = 2, quux = false); + trace!(target: "foo_events", foo = 3, bar.baz = 3,); + trace!(target: "foo_events", "foo"); + trace!(target: "foo_events", "foo: {}", 3); + trace!(target: "foo_events", { foo = 3, bar.baz = 80 }, "quux"); + trace!(target: "foo_events", { foo = 2, bar.baz = 79 }, "quux {:?}", true); + trace!(target: "foo_events", { foo = 2, bar.baz = 79 }, "quux {:?}, {quux}", true, quux = false); + trace!(target: "foo_events", { foo = 2, bar.baz = 78, }, "quux"); + let foo = 1; + trace!(?foo); + trace!(%foo); + trace!(foo); +} + +#[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)] +#[test] +fn debug() { + debug!(foo = ?3, bar.baz = %2, quux = false); + debug!(foo = 3, bar.baz = 2, quux = false); + debug!(foo = 3, bar.baz = 3,); + debug!("foo"); + debug!("foo: {}", 3); + debug!(foo = ?3, bar.baz = %2, quux = false, "hello world {:?}", 42); + debug!(foo = 3, bar.baz = 2, quux = false, "hello world {:?}", 42); + debug!(foo = 3, bar.baz = 3, "hello world {:?}", 42,); + debug!({ foo = 3, bar.baz = 80 }, "quux"); + debug!({ foo = 2, bar.baz = 79 }, "quux {:?}", true); + debug!({ foo = 2, bar.baz = 79 }, "quux {:?}, {quux}", true, quux = false); + debug!({ foo = 2, bar.baz = 78 }, "quux"); + debug!({ foo = ?2, bar.baz = %78 }, "quux"); + debug!(target: "foo_events", foo = 3, bar.baz = 2, quux = false); + debug!(target: "foo_events", foo = 3, bar.baz = 3,); + debug!(target: "foo_events", "foo"); + debug!(target: "foo_events", "foo: {}", 3); + debug!(target: "foo_events", { foo = 3, bar.baz = 80 }, "quux"); + debug!(target: "foo_events", { foo = 2, bar.baz = 79 }, "quux {:?}", true); + debug!(target: "foo_events", { foo = 2, bar.baz = 79 }, "quux {:?}, {quux}", true, quux = false); + debug!(target: "foo_events", { foo = 2, bar.baz = 78, }, "quux"); + let foo = 1; + debug!(?foo); + debug!(%foo); + debug!(foo); +} + +#[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)] +#[test] +fn info() { + info!(foo = ?3, bar.baz = %2, quux = false); + info!(foo = 3, bar.baz = 2, quux = false); + info!(foo = 3, bar.baz = 3,); + info!("foo"); + info!("foo: {}", 3); + info!(foo = ?3, bar.baz = %2, quux = false, "hello world {:?}", 42); + info!(foo = 3, bar.baz = 2, quux = false, "hello world {:?}", 42); + info!(foo = 3, bar.baz = 3, "hello world {:?}", 42,); + info!({ foo = 3, bar.baz = 80 }, "quux"); + info!({ foo = 2, bar.baz = 79 }, "quux {:?}", true); + info!({ foo = 2, bar.baz = 79 }, "quux {:?}, {quux}", true, quux = false); + info!({ foo = 2, bar.baz = 78 }, "quux"); + info!({ foo = ?2, bar.baz = %78 }, "quux"); + info!(target: "foo_events", foo = 3, bar.baz = 2, quux = false); + info!(target: "foo_events", foo = 3, bar.baz = 3,); + info!(target: "foo_events", "foo"); + info!(target: "foo_events", "foo: {}", 3); + info!(target: "foo_events", { foo = 3, bar.baz = 80 }, "quux"); + info!(target: "foo_events", { foo = 2, bar.baz = 79 }, "quux {:?}", true); + info!(target: "foo_events", { foo = 2, bar.baz = 79 }, "quux {:?}, {quux}", true, quux = false); + info!(target: "foo_events", { foo = 2, bar.baz = 78, }, "quux"); + let foo = 1; + info!(?foo); + info!(%foo); + info!(foo); +} + +#[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)] +#[test] +fn warn() { + warn!(foo = ?3, bar.baz = %2, quux = false); + warn!(foo = 3, bar.baz = 2, quux = false); + warn!(foo = 3, bar.baz = 3,); + warn!("foo"); + warn!("foo: {}", 3); + warn!(foo = ?3, bar.baz = %2, quux = false, "hello world {:?}", 42); + warn!(foo = 3, bar.baz = 2, quux = false, "hello world {:?}", 42); + warn!(foo = 3, bar.baz = 3, "hello world {:?}", 42,); + warn!({ foo = 3, bar.baz = 80 }, "quux"); + warn!({ foo = 2, bar.baz = 79 }, "quux {:?}", true); + warn!({ foo = 2, bar.baz = 79 }, "quux {:?}, {quux}", true, quux = false); + warn!({ foo = 2, bar.baz = 78 }, "quux"); + warn!({ foo = ?2, bar.baz = %78 }, "quux"); + warn!(target: "foo_events", foo = 3, bar.baz = 2, quux = false); + warn!(target: "foo_events", foo = 3, bar.baz = 3,); + warn!(target: "foo_events", "foo"); + warn!(target: "foo_events", "foo: {}", 3); + warn!(target: "foo_events", { foo = 3, bar.baz = 80 }, "quux"); + warn!(target: "foo_events", { foo = 2, bar.baz = 79 }, "quux {:?}", true); + warn!(target: "foo_events", { foo = 2, bar.baz = 79 }, "quux {:?}, {quux}", true, quux = false); + warn!(target: "foo_events", { foo = 2, bar.baz = 78, }, "quux"); + let foo = 1; + warn!(?foo); + warn!(%foo); + warn!(foo); +} + +#[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)] +#[test] +fn error() { + error!(foo = ?3, bar.baz = %2, quux = false); + error!(foo = 3, bar.baz = 2, quux = false); + error!(foo = 3, bar.baz = 3,); + error!("foo"); + error!("foo: {}", 3); + error!(foo = ?3, bar.baz = %2, quux = false, "hello world {:?}", 42); + error!(foo = 3, bar.baz = 2, quux = false, "hello world {:?}", 42); + error!(foo = 3, bar.baz = 3, "hello world {:?}", 42,); + error!({ foo = 3, bar.baz = 80 }, "quux"); + error!({ foo = 2, bar.baz = 79 }, "quux {:?}", true); + error!({ foo = 2, bar.baz = 79 }, "quux {:?}, {quux}", true, quux = false); + error!({ foo = 2, bar.baz = 78, }, "quux"); + error!({ foo = ?2, bar.baz = %78 }, "quux"); + error!(target: "foo_events", foo = 3, bar.baz = 2, quux = false); + error!(target: "foo_events", foo = 3, bar.baz = 3,); + error!(target: "foo_events", "foo"); + error!(target: "foo_events", "foo: {}", 3); + error!(target: "foo_events", { foo = 3, bar.baz = 80 }, "quux"); + error!(target: "foo_events", { foo = 2, bar.baz = 79 }, "quux {:?}", true); + error!(target: "foo_events", { foo = 2, bar.baz = 79 }, "quux {:?}, {quux}", true, quux = false); + error!(target: "foo_events", { foo = 2, bar.baz = 78, }, "quux"); + let foo = 1; + error!(?foo); + error!(%foo); + error!(foo); +} + +#[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)] +#[test] +fn event_root() { + event!(parent: None, Level::DEBUG, foo = ?3, bar.baz = %2, quux = false); + event!( + parent: None, + Level::DEBUG, + foo = 3, + bar.baz = 2, + quux = false + ); + event!(parent: None, Level::DEBUG, foo = 3, bar.baz = 3,); + event!(parent: None, Level::DEBUG, "foo"); + event!(parent: None, Level::DEBUG, "foo: {}", 3); + event!(parent: None, Level::DEBUG, { foo = 3, bar.baz = 80 }, "quux"); + event!(parent: None, Level::DEBUG, { foo = 2, bar.baz = 79 }, "quux {:?}", true); + event!(parent: None, Level::DEBUG, { foo = 2, bar.baz = 79 }, "quux {:?}, {quux}", true, quux = false); + event!(parent: None, Level::DEBUG, { foo = ?2, bar.baz = %78 }, "quux"); + event!(target: "foo_events", parent: None, Level::DEBUG, foo = 3, bar.baz = 2, quux = false); + event!(target: "foo_events", parent: None, Level::DEBUG, foo = 3, bar.baz = 3,); + event!(target: "foo_events", parent: None, Level::DEBUG, "foo"); + event!(target: "foo_events", parent: None, Level::DEBUG, "foo: {}", 3); + event!(target: "foo_events", parent: None, Level::DEBUG, { foo = 3, bar.baz = 80 }, "quux"); + event!(target: "foo_events", parent: None, Level::DEBUG, { foo = 2, bar.baz = 79 }, "quux {:?}", true); + event!(target: "foo_events", parent: None, Level::DEBUG, { foo = 2, bar.baz = 79 }, "quux {:?}, {quux}", true, quux = false); + event!(target: "foo_events", parent: None, Level::DEBUG, { foo = 2, bar.baz = 78, }, "quux"); +} + +#[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)] +#[test] +fn trace_root() { + trace!(parent: None, foo = ?3, bar.baz = %2, quux = false); + trace!(parent: None, foo = 3, bar.baz = 2, quux = false); + trace!(parent: None, foo = 3, bar.baz = 3,); + trace!(parent: None, "foo"); + trace!(parent: None, "foo: {}", 3); + trace!(parent: None, { foo = 3, bar.baz = 80 }, "quux"); + trace!(parent: None, { foo = 2, bar.baz = 79 }, "quux {:?}", true); + trace!(parent: None, { foo = 2, bar.baz = 79 }, "quux {:?}, {quux}", true, quux = false); + trace!(parent: None, { foo = 2, bar.baz = 78 }, "quux"); + trace!(parent: None, { foo = ?2, bar.baz = %78 }, "quux"); + trace!(target: "foo_events", parent: None, foo = 3, bar.baz = 2, quux = false); + trace!(target: "foo_events", parent: None, foo = 3, bar.baz = 3,); + trace!(target: "foo_events", parent: None, "foo"); + trace!(target: "foo_events", parent: None, "foo: {}", 3); + trace!(target: "foo_events", parent: None, { foo = 3, bar.baz = 80 }, "quux"); + trace!(target: "foo_events", parent: None, { foo = 2, bar.baz = 79 }, "quux {:?}", true); + trace!(target: "foo_events", parent: None, { foo = 2, bar.baz = 79 }, "quux {:?}, {quux}", true, quux = false); + trace!(target: "foo_events", parent: None, { foo = 2, bar.baz = 78, }, "quux"); +} + +#[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)] +#[test] +fn debug_root() { + debug!(parent: None, foo = ?3, bar.baz = %2, quux = false); + debug!(parent: None, foo = 3, bar.baz = 2, quux = false); + debug!(parent: None, foo = 3, bar.baz = 3,); + debug!(parent: None, "foo"); + debug!(parent: None, "foo: {}", 3); + debug!(parent: None, { foo = 3, bar.baz = 80 }, "quux"); + debug!(parent: None, { foo = 2, bar.baz = 79 }, "quux {:?}", true); + debug!(parent: None, { foo = 2, bar.baz = 79 }, "quux {:?}, {quux}", true, quux = false); + debug!(parent: None, { foo = 2, bar.baz = 78 }, "quux"); + debug!(parent: None, { foo = ?2, bar.baz = %78 }, "quux"); + debug!(target: "foo_events", parent: None, foo = 3, bar.baz = 2, quux = false); + debug!(target: "foo_events", parent: None, foo = 3, bar.baz = 3,); + debug!(target: "foo_events", parent: None, "foo"); + debug!(target: "foo_events", parent: None, "foo: {}", 3); + debug!(target: "foo_events", parent: None, { foo = 3, bar.baz = 80 }, "quux"); + debug!(target: "foo_events", parent: None, { foo = 2, bar.baz = 79 }, "quux {:?}", true); + debug!(target: "foo_events", parent: None, { foo = 2, bar.baz = 79 }, "quux {:?}, {quux}", true, quux = false); + debug!(target: "foo_events", parent: None, { foo = 2, bar.baz = 78, }, "quux"); +} + +#[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)] +#[test] +fn info_root() { + info!(parent: None, foo = ?3, bar.baz = %2, quux = false); + info!(parent: None, foo = 3, bar.baz = 2, quux = false); + info!(parent: None, foo = 3, bar.baz = 3,); + info!(parent: None, "foo"); + info!(parent: None, "foo: {}", 3); + info!(parent: None, { foo = 3, bar.baz = 80 }, "quux"); + info!(parent: None, { foo = 2, bar.baz = 79 }, "quux {:?}", true); + info!(parent: None, { foo = 2, bar.baz = 79 }, "quux {:?}, {quux}", true, quux = false); + info!(parent: None, { foo = 2, bar.baz = 78 }, "quux"); + info!(parent: None, { foo = ?2, bar.baz = %78 }, "quux"); + info!(target: "foo_events", parent: None, foo = 3, bar.baz = 2, quux = false); + info!(target: "foo_events", parent: None, foo = 3, bar.baz = 3,); + info!(target: "foo_events", parent: None, "foo"); + info!(target: "foo_events", parent: None, "foo: {}", 3); + info!(target: "foo_events", parent: None, { foo = 3, bar.baz = 80 }, "quux"); + info!(target: "foo_events", parent: None, { foo = 2, bar.baz = 79 }, "quux {:?}", true); + info!(target: "foo_events", parent: None, { foo = 2, bar.baz = 79 }, "quux {:?}, {quux}", true, quux = false); + info!(target: "foo_events", parent: None, { foo = 2, bar.baz = 78, }, "quux"); +} + +#[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)] +#[test] +fn warn_root() { + warn!(parent: None, foo = ?3, bar.baz = %2, quux = false); + warn!(parent: None, foo = 3, bar.baz = 2, quux = false); + warn!(parent: None, foo = 3, bar.baz = 3,); + warn!(parent: None, "foo"); + warn!(parent: None, "foo: {}", 3); + warn!(parent: None, { foo = 3, bar.baz = 80 }, "quux"); + warn!(parent: None, { foo = 2, bar.baz = 79 }, "quux {:?}", true); + warn!(parent: None, { foo = 2, bar.baz = 79 }, "quux {:?}, {quux}", true, quux = false); + warn!(parent: None, { foo = 2, bar.baz = 78 }, "quux"); + warn!(parent: None, { foo = ?2, bar.baz = %78 }, "quux"); + warn!(target: "foo_events", parent: None, foo = 3, bar.baz = 2, quux = false); + warn!(target: "foo_events", parent: None, foo = 3, bar.baz = 3,); + warn!(target: "foo_events", parent: None, "foo"); + warn!(target: "foo_events", parent: None, "foo: {}", 3); + warn!(target: "foo_events", parent: None, { foo = 3, bar.baz = 80 }, "quux"); + warn!(target: "foo_events", parent: None, { foo = 2, bar.baz = 79 }, "quux {:?}", true); + warn!(target: "foo_events", parent: None, { foo = 2, bar.baz = 79 }, "quux {:?}, {quux}", true, quux = false); + warn!(target: "foo_events", parent: None, { foo = 2, bar.baz = 78, }, "quux"); +} + +#[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)] +#[test] +fn error_root() { + error!(parent: None, foo = ?3, bar.baz = %2, quux = false); + error!(parent: None, foo = 3, bar.baz = 2, quux = false); + error!(parent: None, foo = 3, bar.baz = 3,); + error!(parent: None, "foo"); + error!(parent: None, "foo: {}", 3); + error!(parent: None, { foo = 3, bar.baz = 80 }, "quux"); + error!(parent: None, { foo = 2, bar.baz = 79 }, "quux {:?}", true); + error!(parent: None, { foo = 2, bar.baz = 79 }, "quux {:?}, {quux}", true, quux = false); + error!(parent: None, { foo = 2, bar.baz = 78 }, "quux"); + error!(parent: None, { foo = ?2, bar.baz = %78 }, "quux"); + error!(target: "foo_events", parent: None, foo = 3, bar.baz = 2, quux = false); + error!(target: "foo_events", parent: None, foo = 3, bar.baz = 3,); + error!(target: "foo_events", parent: None, "foo"); + error!(target: "foo_events", parent: None, "foo: {}", 3); + error!(target: "foo_events", parent: None, { foo = 3, bar.baz = 80 }, "quux"); + error!(target: "foo_events", parent: None, { foo = 2, bar.baz = 79 }, "quux {:?}", true); + error!(target: "foo_events", parent: None, { foo = 2, bar.baz = 79 }, "quux {:?}, {quux}", true, quux = false); + error!(target: "foo_events", parent: None, { foo = 2, bar.baz = 78, }, "quux"); +} + +#[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)] +#[test] +fn event_with_parent() { + let p = span!(Level::TRACE, "im_a_parent!"); + event!(parent: &p, Level::DEBUG, foo = ?3, bar.baz = %2, quux = false); + event!(parent: &p, Level::DEBUG, foo = 3, bar.baz = 2, quux = false); + event!(parent: &p, Level::DEBUG, foo = 3, bar.baz = 3,); + event!(parent: &p, Level::DEBUG, "foo"); + event!(parent: &p, Level::DEBUG, "foo: {}", 3); + event!(parent: &p, Level::DEBUG, { foo = 3, bar.baz = 80 }, "quux"); + event!(parent: &p, Level::DEBUG, { foo = 2, bar.baz = 79 }, "quux {:?}", true); + event!(parent: &p, Level::DEBUG, { foo = 2, bar.baz = 79 }, "quux {:?}, {quux}", true, quux = false); + event!(parent: &p, Level::DEBUG, { foo = ?2, bar.baz = %78 }, "quux"); + event!(target: "foo_events", parent: &p, Level::DEBUG, foo = 3, bar.baz = 2, quux = false); + event!(target: "foo_events", parent: &p, Level::DEBUG, foo = 3, bar.baz = 3,); + event!(target: "foo_events", parent: &p, Level::DEBUG, "foo"); + event!(target: "foo_events", parent: &p, Level::DEBUG, "foo: {}", 3); + event!(target: "foo_events", parent: &p, Level::DEBUG, { foo = 3, bar.baz = 80 }, "quux"); + event!(target: "foo_events", parent: &p, Level::DEBUG, { foo = 2, bar.baz = 79 }, "quux {:?}", true); + event!(target: "foo_events", parent: &p, Level::DEBUG, { foo = 2, bar.baz = 79 }, "quux {:?}, {quux}", true, quux = false); + event!(target: "foo_events", parent: &p, Level::DEBUG, { foo = 2, bar.baz = 78, }, "quux"); +} + +#[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)] +#[test] +fn trace_with_parent() { + let p = span!(Level::TRACE, "im_a_parent!"); + trace!(parent: &p, foo = ?3, bar.baz = %2, quux = false); + trace!(parent: &p, foo = 3, bar.baz = 2, quux = false); + trace!(parent: &p, foo = 3, bar.baz = 3,); + trace!(parent: &p, "foo"); + trace!(parent: &p, "foo: {}", 3); + trace!(parent: &p, { foo = 3, bar.baz = 80 }, "quux"); + trace!(parent: &p, { foo = 2, bar.baz = 79 }, "quux {:?}", true); + trace!(parent: &p, { foo = 2, bar.baz = 79 }, "quux {:?}, {quux}", true, quux = false); + trace!(parent: &p, { foo = 2, bar.baz = 78 }, "quux"); + trace!(parent: &p, { foo = ?2, bar.baz = %78 }, "quux"); + trace!(target: "foo_events", parent: &p, foo = 3, bar.baz = 2, quux = false); + trace!(target: "foo_events", parent: &p, foo = 3, bar.baz = 3,); + trace!(target: "foo_events", parent: &p, "foo"); + trace!(target: "foo_events", parent: &p, "foo: {}", 3); + trace!(target: "foo_events", parent: &p, { foo = 3, bar.baz = 80 }, "quux"); + trace!(target: "foo_events", parent: &p, { foo = 2, bar.baz = 79 }, "quux {:?}", true); + trace!(target: "foo_events", parent: &p, { foo = 2, bar.baz = 79 }, "quux {:?}, {quux}", true, quux = false); + trace!(target: "foo_events", parent: &p, { foo = 2, bar.baz = 78, }, "quux"); +} + +#[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)] +#[test] +fn debug_with_parent() { + let p = span!(Level::TRACE, "im_a_parent!"); + debug!(parent: &p, foo = ?3, bar.baz = %2, quux = false); + debug!(parent: &p, foo = 3, bar.baz = 2, quux = false); + debug!(parent: &p, foo = 3, bar.baz = 3,); + debug!(parent: &p, "foo"); + debug!(parent: &p, "foo: {}", 3); + debug!(parent: &p, { foo = 3, bar.baz = 80 }, "quux"); + debug!(parent: &p, { foo = 2, bar.baz = 79 }, "quux {:?}", true); + debug!(parent: &p, { foo = 2, bar.baz = 79 }, "quux {:?}, {quux}", true, quux = false); + debug!(parent: &p, { foo = 2, bar.baz = 78 }, "quux"); + debug!(parent: &p, { foo = ?2, bar.baz = %78 }, "quux"); + debug!(target: "foo_events", parent: &p, foo = 3, bar.baz = 2, quux = false); + debug!(target: "foo_events", parent: &p, foo = 3, bar.baz = 3,); + debug!(target: "foo_events", parent: &p, "foo"); + debug!(target: "foo_events", parent: &p, "foo: {}", 3); + debug!(target: "foo_events", parent: &p, { foo = 3, bar.baz = 80 }, "quux"); + debug!(target: "foo_events", parent: &p, { foo = 2, bar.baz = 79 }, "quux {:?}", true); + debug!(target: "foo_events", parent: &p, { foo = 2, bar.baz = 79 }, "quux {:?}, {quux}", true, quux = false); + debug!(target: "foo_events", parent: &p, { foo = 2, bar.baz = 78, }, "quux"); +} + +#[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)] +#[test] +fn info_with_parent() { + let p = span!(Level::TRACE, "im_a_parent!"); + info!(parent: &p, foo = ?3, bar.baz = %2, quux = false); + info!(parent: &p, foo = 3, bar.baz = 2, quux = false); + info!(parent: &p, foo = 3, bar.baz = 3,); + info!(parent: &p, "foo"); + info!(parent: &p, "foo: {}", 3); + info!(parent: &p, { foo = 3, bar.baz = 80 }, "quux"); + info!(parent: &p, { foo = 2, bar.baz = 79 }, "quux {:?}", true); + info!(parent: &p, { foo = 2, bar.baz = 79 }, "quux {:?}, {quux}", true, quux = false); + info!(parent: &p, { foo = 2, bar.baz = 78 }, "quux"); + info!(parent: &p, { foo = ?2, bar.baz = %78 }, "quux"); + info!(target: "foo_events", parent: &p, foo = 3, bar.baz = 2, quux = false); + info!(target: "foo_events", parent: &p, foo = 3, bar.baz = 3,); + info!(target: "foo_events", parent: &p, "foo"); + info!(target: "foo_events", parent: &p, "foo: {}", 3); + info!(target: "foo_events", parent: &p, { foo = 3, bar.baz = 80 }, "quux"); + info!(target: "foo_events", parent: &p, { foo = 2, bar.baz = 79 }, "quux {:?}", true); + info!(target: "foo_events", parent: &p, { foo = 2, bar.baz = 79 }, "quux {:?}, {quux}", true, quux = false); + info!(target: "foo_events", parent: &p, { foo = 2, bar.baz = 78, }, "quux"); +} + +#[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)] +#[test] +fn warn_with_parent() { + let p = span!(Level::TRACE, "im_a_parent!"); + warn!(parent: &p, foo = ?3, bar.baz = %2, quux = false); + warn!(parent: &p, foo = 3, bar.baz = 2, quux = false); + warn!(parent: &p, foo = 3, bar.baz = 3,); + warn!(parent: &p, "foo"); + warn!(parent: &p, "foo: {}", 3); + warn!(parent: &p, { foo = 3, bar.baz = 80 }, "quux"); + warn!(parent: &p, { foo = 2, bar.baz = 79 }, "quux {:?}", true); + warn!(parent: &p, { foo = 2, bar.baz = 79 }, "quux {:?}, {quux}", true, quux = false); + warn!(parent: &p, { foo = 2, bar.baz = 78 }, "quux"); + warn!(parent: &p, { foo = ?2, bar.baz = %78 }, "quux"); + warn!(target: "foo_events", parent: &p, foo = 3, bar.baz = 2, quux = false); + warn!(target: "foo_events", parent: &p, foo = 3, bar.baz = 3,); + warn!(target: "foo_events", parent: &p, "foo"); + warn!(target: "foo_events", parent: &p, "foo: {}", 3); + warn!(target: "foo_events", parent: &p, { foo = 3, bar.baz = 80 }, "quux"); + warn!(target: "foo_events", parent: &p, { foo = 2, bar.baz = 79 }, "quux {:?}", true); + warn!(target: "foo_events", parent: &p, { foo = 2, bar.baz = 79 }, "quux {:?}, {quux}", true, quux = false); + warn!(target: "foo_events", parent: &p, { foo = 2, bar.baz = 78, }, "quux"); +} + +#[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)] +#[test] +fn error_with_parent() { + let p = span!(Level::TRACE, "im_a_parent!"); + error!(parent: &p, foo = ?3, bar.baz = %2, quux = false); + error!(parent: &p, foo = 3, bar.baz = 2, quux = false); + error!(parent: &p, foo = 3, bar.baz = 3,); + error!(parent: &p, "foo"); + error!(parent: &p, "foo: {}", 3); + error!(parent: &p, { foo = 3, bar.baz = 80 }, "quux"); + error!(parent: &p, { foo = 2, bar.baz = 79 }, "quux {:?}", true); + error!(parent: &p, { foo = 2, bar.baz = 79 }, "quux {:?}, {quux}", true, quux = false); + error!(parent: &p, { foo = 2, bar.baz = 78 }, "quux"); + error!(parent: &p, { foo = ?2, bar.baz = %78 }, "quux"); + error!(target: "foo_events", parent: &p, foo = 3, bar.baz = 2, quux = false); + error!(target: "foo_events", parent: &p, foo = 3, bar.baz = 3,); + error!(target: "foo_events", parent: &p, "foo"); + error!(target: "foo_events", parent: &p, "foo: {}", 3); + error!(target: "foo_events", parent: &p, { foo = 3, bar.baz = 80 }, "quux"); + error!(target: "foo_events", parent: &p, { foo = 2, bar.baz = 79 }, "quux {:?}", true); + error!(target: "foo_events", parent: &p, { foo = 2, bar.baz = 79 }, "quux {:?}, {quux}", true, quux = false); + error!(target: "foo_events", parent: &p, { foo = 2, bar.baz = 78, }, "quux"); +} + +#[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)] +#[test] +fn field_shorthand_only() { + #[derive(Debug)] + struct Position { + x: f32, + y: f32, + } + let pos = Position { + x: 3.234, + y: -1.223, + }; + + trace!(?pos.x, ?pos.y); + debug!(?pos.x, ?pos.y); + info!(?pos.x, ?pos.y); + warn!(?pos.x, ?pos.y); + error!(?pos.x, ?pos.y); + event!(Level::TRACE, ?pos.x, ?pos.y); +} + +#[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)] +#[test] +fn borrow_val_events() { + // Reproduces https://github.com/tokio-rs/tracing/issues/954 + let mut foo = (String::new(), String::new()); + let zero = &mut foo.0; + trace!(one = ?foo.1); + debug!(one = ?foo.1); + info!(one = ?foo.1); + warn!(one = ?foo.1); + error!(one = ?foo.1); + zero.push_str("hello world"); +} + +#[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)] +#[test] +fn borrow_val_spans() { + // Reproduces https://github.com/tokio-rs/tracing/issues/954 + let mut foo = (String::new(), String::new()); + let zero = &mut foo.0; + let _span = trace_span!("span", one = ?foo.1); + let _span = debug_span!("span", one = ?foo.1); + let _span = info_span!("span", one = ?foo.1); + let _span = warn_span!("span", one = ?foo.1); + let _span = error_span!("span", one = ?foo.1); + zero.push_str("hello world"); +} + +#[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)] +#[test] +fn callsite_macro_api() { + // This test should catch any inadvertent breaking changes + // caused by changes to the macro. + let _callsite = callsite! { + name: "test callsite", + kind: tracing::metadata::Kind::EVENT, + target: "test target", + level: tracing::Level::TRACE, + fields: foo, bar, + }; + let _callsite = callsite! { + name: "test callsite", + kind: tracing::metadata::Kind::SPAN, + level: tracing::Level::TRACE, + fields: foo, + }; + let _callsite = callsite! { + name: "test callsite", + kind: tracing::metadata::Kind::SPAN, + fields: foo, + }; +} diff --git a/third_party/rust/tracing/tests/max_level_hint.rs b/third_party/rust/tracing/tests/max_level_hint.rs new file mode 100644 index 0000000000..49f14d55fe --- /dev/null +++ b/third_party/rust/tracing/tests/max_level_hint.rs @@ -0,0 +1,39 @@ +mod support; + +use self::support::*; +use tracing::Level; + +#[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)] +#[test] +fn max_level_hints() { + // This test asserts that when a subscriber provides us with the global + // maximum level that it will enable (by implementing the + // `Subscriber::max_level_hint` method), we will never call + // `Subscriber::enabled` for events above that maximum level. + // + // In this case, we test that by making the `enabled` method assert that no + // `Metadata` for spans or events at the `TRACE` or `DEBUG` levels. + let (subscriber, handle) = subscriber::mock() + .with_max_level_hint(Level::INFO) + .with_filter(|meta| { + assert!( + dbg!(meta).level() <= &Level::INFO, + "a TRACE or DEBUG event was dynamically filtered: " + ); + true + }) + .event(event::mock().at_level(Level::INFO)) + .event(event::mock().at_level(Level::WARN)) + .event(event::mock().at_level(Level::ERROR)) + .done() + .run_with_handle(); + + tracing::subscriber::set_global_default(subscriber).unwrap(); + + tracing::info!("doing a thing that you might care about"); + tracing::debug!("charging turboencabulator with interocitor"); + tracing::warn!("extremely serious warning, pay attention"); + tracing::trace!("interocitor charge level is 10%"); + tracing::error!("everything is on fire"); + handle.assert_finished(); +} diff --git a/third_party/rust/tracing/tests/multiple_max_level_hints.rs b/third_party/rust/tracing/tests/multiple_max_level_hints.rs new file mode 100644 index 0000000000..b2be6351cf --- /dev/null +++ b/third_party/rust/tracing/tests/multiple_max_level_hints.rs @@ -0,0 +1,70 @@ +#![cfg(feature = "std")] +mod support; + +use self::support::*; +use tracing::Level; + +#[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)] +#[test] +fn multiple_max_level_hints() { + // This test ensures that when multiple subscribers are active, their max + // level hints are handled correctly. The global max level should be the + // maximum of the level filters returned by the two `Subscriber`'s + // `max_level_hint` method. + // + // In this test, we create a subscriber whose max level is `INFO`, and + // another whose max level is `DEBUG`. We then add an assertion to both of + // those subscribers' `enabled` method that no metadata for `TRACE` spans or + // events are filtered, since they are disabled by the global max filter. + + fn do_events() { + tracing::info!("doing a thing that you might care about"); + tracing::debug!("charging turboencabulator with interocitor"); + tracing::warn!("extremely serious warning, pay attention"); + tracing::trace!("interocitor charge level is 10%"); + tracing::error!("everything is on fire"); + } + + let (subscriber1, handle1) = subscriber::mock() + .named("subscriber1") + .with_max_level_hint(Level::INFO) + .with_filter(|meta| { + let level = dbg!(meta.level()); + assert!( + level <= &Level::DEBUG, + "a TRACE event was dynamically filtered by subscriber1" + ); + level <= &Level::INFO + }) + .event(event::mock().at_level(Level::INFO)) + .event(event::mock().at_level(Level::WARN)) + .event(event::mock().at_level(Level::ERROR)) + .done() + .run_with_handle(); + let (subscriber2, handle2) = subscriber::mock() + .named("subscriber2") + .with_max_level_hint(Level::DEBUG) + .with_filter(|meta| { + let level = dbg!(meta.level()); + assert!( + level <= &Level::DEBUG, + "a TRACE event was dynamically filtered by subscriber2" + ); + level <= &Level::DEBUG + }) + .event(event::mock().at_level(Level::INFO)) + .event(event::mock().at_level(Level::DEBUG)) + .event(event::mock().at_level(Level::WARN)) + .event(event::mock().at_level(Level::ERROR)) + .done() + .run_with_handle(); + + let dispatch1 = tracing::Dispatch::new(subscriber1); + + tracing::dispatcher::with_default(&dispatch1, do_events); + handle1.assert_finished(); + + let dispatch2 = tracing::Dispatch::new(subscriber2); + tracing::dispatcher::with_default(&dispatch2, do_events); + handle2.assert_finished(); +} diff --git a/third_party/rust/tracing/tests/span.rs b/third_party/rust/tracing/tests/span.rs new file mode 100644 index 0000000000..79914950c2 --- /dev/null +++ b/third_party/rust/tracing/tests/span.rs @@ -0,0 +1,767 @@ +// These tests require the thread-local scoped dispatcher, which only works when +// we have a standard library. The behaviour being tested should be the same +// with the standard lib disabled. +#![cfg(feature = "std")] + +#[macro_use] +extern crate tracing; +mod support; + +use self::support::*; +use std::thread; +use tracing::{ + field::{debug, display}, + subscriber::with_default, + Level, Span, +}; + +#[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)] +#[test] +fn handles_to_the_same_span_are_equal() { + // Create a mock subscriber that will return `true` on calls to + // `Subscriber::enabled`, so that the spans will be constructed. We + // won't enter any spans in this test, so the subscriber won't actually + // expect to see any spans. + with_default(subscriber::mock().run(), || { + let foo1 = span!(Level::TRACE, "foo"); + let foo2 = foo1.clone(); + // Two handles that point to the same span are equal. + assert_eq!(foo1, foo2); + }); +} + +#[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)] +#[test] +fn handles_to_different_spans_are_not_equal() { + with_default(subscriber::mock().run(), || { + // Even though these spans have the same name and fields, they will have + // differing metadata, since they were created on different lines. + let foo1 = span!(Level::TRACE, "foo", bar = 1u64, baz = false); + let foo2 = span!(Level::TRACE, "foo", bar = 1u64, baz = false); + + assert_ne!(foo1, foo2); + }); +} + +#[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)] +#[test] +fn handles_to_different_spans_with_the_same_metadata_are_not_equal() { + // Every time time this function is called, it will return a _new + // instance_ of a span with the same metadata, name, and fields. + fn make_span() -> Span { + span!(Level::TRACE, "foo", bar = 1u64, baz = false) + } + + with_default(subscriber::mock().run(), || { + let foo1 = make_span(); + let foo2 = make_span(); + + assert_ne!(foo1, foo2); + // assert_ne!(foo1.data(), foo2.data()); + }); +} + +#[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)] +#[test] +fn spans_always_go_to_the_subscriber_that_tagged_them() { + let subscriber1 = subscriber::mock() + .enter(span::mock().named("foo")) + .exit(span::mock().named("foo")) + .enter(span::mock().named("foo")) + .exit(span::mock().named("foo")) + .drop_span(span::mock().named("foo")) + .done() + .run(); + let subscriber2 = subscriber::mock().run(); + + let foo = with_default(subscriber1, || { + let foo = span!(Level::TRACE, "foo"); + foo.in_scope(|| {}); + foo + }); + // Even though we enter subscriber 2's context, the subscriber that + // tagged the span should see the enter/exit. + with_default(subscriber2, move || foo.in_scope(|| {})); +} + +// This gets exempt from testing in wasm because of: `thread::spawn` which is +// not yet possible to do in WASM. There is work going on see: +// <https://rustwasm.github.io/2018/10/24/multithreading-rust-and-wasm.html> +// +// But for now since it's not possible we don't need to test for it :) +#[test] +fn spans_always_go_to_the_subscriber_that_tagged_them_even_across_threads() { + let subscriber1 = subscriber::mock() + .enter(span::mock().named("foo")) + .exit(span::mock().named("foo")) + .enter(span::mock().named("foo")) + .exit(span::mock().named("foo")) + .drop_span(span::mock().named("foo")) + .done() + .run(); + let foo = with_default(subscriber1, || { + let foo = span!(Level::TRACE, "foo"); + foo.in_scope(|| {}); + foo + }); + + // Even though we enter subscriber 2's context, the subscriber that + // tagged the span should see the enter/exit. + thread::spawn(move || { + with_default(subscriber::mock().run(), || { + foo.in_scope(|| {}); + }) + }) + .join() + .unwrap(); +} + +#[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)] +#[test] +fn dropping_a_span_calls_drop_span() { + let (subscriber, handle) = subscriber::mock() + .enter(span::mock().named("foo")) + .exit(span::mock().named("foo")) + .drop_span(span::mock().named("foo")) + .done() + .run_with_handle(); + with_default(subscriber, || { + let span = span!(Level::TRACE, "foo"); + span.in_scope(|| {}); + drop(span); + }); + + handle.assert_finished(); +} + +#[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)] +#[test] +fn span_closes_after_event() { + let (subscriber, handle) = subscriber::mock() + .enter(span::mock().named("foo")) + .event(event::mock()) + .exit(span::mock().named("foo")) + .drop_span(span::mock().named("foo")) + .done() + .run_with_handle(); + with_default(subscriber, || { + span!(Level::TRACE, "foo").in_scope(|| { + event!(Level::DEBUG, {}, "my event!"); + }); + }); + + handle.assert_finished(); +} + +#[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)] +#[test] +fn new_span_after_event() { + let (subscriber, handle) = subscriber::mock() + .enter(span::mock().named("foo")) + .event(event::mock()) + .exit(span::mock().named("foo")) + .drop_span(span::mock().named("foo")) + .enter(span::mock().named("bar")) + .exit(span::mock().named("bar")) + .drop_span(span::mock().named("bar")) + .done() + .run_with_handle(); + with_default(subscriber, || { + span!(Level::TRACE, "foo").in_scope(|| { + event!(Level::DEBUG, {}, "my event!"); + }); + span!(Level::TRACE, "bar").in_scope(|| {}); + }); + + handle.assert_finished(); +} + +#[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)] +#[test] +fn event_outside_of_span() { + let (subscriber, handle) = subscriber::mock() + .event(event::mock()) + .enter(span::mock().named("foo")) + .exit(span::mock().named("foo")) + .drop_span(span::mock().named("foo")) + .done() + .run_with_handle(); + with_default(subscriber, || { + debug!("my event!"); + span!(Level::TRACE, "foo").in_scope(|| {}); + }); + + handle.assert_finished(); +} + +#[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)] +#[test] +fn cloning_a_span_calls_clone_span() { + let (subscriber, handle) = subscriber::mock() + .clone_span(span::mock().named("foo")) + .run_with_handle(); + with_default(subscriber, || { + let span = span!(Level::TRACE, "foo"); + // Allow the "redundant" `.clone` since it is used to call into the `.clone_span` hook. + #[allow(clippy::redundant_clone)] + let _span2 = span.clone(); + }); + + handle.assert_finished(); +} + +#[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)] +#[test] +fn drop_span_when_exiting_dispatchers_context() { + let (subscriber, handle) = subscriber::mock() + .clone_span(span::mock().named("foo")) + .drop_span(span::mock().named("foo")) + .drop_span(span::mock().named("foo")) + .run_with_handle(); + with_default(subscriber, || { + let span = span!(Level::TRACE, "foo"); + let _span2 = span.clone(); + drop(span); + }); + + handle.assert_finished(); +} + +#[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)] +#[test] +fn clone_and_drop_span_always_go_to_the_subscriber_that_tagged_the_span() { + let (subscriber1, handle1) = subscriber::mock() + .enter(span::mock().named("foo")) + .exit(span::mock().named("foo")) + .clone_span(span::mock().named("foo")) + .enter(span::mock().named("foo")) + .exit(span::mock().named("foo")) + .drop_span(span::mock().named("foo")) + .drop_span(span::mock().named("foo")) + .run_with_handle(); + let subscriber2 = subscriber::mock().done().run(); + + let foo = with_default(subscriber1, || { + let foo = span!(Level::TRACE, "foo"); + foo.in_scope(|| {}); + foo + }); + // Even though we enter subscriber 2's context, the subscriber that + // tagged the span should see the enter/exit. + with_default(subscriber2, move || { + let foo2 = foo.clone(); + foo.in_scope(|| {}); + drop(foo); + drop(foo2); + }); + + handle1.assert_finished(); +} + +#[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)] +#[test] +fn span_closes_when_exited() { + let (subscriber, handle) = subscriber::mock() + .enter(span::mock().named("foo")) + .exit(span::mock().named("foo")) + .drop_span(span::mock().named("foo")) + .done() + .run_with_handle(); + with_default(subscriber, || { + let foo = span!(Level::TRACE, "foo"); + + foo.in_scope(|| {}); + + drop(foo); + }); + + handle.assert_finished(); +} + +#[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)] +#[test] +fn enter() { + let (subscriber, handle) = subscriber::mock() + .enter(span::mock().named("foo")) + .event(event::mock()) + .exit(span::mock().named("foo")) + .drop_span(span::mock().named("foo")) + .done() + .run_with_handle(); + with_default(subscriber, || { + let foo = span!(Level::TRACE, "foo"); + let _enter = foo.enter(); + debug!("dropping guard..."); + }); + + handle.assert_finished(); +} + +#[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)] +#[test] +fn moved_field() { + let (subscriber, handle) = subscriber::mock() + .new_span( + span::mock().named("foo").with_field( + field::mock("bar") + .with_value(&display("hello from my span")) + .only(), + ), + ) + .enter(span::mock().named("foo")) + .exit(span::mock().named("foo")) + .drop_span(span::mock().named("foo")) + .done() + .run_with_handle(); + with_default(subscriber, || { + let from = "my span"; + let span = span!( + Level::TRACE, + "foo", + bar = display(format!("hello from {}", from)) + ); + span.in_scope(|| {}); + }); + + handle.assert_finished(); +} + +#[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)] +#[test] +fn dotted_field_name() { + let (subscriber, handle) = subscriber::mock() + .new_span( + span::mock() + .named("foo") + .with_field(field::mock("fields.bar").with_value(&true).only()), + ) + .done() + .run_with_handle(); + with_default(subscriber, || { + span!(Level::TRACE, "foo", fields.bar = true); + }); + + handle.assert_finished(); +} + +#[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)] +#[test] +fn borrowed_field() { + let (subscriber, handle) = subscriber::mock() + .new_span( + span::mock().named("foo").with_field( + field::mock("bar") + .with_value(&display("hello from my span")) + .only(), + ), + ) + .enter(span::mock().named("foo")) + .exit(span::mock().named("foo")) + .drop_span(span::mock().named("foo")) + .done() + .run_with_handle(); + + with_default(subscriber, || { + let from = "my span"; + let mut message = format!("hello from {}", from); + let span = span!(Level::TRACE, "foo", bar = display(&message)); + span.in_scope(|| { + message.insert_str(10, " inside"); + }); + }); + + handle.assert_finished(); +} + +#[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)] +#[test] +// If emitting log instrumentation, this gets moved anyway, breaking the test. +#[cfg(not(feature = "log"))] +fn move_field_out_of_struct() { + use tracing::field::debug; + + #[derive(Debug)] + struct Position { + x: f32, + y: f32, + } + + let pos = Position { + x: 3.234, + y: -1.223, + }; + let (subscriber, handle) = subscriber::mock() + .new_span( + span::mock().named("foo").with_field( + field::mock("x") + .with_value(&debug(3.234)) + .and(field::mock("y").with_value(&debug(-1.223))) + .only(), + ), + ) + .new_span( + span::mock() + .named("bar") + .with_field(field::mock("position").with_value(&debug(&pos)).only()), + ) + .run_with_handle(); + + with_default(subscriber, || { + let pos = Position { + x: 3.234, + y: -1.223, + }; + let foo = span!(Level::TRACE, "foo", x = debug(pos.x), y = debug(pos.y)); + let bar = span!(Level::TRACE, "bar", position = debug(pos)); + foo.in_scope(|| {}); + bar.in_scope(|| {}); + }); + + handle.assert_finished(); +} + +// TODO(#1138): determine a new syntax for uninitialized span fields, and +// re-enable these. +/* +#[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)] +#[test] +fn add_field_after_new_span() { + let (subscriber, handle) = subscriber::mock() + .new_span( + span::mock() + .named("foo") + .with_field(field::mock("bar").with_value(&5) + .and(field::mock("baz").with_value).only()), + ) + .record( + span::mock().named("foo"), + field::mock("baz").with_value(&true).only(), + ) + .enter(span::mock().named("foo")) + .exit(span::mock().named("foo")) + .drop_span(span::mock().named("foo")) + .done() + .run_with_handle(); + + with_default(subscriber, || { + let span = span!(Level::TRACE, "foo", bar = 5, baz = false); + span.record("baz", &true); + span.in_scope(|| {}) + }); + + handle.assert_finished(); +} + +#[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)] +#[test] +fn add_fields_only_after_new_span() { + let (subscriber, handle) = subscriber::mock() + .new_span(span::mock().named("foo")) + .record( + span::mock().named("foo"), + field::mock("bar").with_value(&5).only(), + ) + .record( + span::mock().named("foo"), + field::mock("baz").with_value(&true).only(), + ) + .enter(span::mock().named("foo")) + .exit(span::mock().named("foo")) + .drop_span(span::mock().named("foo")) + .done() + .run_with_handle(); + + with_default(subscriber, || { + let span = span!(Level::TRACE, "foo", bar = _, baz = _); + span.record("bar", &5); + span.record("baz", &true); + span.in_scope(|| {}) + }); + + handle.assert_finished(); +} +*/ + +#[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)] +#[test] +fn record_new_value_for_field() { + let (subscriber, handle) = subscriber::mock() + .new_span( + span::mock().named("foo").with_field( + field::mock("bar") + .with_value(&5) + .and(field::mock("baz").with_value(&false)) + .only(), + ), + ) + .record( + span::mock().named("foo"), + field::mock("baz").with_value(&true).only(), + ) + .enter(span::mock().named("foo")) + .exit(span::mock().named("foo")) + .drop_span(span::mock().named("foo")) + .done() + .run_with_handle(); + + with_default(subscriber, || { + let span = span!(Level::TRACE, "foo", bar = 5, baz = false); + span.record("baz", &true); + span.in_scope(|| {}) + }); + + handle.assert_finished(); +} + +#[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)] +#[test] +fn record_new_values_for_fields() { + let (subscriber, handle) = subscriber::mock() + .new_span( + span::mock().named("foo").with_field( + field::mock("bar") + .with_value(&4) + .and(field::mock("baz").with_value(&false)) + .only(), + ), + ) + .record( + span::mock().named("foo"), + field::mock("bar").with_value(&5).only(), + ) + .record( + span::mock().named("foo"), + field::mock("baz").with_value(&true).only(), + ) + .enter(span::mock().named("foo")) + .exit(span::mock().named("foo")) + .drop_span(span::mock().named("foo")) + .done() + .run_with_handle(); + + with_default(subscriber, || { + let span = span!(Level::TRACE, "foo", bar = 4, baz = false); + span.record("bar", &5); + span.record("baz", &true); + span.in_scope(|| {}) + }); + + handle.assert_finished(); +} + +#[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)] +#[test] +fn new_span_with_target_and_log_level() { + let (subscriber, handle) = subscriber::mock() + .new_span( + span::mock() + .named("foo") + .with_target("app_span") + .at_level(Level::DEBUG), + ) + .done() + .run_with_handle(); + + with_default(subscriber, || { + span!(target: "app_span", Level::DEBUG, "foo"); + }); + + handle.assert_finished(); +} + +#[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)] +#[test] +fn explicit_root_span_is_root() { + let (subscriber, handle) = subscriber::mock() + .new_span(span::mock().named("foo").with_explicit_parent(None)) + .done() + .run_with_handle(); + + with_default(subscriber, || { + span!(parent: None, Level::TRACE, "foo"); + }); + + handle.assert_finished(); +} + +#[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)] +#[test] +fn explicit_root_span_is_root_regardless_of_ctx() { + let (subscriber, handle) = subscriber::mock() + .new_span(span::mock().named("foo")) + .enter(span::mock().named("foo")) + .new_span(span::mock().named("bar").with_explicit_parent(None)) + .exit(span::mock().named("foo")) + .done() + .run_with_handle(); + + with_default(subscriber, || { + span!(Level::TRACE, "foo").in_scope(|| { + span!(parent: None, Level::TRACE, "bar"); + }) + }); + + handle.assert_finished(); +} + +#[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)] +#[test] +fn explicit_child() { + let (subscriber, handle) = subscriber::mock() + .new_span(span::mock().named("foo")) + .new_span(span::mock().named("bar").with_explicit_parent(Some("foo"))) + .done() + .run_with_handle(); + + with_default(subscriber, || { + let foo = span!(Level::TRACE, "foo"); + span!(parent: foo.id(), Level::TRACE, "bar"); + }); + + handle.assert_finished(); +} + +#[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)] +#[test] +fn explicit_child_at_levels() { + let (subscriber, handle) = subscriber::mock() + .new_span(span::mock().named("foo")) + .new_span(span::mock().named("a").with_explicit_parent(Some("foo"))) + .new_span(span::mock().named("b").with_explicit_parent(Some("foo"))) + .new_span(span::mock().named("c").with_explicit_parent(Some("foo"))) + .new_span(span::mock().named("d").with_explicit_parent(Some("foo"))) + .new_span(span::mock().named("e").with_explicit_parent(Some("foo"))) + .done() + .run_with_handle(); + + with_default(subscriber, || { + let foo = span!(Level::TRACE, "foo"); + trace_span!(parent: foo.id(), "a"); + debug_span!(parent: foo.id(), "b"); + info_span!(parent: foo.id(), "c"); + warn_span!(parent: foo.id(), "d"); + error_span!(parent: foo.id(), "e"); + }); + + handle.assert_finished(); +} + +#[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)] +#[test] +fn explicit_child_regardless_of_ctx() { + let (subscriber, handle) = subscriber::mock() + .new_span(span::mock().named("foo")) + .new_span(span::mock().named("bar")) + .enter(span::mock().named("bar")) + .new_span(span::mock().named("baz").with_explicit_parent(Some("foo"))) + .exit(span::mock().named("bar")) + .done() + .run_with_handle(); + + with_default(subscriber, || { + let foo = span!(Level::TRACE, "foo"); + span!(Level::TRACE, "bar").in_scope(|| span!(parent: foo.id(), Level::TRACE, "baz")) + }); + + handle.assert_finished(); +} + +#[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)] +#[test] +fn contextual_root() { + let (subscriber, handle) = subscriber::mock() + .new_span(span::mock().named("foo").with_contextual_parent(None)) + .done() + .run_with_handle(); + + with_default(subscriber, || { + span!(Level::TRACE, "foo"); + }); + + handle.assert_finished(); +} + +#[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)] +#[test] +fn contextual_child() { + let (subscriber, handle) = subscriber::mock() + .new_span(span::mock().named("foo")) + .enter(span::mock().named("foo")) + .new_span( + span::mock() + .named("bar") + .with_contextual_parent(Some("foo")), + ) + .exit(span::mock().named("foo")) + .done() + .run_with_handle(); + + with_default(subscriber, || { + span!(Level::TRACE, "foo").in_scope(|| { + span!(Level::TRACE, "bar"); + }) + }); + + handle.assert_finished(); +} + +#[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)] +#[test] +fn display_shorthand() { + let (subscriber, handle) = subscriber::mock() + .new_span( + span::mock().named("my_span").with_field( + field::mock("my_field") + .with_value(&display("hello world")) + .only(), + ), + ) + .done() + .run_with_handle(); + with_default(subscriber, || { + span!(Level::TRACE, "my_span", my_field = %"hello world"); + }); + + handle.assert_finished(); +} + +#[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)] +#[test] +fn debug_shorthand() { + let (subscriber, handle) = subscriber::mock() + .new_span( + span::mock().named("my_span").with_field( + field::mock("my_field") + .with_value(&debug("hello world")) + .only(), + ), + ) + .done() + .run_with_handle(); + with_default(subscriber, || { + span!(Level::TRACE, "my_span", my_field = ?"hello world"); + }); + + handle.assert_finished(); +} + +#[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)] +#[test] +fn both_shorthands() { + let (subscriber, handle) = subscriber::mock() + .new_span( + span::mock().named("my_span").with_field( + field::mock("display_field") + .with_value(&display("hello world")) + .and(field::mock("debug_field").with_value(&debug("hello world"))) + .only(), + ), + ) + .done() + .run_with_handle(); + with_default(subscriber, || { + span!(Level::TRACE, "my_span", display_field = %"hello world", debug_field = ?"hello world"); + }); + + handle.assert_finished(); +} diff --git a/third_party/rust/tracing/tests/subscriber.rs b/third_party/rust/tracing/tests/subscriber.rs new file mode 100644 index 0000000000..2a810c9111 --- /dev/null +++ b/third_party/rust/tracing/tests/subscriber.rs @@ -0,0 +1,57 @@ +// These tests require the thread-local scoped dispatcher, which only works when +// we have a standard library. The behaviour being tested should be the same +// with the standard lib disabled. +// +// The alternative would be for each of these tests to be defined in a separate +// file, which is :( +#![cfg(feature = "std")] + +#[macro_use] +extern crate tracing; +use tracing::{ + span, + subscriber::{with_default, Interest, Subscriber}, + Event, Level, Metadata, +}; + +#[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)] +#[test] +fn event_macros_dont_infinite_loop() { + // This test ensures that an event macro within a subscriber + // won't cause an infinite loop of events. + struct TestSubscriber; + impl Subscriber for TestSubscriber { + fn register_callsite(&self, _: &Metadata<'_>) -> Interest { + // Always return sometimes so that `enabled` will be called + // (which can loop). + Interest::sometimes() + } + + fn enabled(&self, meta: &Metadata<'_>) -> bool { + assert!(meta.fields().iter().any(|f| f.name() == "foo")); + event!(Level::TRACE, bar = false); + true + } + + fn new_span(&self, _: &span::Attributes<'_>) -> span::Id { + span::Id::from_u64(0xAAAA) + } + + fn record(&self, _: &span::Id, _: &span::Record<'_>) {} + + fn record_follows_from(&self, _: &span::Id, _: &span::Id) {} + + fn event(&self, event: &Event<'_>) { + assert!(event.metadata().fields().iter().any(|f| f.name() == "foo")); + event!(Level::TRACE, baz = false); + } + + fn enter(&self, _: &span::Id) {} + + fn exit(&self, _: &span::Id) {} + } + + with_default(TestSubscriber, || { + event!(Level::TRACE, foo = false); + }) +} diff --git a/third_party/rust/tracing/tests/support/event.rs b/third_party/rust/tracing/tests/support/event.rs new file mode 100644 index 0000000000..7033d8a134 --- /dev/null +++ b/third_party/rust/tracing/tests/support/event.rs @@ -0,0 +1,99 @@ +#![allow(missing_docs)] +use super::{field, metadata, Parent}; + +use std::fmt; + +/// A mock event. +/// +/// This is intended for use with the mock subscriber API in the +/// `subscriber` module. +#[derive(Debug, Default, Eq, PartialEq)] +pub struct MockEvent { + pub fields: Option<field::Expect>, + pub(in crate::support) parent: Option<Parent>, + metadata: metadata::Expect, +} + +pub fn mock() -> MockEvent { + MockEvent { + ..Default::default() + } +} + +impl MockEvent { + pub fn named<I>(self, name: I) -> Self + where + I: Into<String>, + { + Self { + metadata: metadata::Expect { + name: Some(name.into()), + ..self.metadata + }, + ..self + } + } + + pub fn with_fields<I>(self, fields: I) -> Self + where + I: Into<field::Expect>, + { + Self { + fields: Some(fields.into()), + ..self + } + } + + pub fn at_level(self, level: tracing::Level) -> Self { + Self { + metadata: metadata::Expect { + level: Some(level), + ..self.metadata + }, + ..self + } + } + + pub fn with_target<I>(self, target: I) -> Self + where + I: Into<String>, + { + Self { + metadata: metadata::Expect { + target: Some(target.into()), + ..self.metadata + }, + ..self + } + } + + pub fn with_explicit_parent(self, parent: Option<&str>) -> MockEvent { + let parent = match parent { + Some(name) => Parent::Explicit(name.into()), + None => Parent::ExplicitRoot, + }; + Self { + parent: Some(parent), + ..self + } + } + + pub(in crate::support) fn check(&mut self, event: &tracing::Event<'_>) { + let meta = event.metadata(); + let name = meta.name(); + self.metadata + .check(meta, format_args!("event \"{}\"", name)); + assert!(meta.is_event(), "expected {}, but got {:?}", self, event); + if let Some(ref mut expected_fields) = self.fields { + let mut checker = expected_fields.checker(name.to_string()); + event.record(&mut checker); + checker.finish(); + } + } +} + +impl fmt::Display for MockEvent { + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + write!(f, "an event{}", self.metadata) + } +} diff --git a/third_party/rust/tracing/tests/support/field.rs b/third_party/rust/tracing/tests/support/field.rs new file mode 100644 index 0000000000..3667cf08b4 --- /dev/null +++ b/third_party/rust/tracing/tests/support/field.rs @@ -0,0 +1,226 @@ +use tracing::{ + callsite, + callsite::Callsite, + field::{self, Field, Value, Visit}, + metadata::Kind, +}; + +use std::{collections::HashMap, fmt}; + +#[derive(Default, Debug, Eq, PartialEq)] +pub struct Expect { + fields: HashMap<String, MockValue>, + only: bool, +} + +#[derive(Debug)] +pub struct MockField { + name: String, + value: MockValue, +} + +#[derive(Debug, Eq, PartialEq)] +pub enum MockValue { + I64(i64), + U64(u64), + Bool(bool), + Str(String), + Debug(String), + Any, +} + +pub fn mock<K>(name: K) -> MockField +where + String: From<K>, +{ + MockField { + name: name.into(), + value: MockValue::Any, + } +} + +impl MockField { + /// Expect a field with the given name and value. + pub fn with_value(self, value: &dyn Value) -> Self { + Self { + value: MockValue::from(value), + ..self + } + } + + pub fn and(self, other: MockField) -> Expect { + Expect { + fields: HashMap::new(), + only: false, + } + .and(self) + .and(other) + } + + pub fn only(self) -> Expect { + Expect { + fields: HashMap::new(), + only: true, + } + .and(self) + } +} + +impl Into<Expect> for MockField { + fn into(self) -> Expect { + Expect { + fields: HashMap::new(), + only: false, + } + .and(self) + } +} + +impl Expect { + pub fn and(mut self, field: MockField) -> Self { + self.fields.insert(field.name, field.value); + self + } + + /// Indicates that no fields other than those specified should be expected. + pub fn only(self) -> Self { + Self { only: true, ..self } + } + + fn compare_or_panic(&mut self, name: &str, value: &dyn Value, ctx: &str) { + let value = value.into(); + match self.fields.remove(name) { + Some(MockValue::Any) => {} + Some(expected) => assert!( + expected == value, + "\nexpected `{}` to contain:\n\t`{}{}`\nbut got:\n\t`{}{}`", + ctx, + name, + expected, + name, + value + ), + None if self.only => panic!( + "\nexpected `{}` to contain only:\n\t`{}`\nbut got:\n\t`{}{}`", + ctx, self, name, value + ), + _ => {} + } + } + + pub fn checker(&mut self, ctx: String) -> CheckVisitor<'_> { + CheckVisitor { expect: self, ctx } + } + + pub fn is_empty(&self) -> bool { + self.fields.is_empty() + } +} + +impl fmt::Display for MockValue { + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + match self { + MockValue::I64(v) => write!(f, "i64 = {:?}", v), + MockValue::U64(v) => write!(f, "u64 = {:?}", v), + MockValue::Bool(v) => write!(f, "bool = {:?}", v), + MockValue::Str(v) => write!(f, "&str = {:?}", v), + MockValue::Debug(v) => write!(f, "&fmt::Debug = {:?}", v), + MockValue::Any => write!(f, "_ = _"), + } + } +} + +pub struct CheckVisitor<'a> { + expect: &'a mut Expect, + ctx: String, +} + +impl<'a> Visit for CheckVisitor<'a> { + fn record_i64(&mut self, field: &Field, value: i64) { + self.expect + .compare_or_panic(field.name(), &value, &self.ctx[..]) + } + + fn record_u64(&mut self, field: &Field, value: u64) { + self.expect + .compare_or_panic(field.name(), &value, &self.ctx[..]) + } + + fn record_bool(&mut self, field: &Field, value: bool) { + self.expect + .compare_or_panic(field.name(), &value, &self.ctx[..]) + } + + fn record_str(&mut self, field: &Field, value: &str) { + self.expect + .compare_or_panic(field.name(), &value, &self.ctx[..]) + } + + fn record_debug(&mut self, field: &Field, value: &dyn fmt::Debug) { + self.expect + .compare_or_panic(field.name(), &field::debug(value), &self.ctx) + } +} + +impl<'a> CheckVisitor<'a> { + pub fn finish(self) { + assert!( + self.expect.fields.is_empty(), + "{}missing {}", + self.expect, + self.ctx + ); + } +} + +impl<'a> From<&'a dyn Value> for MockValue { + fn from(value: &'a dyn Value) -> Self { + struct MockValueBuilder { + value: Option<MockValue>, + } + + impl Visit for MockValueBuilder { + fn record_i64(&mut self, _: &Field, value: i64) { + self.value = Some(MockValue::I64(value)); + } + + fn record_u64(&mut self, _: &Field, value: u64) { + self.value = Some(MockValue::U64(value)); + } + + fn record_bool(&mut self, _: &Field, value: bool) { + self.value = Some(MockValue::Bool(value)); + } + + fn record_str(&mut self, _: &Field, value: &str) { + self.value = Some(MockValue::Str(value.to_owned())); + } + + fn record_debug(&mut self, _: &Field, value: &dyn fmt::Debug) { + self.value = Some(MockValue::Debug(format!("{:?}", value))); + } + } + + let fake_field = callsite!(name: "fake", kind: Kind::EVENT, fields: fake_field) + .metadata() + .fields() + .field("fake_field") + .unwrap(); + let mut builder = MockValueBuilder { value: None }; + value.record(&fake_field, &mut builder); + builder + .value + .expect("finish called before a value was recorded") + } +} + +impl fmt::Display for Expect { + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + write!(f, "fields ")?; + let entries = self + .fields + .iter() + .map(|(k, v)| (field::display(k), field::display(v))); + f.debug_map().entries(entries).finish() + } +} diff --git a/third_party/rust/tracing/tests/support/metadata.rs b/third_party/rust/tracing/tests/support/metadata.rs new file mode 100644 index 0000000000..2c3606b05e --- /dev/null +++ b/third_party/rust/tracing/tests/support/metadata.rs @@ -0,0 +1,64 @@ +use std::fmt; +use tracing::Metadata; + +#[derive(Clone, Debug, Eq, PartialEq, Default)] +pub struct Expect { + pub name: Option<String>, + pub level: Option<tracing::Level>, + pub target: Option<String>, +} + +impl Expect { + pub(in crate::support) fn check(&self, actual: &Metadata<'_>, ctx: fmt::Arguments<'_>) { + if let Some(ref expected_name) = self.name { + let name = actual.name(); + assert!( + expected_name == name, + "expected {} to be named `{}`, but got one named `{}`", + ctx, + expected_name, + name + ) + } + + if let Some(ref expected_level) = self.level { + let level = actual.level(); + assert!( + expected_level == level, + "expected {} to be at level `{:?}`, but it was at level `{:?}` instead", + ctx, + expected_level, + level, + ) + } + + if let Some(ref expected_target) = self.target { + let target = actual.target(); + assert!( + expected_target == target, + "expected {} to have target `{}`, but it had target `{}` instead", + ctx, + expected_target, + target, + ) + } + } +} + +impl fmt::Display for Expect { + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + if let Some(ref name) = self.name { + write!(f, " named `{}`", name)?; + } + + if let Some(ref level) = self.level { + write!(f, " at the `{:?}` level", level)?; + } + + if let Some(ref target) = self.target { + write!(f, " with target `{}`", target)?; + } + + Ok(()) + } +} diff --git a/third_party/rust/tracing/tests/support/mod.rs b/third_party/rust/tracing/tests/support/mod.rs new file mode 100644 index 0000000000..7900f38c76 --- /dev/null +++ b/third_party/rust/tracing/tests/support/mod.rs @@ -0,0 +1,14 @@ +#![allow(dead_code)] +pub mod event; +pub mod field; +mod metadata; +pub mod span; +pub mod subscriber; + +#[derive(Debug, Eq, PartialEq)] +pub(in crate::support) enum Parent { + ContextualRoot, + Contextual(String), + ExplicitRoot, + Explicit(String), +} diff --git a/third_party/rust/tracing/tests/support/span.rs b/third_party/rust/tracing/tests/support/span.rs new file mode 100644 index 0000000000..023e5b7079 --- /dev/null +++ b/third_party/rust/tracing/tests/support/span.rs @@ -0,0 +1,167 @@ +#![allow(missing_docs)] +use super::{field, metadata, Parent}; +use std::fmt; + +/// A mock span. +/// +/// This is intended for use with the mock subscriber API in the +/// `subscriber` module. +#[derive(Clone, Debug, Default, Eq, PartialEq)] +pub struct MockSpan { + pub(in crate::support) metadata: metadata::Expect, +} + +#[derive(Debug, Default, Eq, PartialEq)] +pub struct NewSpan { + pub(in crate::support) span: MockSpan, + pub(in crate::support) fields: field::Expect, + pub(in crate::support) parent: Option<Parent>, +} + +pub fn mock() -> MockSpan { + MockSpan { + ..Default::default() + } +} + +impl MockSpan { + pub fn named<I>(self, name: I) -> Self + where + I: Into<String>, + { + Self { + metadata: metadata::Expect { + name: Some(name.into()), + ..self.metadata + }, + } + } + + pub fn at_level(self, level: tracing::Level) -> Self { + Self { + metadata: metadata::Expect { + level: Some(level), + ..self.metadata + }, + } + } + + pub fn with_target<I>(self, target: I) -> Self + where + I: Into<String>, + { + Self { + metadata: metadata::Expect { + target: Some(target.into()), + ..self.metadata + }, + } + } + + pub fn with_explicit_parent(self, parent: Option<&str>) -> NewSpan { + let parent = match parent { + Some(name) => Parent::Explicit(name.into()), + None => Parent::ExplicitRoot, + }; + NewSpan { + parent: Some(parent), + span: self, + ..Default::default() + } + } + + pub fn with_contextual_parent(self, parent: Option<&str>) -> NewSpan { + let parent = match parent { + Some(name) => Parent::Contextual(name.into()), + None => Parent::ContextualRoot, + }; + NewSpan { + parent: Some(parent), + span: self, + ..Default::default() + } + } + + pub fn name(&self) -> Option<&str> { + self.metadata.name.as_ref().map(String::as_ref) + } + + pub fn with_field<I>(self, fields: I) -> NewSpan + where + I: Into<field::Expect>, + { + NewSpan { + span: self, + fields: fields.into(), + ..Default::default() + } + } + + pub(in crate::support) fn check_metadata(&self, actual: &tracing::Metadata<'_>) { + self.metadata.check(actual, format_args!("span {}", self)); + assert!(actual.is_span(), "expected a span but got {:?}", actual); + } +} + +impl fmt::Display for MockSpan { + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + if self.metadata.name.is_some() { + write!(f, "a span{}", self.metadata) + } else { + write!(f, "any span{}", self.metadata) + } + } +} + +impl Into<NewSpan> for MockSpan { + fn into(self) -> NewSpan { + NewSpan { + span: self, + ..Default::default() + } + } +} + +impl NewSpan { + pub fn with_explicit_parent(self, parent: Option<&str>) -> NewSpan { + let parent = match parent { + Some(name) => Parent::Explicit(name.into()), + None => Parent::ExplicitRoot, + }; + NewSpan { + parent: Some(parent), + ..self + } + } + + pub fn with_contextual_parent(self, parent: Option<&str>) -> NewSpan { + let parent = match parent { + Some(name) => Parent::Contextual(name.into()), + None => Parent::ContextualRoot, + }; + NewSpan { + parent: Some(parent), + ..self + } + } + + pub fn with_field<I>(self, fields: I) -> NewSpan + where + I: Into<field::Expect>, + { + NewSpan { + fields: fields.into(), + ..self + } + } +} + +impl fmt::Display for NewSpan { + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + write!(f, "a new span{}", self.span.metadata)?; + if !self.fields.is_empty() { + write!(f, " with {}", self.fields)?; + } + Ok(()) + } +} diff --git a/third_party/rust/tracing/tests/support/subscriber.rs b/third_party/rust/tracing/tests/support/subscriber.rs new file mode 100644 index 0000000000..83f1139849 --- /dev/null +++ b/third_party/rust/tracing/tests/support/subscriber.rs @@ -0,0 +1,569 @@ +#![allow(missing_docs)] +use super::{ + event::MockEvent, + field as mock_field, + span::{MockSpan, NewSpan}, + Parent, +}; +use std::{ + collections::{HashMap, VecDeque}, + fmt, + sync::{ + atomic::{AtomicUsize, Ordering}, + Arc, Mutex, + }, + thread, +}; +use tracing::{ + level_filters::LevelFilter, + span::{self, Attributes, Id}, + subscriber::Interest, + Event, Metadata, Subscriber, +}; + +#[derive(Debug, Eq, PartialEq)] +enum Expect { + Event(MockEvent), + Enter(MockSpan), + Exit(MockSpan), + CloneSpan(MockSpan), + DropSpan(MockSpan), + Visit(MockSpan, mock_field::Expect), + NewSpan(NewSpan), + Nothing, +} + +struct SpanState { + name: &'static str, + refs: usize, +} + +struct Running<F: Fn(&Metadata<'_>) -> bool> { + spans: Mutex<HashMap<Id, SpanState>>, + expected: Arc<Mutex<VecDeque<Expect>>>, + current: Mutex<Vec<Id>>, + ids: AtomicUsize, + max_level: Option<LevelFilter>, + filter: F, + name: String, +} + +pub struct MockSubscriber<F: Fn(&Metadata<'_>) -> bool> { + expected: VecDeque<Expect>, + max_level: Option<LevelFilter>, + filter: F, + name: String, +} + +pub struct MockHandle(Arc<Mutex<VecDeque<Expect>>>, String); + +pub fn mock() -> MockSubscriber<fn(&Metadata<'_>) -> bool> { + MockSubscriber { + expected: VecDeque::new(), + filter: (|_: &Metadata<'_>| true) as for<'r, 's> fn(&'r Metadata<'s>) -> _, + max_level: None, + name: thread::current() + .name() + .unwrap_or("mock_subscriber") + .to_string(), + } +} + +impl<F> MockSubscriber<F> +where + F: Fn(&Metadata<'_>) -> bool + 'static, +{ + /// Overrides the name printed by the mock subscriber's debugging output. + /// + /// The debugging output is displayed if the test panics, or if the test is + /// run with `--nocapture`. + /// + /// By default, the mock subscriber's name is the name of the test + /// (*technically*, the name of the thread where it was created, which is + /// the name of the test unless tests are run with `--test-threads=1`). + /// When a test has only one mock subscriber, this is sufficient. However, + /// some tests may include multiple subscribers, in order to test + /// interactions between multiple subscribers. In that case, it can be + /// helpful to give each subscriber a separate name to distinguish where the + /// debugging output comes from. + pub fn named(self, name: impl ToString) -> Self { + Self { + name: name.to_string(), + ..self + } + } + + pub fn enter(mut self, span: MockSpan) -> Self { + self.expected.push_back(Expect::Enter(span)); + self + } + + pub fn event(mut self, event: MockEvent) -> Self { + self.expected.push_back(Expect::Event(event)); + self + } + + pub fn exit(mut self, span: MockSpan) -> Self { + self.expected.push_back(Expect::Exit(span)); + self + } + + pub fn clone_span(mut self, span: MockSpan) -> Self { + self.expected.push_back(Expect::CloneSpan(span)); + self + } + + #[allow(deprecated)] + pub fn drop_span(mut self, span: MockSpan) -> Self { + self.expected.push_back(Expect::DropSpan(span)); + self + } + + pub fn done(mut self) -> Self { + self.expected.push_back(Expect::Nothing); + self + } + + pub fn record<I>(mut self, span: MockSpan, fields: I) -> Self + where + I: Into<mock_field::Expect>, + { + self.expected.push_back(Expect::Visit(span, fields.into())); + self + } + + pub fn new_span<I>(mut self, new_span: I) -> Self + where + I: Into<NewSpan>, + { + self.expected.push_back(Expect::NewSpan(new_span.into())); + self + } + + pub fn with_filter<G>(self, filter: G) -> MockSubscriber<G> + where + G: Fn(&Metadata<'_>) -> bool + 'static, + { + MockSubscriber { + expected: self.expected, + filter, + max_level: self.max_level, + name: self.name, + } + } + + pub fn with_max_level_hint(self, hint: impl Into<LevelFilter>) -> Self { + Self { + max_level: Some(hint.into()), + ..self + } + } + + pub fn run(self) -> impl Subscriber { + let (subscriber, _) = self.run_with_handle(); + subscriber + } + + pub fn run_with_handle(self) -> (impl Subscriber, MockHandle) { + let expected = Arc::new(Mutex::new(self.expected)); + let handle = MockHandle(expected.clone(), self.name.clone()); + let subscriber = Running { + spans: Mutex::new(HashMap::new()), + expected, + current: Mutex::new(Vec::new()), + ids: AtomicUsize::new(1), + filter: self.filter, + max_level: self.max_level, + name: self.name, + }; + (subscriber, handle) + } +} + +impl<F> Subscriber for Running<F> +where + F: Fn(&Metadata<'_>) -> bool + 'static, +{ + fn enabled(&self, meta: &Metadata<'_>) -> bool { + println!("[{}] enabled: {:#?}", self.name, meta); + let enabled = (self.filter)(meta); + println!("[{}] enabled -> {}", self.name, enabled); + enabled + } + + fn register_callsite(&self, meta: &'static Metadata<'static>) -> Interest { + println!("[{}] register_callsite: {:#?}", self.name, meta); + if self.enabled(meta) { + Interest::always() + } else { + Interest::never() + } + } + fn max_level_hint(&self) -> Option<LevelFilter> { + self.max_level + } + + fn record(&self, id: &Id, values: &span::Record<'_>) { + let spans = self.spans.lock().unwrap(); + let mut expected = self.expected.lock().unwrap(); + let span = spans + .get(id) + .unwrap_or_else(|| panic!("[{}] no span for ID {:?}", self.name, id)); + println!( + "[{}] record: {}; id={:?}; values={:?};", + self.name, span.name, id, values + ); + let was_expected = if let Some(Expect::Visit(_, _)) = expected.front() { + true + } else { + false + }; + if was_expected { + if let Expect::Visit(expected_span, mut expected_values) = expected.pop_front().unwrap() + { + if let Some(name) = expected_span.name() { + assert_eq!(name, span.name); + } + let mut checker = expected_values.checker(format!("span {}: ", span.name)); + values.record(&mut checker); + checker.finish(); + } + } + } + + fn event(&self, event: &Event<'_>) { + let name = event.metadata().name(); + println!("[{}] event: {};", self.name, name); + match self.expected.lock().unwrap().pop_front() { + None => {} + Some(Expect::Event(mut expected)) => { + let spans = self.spans.lock().unwrap(); + expected.check(event); + match expected.parent { + Some(Parent::ExplicitRoot) => { + assert!( + event.is_root(), + "[{}] expected {:?} to be an explicit root event", + self.name, + name + ); + } + Some(Parent::Explicit(expected_parent)) => { + let actual_parent = + event.parent().and_then(|id| spans.get(id)).map(|s| s.name); + assert_eq!( + Some(expected_parent.as_ref()), + actual_parent, + "[{}] expected {:?} to have explicit parent {:?}", + self.name, + name, + expected_parent, + ); + } + Some(Parent::ContextualRoot) => { + assert!( + event.is_contextual(), + "[{}] expected {:?} to have a contextual parent", + self.name, + name + ); + assert!( + self.current.lock().unwrap().last().is_none(), + "[{}] expected {:?} to be a root, but we were inside a span", + self.name, + name + ); + } + Some(Parent::Contextual(expected_parent)) => { + assert!( + event.is_contextual(), + "[{}] expected {:?} to have a contextual parent", + self.name, + name + ); + let stack = self.current.lock().unwrap(); + let actual_parent = + stack.last().and_then(|id| spans.get(id)).map(|s| s.name); + assert_eq!( + Some(expected_parent.as_ref()), + actual_parent, + "[{}] expected {:?} to have contextual parent {:?}", + self.name, + name, + expected_parent, + ); + } + None => {} + } + } + Some(ex) => ex.bad( + &self.name, + format_args!("[{}] observed event {:?}", self.name, event), + ), + } + } + + fn record_follows_from(&self, _span: &Id, _follows: &Id) { + // TODO: it should be possible to expect spans to follow from other spans + } + + fn new_span(&self, span: &Attributes<'_>) -> Id { + let meta = span.metadata(); + let id = self.ids.fetch_add(1, Ordering::SeqCst); + let id = Id::from_u64(id as u64); + println!( + "[{}] new_span: name={:?}; target={:?}; id={:?};", + self.name, + meta.name(), + meta.target(), + id + ); + let mut expected = self.expected.lock().unwrap(); + let was_expected = match expected.front() { + Some(Expect::NewSpan(_)) => true, + _ => false, + }; + let mut spans = self.spans.lock().unwrap(); + if was_expected { + if let Expect::NewSpan(mut expected) = expected.pop_front().unwrap() { + let name = meta.name(); + expected + .span + .metadata + .check(meta, format_args!("span `{}`", name)); + let mut checker = expected.fields.checker(name.to_string()); + span.record(&mut checker); + checker.finish(); + match expected.parent { + Some(Parent::ExplicitRoot) => { + assert!( + span.is_root(), + "[{}] expected {:?} to be an explicit root span", + self.name, + name + ); + } + Some(Parent::Explicit(expected_parent)) => { + let actual_parent = + span.parent().and_then(|id| spans.get(id)).map(|s| s.name); + assert_eq!( + Some(expected_parent.as_ref()), + actual_parent, + "[{}] expected {:?} to have explicit parent {:?}", + self.name, + name, + expected_parent, + ); + } + Some(Parent::ContextualRoot) => { + assert!( + span.is_contextual(), + "[{}] expected {:?} to have a contextual parent", + self.name, + name + ); + assert!( + self.current.lock().unwrap().last().is_none(), + "[{}] expected {:?} to be a root, but we were inside a span", + self.name, + name + ); + } + Some(Parent::Contextual(expected_parent)) => { + assert!( + span.is_contextual(), + "[{}] expected {:?} to have a contextual parent", + self.name, + name + ); + let stack = self.current.lock().unwrap(); + let actual_parent = + stack.last().and_then(|id| spans.get(id)).map(|s| s.name); + assert_eq!( + Some(expected_parent.as_ref()), + actual_parent, + "[{}] expected {:?} to have contextual parent {:?}", + self.name, + name, + expected_parent, + ); + } + None => {} + } + } + } + spans.insert( + id.clone(), + SpanState { + name: meta.name(), + refs: 1, + }, + ); + id + } + + fn enter(&self, id: &Id) { + let spans = self.spans.lock().unwrap(); + if let Some(span) = spans.get(id) { + println!("[{}] enter: {}; id={:?};", self.name, span.name, id); + match self.expected.lock().unwrap().pop_front() { + None => {} + Some(Expect::Enter(ref expected_span)) => { + if let Some(name) = expected_span.name() { + assert_eq!(name, span.name); + } + } + Some(ex) => ex.bad(&self.name, format_args!("entered span {:?}", span.name)), + } + }; + self.current.lock().unwrap().push(id.clone()); + } + + fn exit(&self, id: &Id) { + if std::thread::panicking() { + // `exit()` can be called in `drop` impls, so we must guard against + // double panics. + println!("[{}] exit {:?} while panicking", self.name, id); + return; + } + let spans = self.spans.lock().unwrap(); + let span = spans + .get(id) + .unwrap_or_else(|| panic!("[{}] no span for ID {:?}", self.name, id)); + println!("[{}] exit: {}; id={:?};", self.name, span.name, id); + match self.expected.lock().unwrap().pop_front() { + None => {} + Some(Expect::Exit(ref expected_span)) => { + if let Some(name) = expected_span.name() { + assert_eq!(name, span.name); + } + let curr = self.current.lock().unwrap().pop(); + assert_eq!( + Some(id), + curr.as_ref(), + "[{}] exited span {:?}, but the current span was {:?}", + self.name, + span.name, + curr.as_ref().and_then(|id| spans.get(id)).map(|s| s.name) + ); + } + Some(ex) => ex.bad(&self.name, format_args!("exited span {:?}", span.name)), + }; + } + + fn clone_span(&self, id: &Id) -> Id { + let name = self.spans.lock().unwrap().get_mut(id).map(|span| { + let name = span.name; + println!( + "[{}] clone_span: {}; id={:?}; refs={:?};", + self.name, name, id, span.refs + ); + span.refs += 1; + name + }); + if name.is_none() { + println!("[{}] clone_span: id={:?};", self.name, id); + } + let mut expected = self.expected.lock().unwrap(); + let was_expected = if let Some(Expect::CloneSpan(ref span)) = expected.front() { + assert_eq!( + name, + span.name(), + "[{}] expected to clone a span named {:?}", + self.name, + span.name() + ); + true + } else { + false + }; + if was_expected { + expected.pop_front(); + } + id.clone() + } + + fn drop_span(&self, id: Id) { + let mut is_event = false; + let name = if let Ok(mut spans) = self.spans.try_lock() { + spans.get_mut(&id).map(|span| { + let name = span.name; + if name.contains("event") { + is_event = true; + } + println!( + "[{}] drop_span: {}; id={:?}; refs={:?};", + self.name, name, id, span.refs + ); + span.refs -= 1; + name + }) + } else { + None + }; + if name.is_none() { + println!("[{}] drop_span: id={:?}", self.name, id); + } + if let Ok(mut expected) = self.expected.try_lock() { + let was_expected = match expected.front() { + Some(Expect::DropSpan(ref span)) => { + // Don't assert if this function was called while panicking, + // as failing the assertion can cause a double panic. + if !::std::thread::panicking() { + assert_eq!(name, span.name()); + } + true + } + Some(Expect::Event(_)) => { + if !::std::thread::panicking() { + assert!(is_event, "[{}] expected an event", self.name); + } + true + } + _ => false, + }; + if was_expected { + expected.pop_front(); + } + } + } +} + +impl MockHandle { + pub fn assert_finished(&self) { + if let Ok(ref expected) = self.0.lock() { + assert!( + !expected.iter().any(|thing| thing != &Expect::Nothing), + "[{}] more notifications expected: {:?}", + self.1, + **expected + ); + } + } +} + +impl Expect { + fn bad<'a>(&self, name: impl AsRef<str>, what: fmt::Arguments<'a>) { + let name = name.as_ref(); + match self { + Expect::Event(e) => panic!("[{}] expected event {}, but {} instead", name, e, what,), + Expect::Enter(e) => panic!("[{}] expected to enter {} but {} instead", name, e, what,), + Expect::Exit(e) => panic!("[{}] expected to exit {} but {} instead", name, e, what,), + Expect::CloneSpan(e) => { + panic!("[{}] expected to clone {} but {} instead", name, e, what,) + } + Expect::DropSpan(e) => { + panic!("[{}] expected to drop {} but {} instead", name, e, what,) + } + Expect::Visit(e, fields) => panic!( + "[{}] expected {} to record {} but {} instead", + name, e, fields, what, + ), + Expect::NewSpan(e) => panic!("[{}] expected {} but {} instead", name, e, what), + Expect::Nothing => panic!( + "[{}] expected nothing else to happen, but {} instead", + name, what, + ), + } + } +} |