diff options
| author | Fedor Tsarev <ftsarev@google.com> | 2023-03-27 08:03:13 +0000 |
|---|---|---|
| committer | Automerger Merge Worker <android-build-automerger-merge-worker@system.gserviceaccount.com> | 2023-03-27 08:03:13 +0000 |
| commit | 82eeb450e95f36b9b19ecab0fbda9a71813d71bf (patch) | |
| tree | f479f88bd4791d5ea3b69e124b198aac586d910d | |
| parent | ae0030cf1093e4b735124829e054dc1409814af0 (diff) | |
| parent | 76d353d71de33839a52243705f4edfd02d716f91 (diff) | |
| download | tracing-82eeb450e95f36b9b19ecab0fbda9a71813d71bf.tar.gz | |
Import crate tracing am: 5500e2cb84 am: 4f725c2903 am: 76d353d71d
Original change: https://android-review.googlesource.com/c/platform/external/rust/crates/tracing/+/2506378
Change-Id: I97d81aa4dcaa40faa0372a5e1b41a0ab841b17ac
Signed-off-by: Automerger Merge Worker <android-build-automerger-merge-worker@system.gserviceaccount.com>
45 files changed, 11114 insertions, 0 deletions
diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..978e0ca --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,806 @@ +# 0.1.37 (October 6, 2022) + +This release of `tracing` incorporates changes from `tracing-core` +[v0.1.30][core-0.1.30] and `tracing-attributes` [v0.1.23][attrs-0.1.23], +including the new `Subscriber::on_register_dispatch` method for performing late +initialization after a `Subscriber` is registered as a `Dispatch`, and bugfixes +for the `#[instrument]` attribute. Additionally, it fixes instances of the +`bare_trait_objects` lint, which is now a warning on `tracing`'s MSRV and will +become an error in the next edition. + +### Fixed + +- **attributes**: Incorrect handling of inner attributes in `#[instrument]`ed + functions ([#2307]) +- **attributes**: Incorrect location of compiler diagnostic spans generated for + type errors in `#[instrument]`ed `async fn`s ([#2270]) +- **attributes**: Updated `syn` dependency to fix compilation with `-Z + minimal-versions` ([#2246]) +- `bare_trait_objects` warning in `valueset!` macro expansion ([#2308]) + +### Added + +- **core**: `Subscriber::on_register_dispatch` method ([#2269]) +- **core**: `WeakDispatch` type and `Dispatch::downgrade()` function ([#2293]) + +### Changed + +- `tracing-core`: updated to [0.1.30][core-0.1.30] +- `tracing-attributes`: updated to [0.1.23][attrs-0.1.23] + +### Documented + +- Added [`tracing-web`] and [`reqwest-tracing`] to related crates ([#2283], + [#2331]) + +Thanks to new contributors @compiler-errors, @e-nomem, @WorldSEnder, @Xiami2012, +and @tl-rodrigo-gryzinski, as well as @jswrenn and @CAD97, for contributing to +this release! + +[core-0.1.30]: https://github.com/tokio-rs/tracing/releases/tag/tracing-core-0.1.30 +[attrs-0.1.23]: https://github.com/tokio-rs/tracing/releases/tag/tracing-attributes-0.1.23 +[`tracing-web`]: https://crates.io/crates/tracing-web/ +[`reqwest-tracing`]: https://crates.io/crates/reqwest-tracing/ +[#2246]: https://github.com/tokio-rs/tracing/pull/2246 +[#2269]: https://github.com/tokio-rs/tracing/pull/2269 +[#2283]: https://github.com/tokio-rs/tracing/pull/2283 +[#2270]: https://github.com/tokio-rs/tracing/pull/2270 +[#2293]: https://github.com/tokio-rs/tracing/pull/2293 +[#2307]: https://github.com/tokio-rs/tracing/pull/2307 +[#2308]: https://github.com/tokio-rs/tracing/pull/2308 +[#2331]: https://github.com/tokio-rs/tracing/pull/2331 + +# 0.1.36 (July 29, 2022) + +This release adds support for owned values and fat pointers as arguments to the +`Span::record` method, as well as updating the minimum `tracing-core` version +and several documentation improvements. + +### Fixed + +- Incorrect docs in `dispatcher::set_default` ([#2220]) +- Compilation with `-Z minimal-versions` ([#2246]) + +### Added + +- Support for owned values and fat pointers in `Span::record` ([#2212]) +- Documentation improvements ([#2208], [#2163]) + +### Changed + +- `tracing-core`: updated to [0.1.29][core-0.1.29] + +Thanks to @fredr, @cgbur, @jyn514, @matklad, and @CAD97 for contributing to this +release! + +[core-0.1.29]: https://github.com/tokio-rs/tracing/releases/tag/tracing-core-0.1.29 +[#2220]: https://github.com/tokio-rs/tracing/pull/2220 +[#2246]: https://github.com/tokio-rs/tracing/pull/2246 +[#2212]: https://github.com/tokio-rs/tracing/pull/2212 +[#2208]: https://github.com/tokio-rs/tracing/pull/2208 +[#2163]: https://github.com/tokio-rs/tracing/pull/2163 + +# 0.1.35 (June 8, 2022) + +This release reduces the overhead of callsite registration by using new +`tracing-core` APIs. + +### Added + +- Use `DefaultCallsite` to reduce callsite registration overhead ([#2083]) + +### Changed + +- `tracing-core`: updated to [0.1.27][core-0.1.27] + +[core-0.1.27]: https://github.com/tokio-rs/tracing/releases/tag/tracing-core-0.1.27 +[#2088]: https://github.com/tokio-rs/tracing/pull/2083 + +# 0.1.34 (April 14, 2022) + +This release includes bug fixes for the "log" support feature and for the use of +both scoped and global default dispatchers in the same program. + +### Fixed + +- Failure to use the global default dispatcher when a thread sets a local + default dispatcher before the global default is set ([#2065]) +- **log**: Compilation errors due to `async` block/fn futures becoming `!Send` + when the "log" feature flag is enabled ([#2073]) +- Broken links in documentation ([#2068]) + +Thanks to @ben0x539 for contributing to this release! + +[#2065]: https://github.com/tokio-rs/tracing/pull/2065 +[#2073]: https://github.com/tokio-rs/tracing/pull/2073 +[#2068]: https://github.com/tokio-rs/tracing/pull/2068 + +# 0.1.33 (April 9, 2022) + +This release adds new `span_enabled!` and `event_enabled!` variants of the +`enabled!` macro, for testing whether a subscriber would specifically enable a +span or an event. + +### Added + +- `span_enabled!` and `event_enabled!` macros ([#1900]) +- Several documentation improvements ([#2010], [#2012]) + +### Fixed + +- Compilation warning when compiling for <=32-bit targets (including `wasm32`) + ([#2060]) + +Thanks to @guswynn, @arifd, @hrxi, @CAD97, and @name1e5s for contributing to +this release! + +[#1900]: https://github.com/tokio-rs/tracing/pull/1900 +[#2010]: https://github.com/tokio-rs/tracing/pull/2010 +[#2012]: https://github.com/tokio-rs/tracing/pull/2012 +[#2060]: https://github.com/tokio-rs/tracing/pull/2060 + +# 0.1.32 (March 8th, 2022) + +This release reduces the overhead of creating and dropping disabled +spans significantly, which should improve performance when no `tracing` +subscriber is in use or when spans are disabled by a filter. + +### Fixed + +- **attributes**: Compilation failure with `--minimal-versions` due to a + too-permissive `syn` dependency ([#1960]) + +### Changed + +- Reduced `Drop` overhead for disabled spans ([#1974]) +- `tracing-attributes`: updated to [0.1.20][attributes-0.1.20] + +[#1974]: https://github.com/tokio-rs/tracing/pull/1974 +[#1960]: https://github.com/tokio-rs/tracing/pull/1960 +[attributes-0.1.20]: https://github.com/tokio-rs/tracing/releases/tag/tracing-attributes-0.1.20 + +# 0.1.31 (February 17th, 2022) + +This release increases the minimum supported Rust version (MSRV) to 1.49.0. In +addition, it fixes some relatively rare macro bugs. + +### Added + +- Added `tracing-forest` to the list of related crates ([#1935]) + +### Changed + +- Updated minimum supported Rust version (MSRV) to 1.49.0 ([#1913]) + +### Fixed + +- Fixed the `warn!` macro incorrectly generating an event with the `TRACE` level + ([#1930]) +- Fixed macro hygiene issues when used in a crate that defines its own `concat!` + macro, for real this time ([#1918]) + +Thanks to @QnnOkabayashi, @nicolaasg, and @teohhanhui for contributing to this +release! + +[#1935]: https://github.com/tokio-rs/tracing/pull/1935 +[#1913]: https://github.com/tokio-rs/tracing/pull/1913 +[#1930]: https://github.com/tokio-rs/tracing/pull/1930 +[#1918]: https://github.com/tokio-rs/tracing/pull/1918 + +# 0.1.30 (February 3rd, 2022) + +This release adds *experimental* support for recording structured field +values using the [`valuable`] crate. See [this blog post][post] for +details on `valuable`. + +Note that `valuable` support currently requires `--cfg tracing_unstable`. See +the documentation for details. + +This release also adds a new `enabled!` macro for testing if a span or event +would be enabled. + +### Added + +- **field**: Experimental support for recording field values using the + [`valuable`] crate ([#1608], [#1888], [#1887]) +- `enabled!` macro for testing if a span or event is enabled ([#1882]) + +### Changed + +- `tracing-core`: updated to [0.1.22][core-0.1.22] +- `tracing-attributes`: updated to [0.1.19][attributes-0.1.19] + +### Fixed + +- **log**: Fixed "use of moved value" compiler error when the "log" feature is + enabled ([#1823]) +- Fixed macro hygiene issues when used in a crate that defines its own `concat!` + macro ([#1842]) +- A very large number of documentation fixes and improvements. + +Thanks to @@Vlad-Scherbina, @Skepfyr, @Swatinem, @guswynn, @teohhanhui, +@xd009642, @tobz, @d-e-s-o@0b01, and @nickelc for contributing to this release! + +[`valuable`]: https://crates.io/crates/valuable +[post]: https://tokio.rs/blog/2021-05-valuable +[core-0.1.22]: https://github.com/tokio-rs/tracing/releases/tag/tracing-core-0.1.22 +[attributes-0.1.19]: https://github.com/tokio-rs/tracing/releases/tag/tracing-attributes-0.1.19 +[#1608]: https://github.com/tokio-rs/tracing/pull/1608 +[#1888]: https://github.com/tokio-rs/tracing/pull/1888 +[#1887]: https://github.com/tokio-rs/tracing/pull/1887 +[#1882]: https://github.com/tokio-rs/tracing/pull/1882 +[#1823]: https://github.com/tokio-rs/tracing/pull/1823 +[#1842]: https://github.com/tokio-rs/tracing/pull/1842 + +# 0.1.29 (October 5th, 2021) + +This release adds support for recording `Option<T> where T: Value` as typed +`tracing` field values. It also includes significant performance improvements +for functions annotated with the `#[instrument]` attribute when the generated +span is disabled. + +### Changed + +- `tracing-core`: updated to v0.1.21 +- `tracing-attributes`: updated to v0.1.18 + +### Added + +- **field**: `Value` impl for `Option<T> where T: Value` ([#1585]) +- **attributes**: - improved performance when skipping `#[instrument]`-generated + spans below the max level ([#1600], [#1605], [#1614], [#1616], [#1617]) + +### Fixed + +- **instrument**: added missing `Future` implementation for `WithSubscriber`, + making the `WithDispatch` extension trait actually useable ([#1602]) +- Documentation fixes and improvements ([#1595], [#1601], [#1597]) + +Thanks to @brianburgers, @mattiast, @DCjanus, @oli-obk, and @matklad for +contributing to this release! + +[#1585]: https://github.com/tokio-rs/tracing/pull/1585 +[#1595]: https://github.com/tokio-rs/tracing/pull/1596 +[#1597]: https://github.com/tokio-rs/tracing/pull/1597 +[#1600]: https://github.com/tokio-rs/tracing/pull/1600 +[#1601]: https://github.com/tokio-rs/tracing/pull/1601 +[#1602]: https://github.com/tokio-rs/tracing/pull/1602 +[#1605]: https://github.com/tokio-rs/tracing/pull/1605 +[#1614]: https://github.com/tokio-rs/tracing/pull/1614 +[#1616]: https://github.com/tokio-rs/tracing/pull/1616 +[#1617]: https://github.com/tokio-rs/tracing/pull/1617 + +# 0.1.28 (September 17th, 2021) + +This release fixes an issue where the RustDoc documentation was rendered +incorrectly. It doesn't include any actual code changes, and is very boring and +can be ignored. + +### Fixed + +- **docs**: Incorrect documentation rendering due to unclosed `<div>` tag + ([#1572]) + +[#1572]: https://github.com/tokio-rs/tracing/pull/1572 + +# 0.1.27 (September 13, 2021) + +This release adds a new [`Span::or_current`] method to aid in efficiently +propagating span contexts to spawned threads or tasks. Additionally, it updates +the [`tracing-core`] version to [0.1.20] and the [`tracing-attributes`] version to +[0.1.16], ensuring that a number of new features in those crates are present. + +### Fixed + +- **instrument**: Added missing `WithSubscriber` implementations for futures and + other types ([#1424]) + +### Added + +- `Span::or_current` method, to help with efficient span context propagation + ([#1538]) +- **attributes**: add `skip_all` option to `#[instrument]` ([#1548]) +- **attributes**: record primitive types as primitive values rather than as + `fmt::Debug` ([#1378]) +- **core**: `NoSubscriber`, a no-op `Subscriber` implementation + ([#1549]) +- **core**: Added `Visit::record_f64` and support for recording floating-point + values ([#1507], [#1522]) +- A large number of documentation improvements and fixes ([#1369], [#1398], + [#1435], [#1442], [#1524], [#1556]) + +Thanks to new contributors @dzvon and @mbergkvist, as well as @teozkr, +@maxburke, @LukeMathWalker, and @jsgf, for contributing to this +release! + +[`Span::or_current`]: https://docs.rs/tracing/0.1.27/tracing/struct.Span.html#method.or_current +[`tracing-core`]: https://crates.io/crates/tracing-core +[`tracing-attributes`]: https://crates.io/crates/tracing-attributes +[`tracing-core`]: https://crates.io/crates/tracing-core +[0.1.20]: https://github.com/tokio-rs/tracing/releases/tag/tracing-core-0.1.20 +[0.1.16]: https://github.com/tokio-rs/tracing/releases/tag/tracing-attributes-0.1.16 +[#1424]: https://github.com/tokio-rs/tracing/pull/1424 +[#1538]: https://github.com/tokio-rs/tracing/pull/1538 +[#1548]: https://github.com/tokio-rs/tracing/pull/1548 +[#1378]: https://github.com/tokio-rs/tracing/pull/1378 +[#1507]: https://github.com/tokio-rs/tracing/pull/1507 +[#1522]: https://github.com/tokio-rs/tracing/pull/1522 +[#1369]: https://github.com/tokio-rs/tracing/pull/1369 +[#1398]: https://github.com/tokio-rs/tracing/pull/1398 +[#1435]: https://github.com/tokio-rs/tracing/pull/1435 +[#1442]: https://github.com/tokio-rs/tracing/pull/1442 +[#1524]: https://github.com/tokio-rs/tracing/pull/1524 +[#1556]: https://github.com/tokio-rs/tracing/pull/1556 + +# 0.1.26 (April 30, 2021) + +### Fixed + +- **attributes**: Compatibility between `#[instrument]` and `async-trait` + v0.1.43 and newer ([#1228]) +- Several documentation fixes ([#1305], [#1344]) +### Added + +- `Subscriber` impl for `Box<dyn Subscriber + Send + Sync + 'static>` ([#1358]) +- `Subscriber` impl for `Arc<dyn Subscriber + Send + Sync + 'static>` ([#1374]) +- Symmetric `From` impls for existing `Into` impls on `span::Current`, `Span`, + and `Option<Id>` ([#1335], [#1338]) +- `From<EnteredSpan>` implementation for `Option<Id>`, allowing `EnteredSpan` to + be used in a `span!` macro's `parent:` field ([#1325]) +- `Attributes::fields` accessor that returns the set of fields defined on a + span's `Attributes` ([#1331]) + + +Thanks to @Folyd, @nightmared, and new contributors @rmsc and @Fishrock123 for +contributing to this release! + +[#1227]: https://github.com/tokio-rs/tracing/pull/1228 +[#1305]: https://github.com/tokio-rs/tracing/pull/1305 +[#1325]: https://github.com/tokio-rs/tracing/pull/1325 +[#1338]: https://github.com/tokio-rs/tracing/pull/1338 +[#1344]: https://github.com/tokio-rs/tracing/pull/1344 +[#1358]: https://github.com/tokio-rs/tracing/pull/1358 +[#1374]: https://github.com/tokio-rs/tracing/pull/1374 +[#1335]: https://github.com/tokio-rs/tracing/pull/1335 +[#1331]: https://github.com/tokio-rs/tracing/pull/1331 + +# 0.1.25 (February 23, 2021) + +### Added + +- `Span::entered` method for entering a span and moving it into a guard by value + rather than borrowing it ([#1252]) + +Thanks to @matklad for contributing to this release! + +[#1252]: https://github.com/tokio-rs/tracing/pull/1252 + +# 0.1.24 (February 17, 2021) + +### Fixed + +- **attributes**: Compiler error when using `#[instrument(err)]` on functions + which return `impl Trait` ([#1236]) +- Fixed broken match arms in event macros ([#1239]) +- Documentation improvements ([#1232]) + +Thanks to @bkchr and @lfranke for contributing to this release! + +[#1236]: https://github.com/tokio-rs/tracing/pull/1236 +[#1239]: https://github.com/tokio-rs/tracing/pull/1239 +[#1232]: https://github.com/tokio-rs/tracing/pull/1232 + +# 0.1.23 (February 4, 2021) + +### Fixed + +- **attributes**: Compiler error when using `#[instrument(err)]` on functions + with mutable parameters ([#1167]) +- **attributes**: Missing function visibility modifier when using + `#[instrument]` with `async-trait` ([#977]) +- **attributes** Removed unused `syn` features ([#928]) +- **log**: Fixed an issue where the `tracing` macros would generate code for + events whose levels are disabled statically by the `log` crate's + `static_max_level_XXX` features ([#1175]) +- Fixed deprecations and clippy lints ([#1195]) +- Several documentation fixes and improvements ([#941], [#965], [#981], [#1146], + [#1215]) + +### Changed + +- **attributes**: `tracing-futures` dependency is no longer required when using + `#[instrument]` on async functions ([#808]) +- **attributes**: Updated `tracing-attributes` minimum dependency to v0.1.12 + ([#1222]) + +Thanks to @nagisa, @Txuritan, @TaKO8Ki, @okready, and @krojew for contributing +to this release! + +[#1167]: https://github.com/tokio-rs/tracing/pull/1167 +[#977]: https://github.com/tokio-rs/tracing/pull/977 +[#965]: https://github.com/tokio-rs/tracing/pull/965 +[#981]: https://github.com/tokio-rs/tracing/pull/981 +[#1215]: https://github.com/tokio-rs/tracing/pull/1215 +[#808]: https://github.com/tokio-rs/tracing/pull/808 +[#941]: https://github.com/tokio-rs/tracing/pull/941 +[#1146]: https://github.com/tokio-rs/tracing/pull/1146 +[#1175]: https://github.com/tokio-rs/tracing/pull/1175 +[#1195]: https://github.com/tokio-rs/tracing/pull/1195 +[#1222]: https://github.com/tokio-rs/tracing/pull/1222 + +# 0.1.22 (November 23, 2020) + +### Changed + +- Updated `pin-project-lite` dependency to 0.2 ([#1108]) + +[#1108]: https://github.com/tokio-rs/tracing/pull/1108 + +# 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/Cargo.toml b/Cargo.toml new file mode 100644 index 0000000..90f084d --- /dev/null +++ b/Cargo.toml @@ -0,0 +1,142 @@ +# 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 are reading this file be aware that the original Cargo.toml +# will likely look very different (and much more reasonable). +# See Cargo.toml.orig for the original contents. + +[package] +edition = "2018" +rust-version = "1.49.0" +name = "tracing" +version = "0.1.37" +authors = [ + "Eliza Weisman <eliza@buoyant.io>", + "Tokio Contributors <team@tokio.rs>", +] +description = """ +Application-level tracing for Rust. +""" +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", + "--cfg", + "tracing_unstable", +] +rustc-args = [ + "--cfg", + "tracing_unstable", +] + +[[bench]] +name = "baseline" +harness = false + +[[bench]] +name = "dispatch_get_clone" +harness = false + +[[bench]] +name = "dispatch_get_ref" +harness = false + +[[bench]] +name = "empty_span" +harness = false + +[[bench]] +name = "enter_span" +harness = false + +[[bench]] +name = "event" +harness = false + +[[bench]] +name = "span_fields" +harness = false + +[[bench]] +name = "span_no_fields" +harness = false + +[[bench]] +name = "span_repeated" +harness = false + +[dependencies.cfg-if] +version = "1.0.0" + +[dependencies.log] +version = "0.4.17" +optional = true + +[dependencies.pin-project-lite] +version = "0.2.9" + +[dependencies.tracing-attributes] +version = "0.1.23" +optional = true + +[dependencies.tracing-core] +version = "0.1.30" +default-features = false + +[dev-dependencies.criterion] +version = "0.3.6" +default-features = false + +[dev-dependencies.log] +version = "0.4.17" + +[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"] +valuable = ["tracing-core/valuable"] + +[target."cfg(target_arch = \"wasm32\")".dev-dependencies.wasm-bindgen-test] +version = "^0.3" + +[badges.maintenance] +status = "actively-developed" diff --git a/Cargo.toml.orig b/Cargo.toml.orig new file mode 100644 index 0000000..313c337 --- /dev/null +++ b/Cargo.toml.orig @@ -0,0 +1,115 @@ +[package] +name = "tracing" +# When releasing to crates.io: +# - Remove path dependencies +# - Update html_root_url. +# - Update doc url +# - Cargo.toml +# - README.md +# - Update CHANGELOG.md. +# - Create "v0.1.x" git tag +version = "0.1.37" +authors = ["Eliza Weisman <eliza@buoyant.io>", "Tokio Contributors <team@tokio.rs>"] +license = "MIT" +readme = "README.md" +repository = "https://github.com/tokio-rs/tracing" +homepage = "https://tokio.rs" +description = """ +Application-level tracing for Rust. +""" +categories = [ + "development-tools::debugging", + "development-tools::profiling", + "asynchronous", + "no-std", +] +keywords = ["logging", "tracing", "metrics", "async"] +edition = "2018" +rust-version = "1.49.0" + +[dependencies] +tracing-core = { path = "../tracing-core", version = "0.1.30", default-features = false } +log = { version = "0.4.17", optional = true } +tracing-attributes = { path = "../tracing-attributes", version = "0.1.23", optional = true } +cfg-if = "1.0.0" +pin-project-lite = "0.2.9" + +[dev-dependencies] +criterion = { version = "0.3.6", default-features = false } +log = "0.4.17" +tracing-mock = { path = "../tracing-mock" } + +[target.'cfg(target_arch = "wasm32")'.dev-dependencies] +wasm-bindgen-test = "^0.3" + +[features] +default = ["std", "attributes"] + +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 = [] + +# This feature flag is no longer necessary. +async-await = [] + +std = ["tracing-core/std"] +log-always = ["log"] +attributes = ["tracing-attributes"] +valuable = ["tracing-core/valuable"] + +[[bench]] +name = "baseline" +harness = false + +[[bench]] +name = "dispatch_get_clone" +harness = false + +[[bench]] +name = "dispatch_get_ref" +harness = false + +[[bench]] +name = "empty_span" +harness = false + +[[bench]] +name = "enter_span" +harness = false + +[[bench]] +name = "event" +harness = false + +[[bench]] +name = "span_fields" +harness = false + +[[bench]] +name = "span_no_fields" +harness = false + +[[bench]] +name = "span_repeated" +harness = false + +[badges] +maintenance = { status = "actively-developed" } + +[package.metadata.docs.rs] +all-features = true +# enable unstable features in the documentation +rustdoc-args = ["--cfg", "docsrs", "--cfg", "tracing_unstable"] +# it's necessary to _also_ pass `--cfg tracing_unstable` to rustc, or else +# dependencies will not be enabled, and the docs build will fail. +rustc-args = ["--cfg", "tracing_unstable"] @@ -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/METADATA b/METADATA new file mode 100644 index 0000000..6047baa --- /dev/null +++ b/METADATA @@ -0,0 +1,19 @@ +name: "tracing" +description: "A scoped, structured logging and diagnostics system." +third_party { + url { + type: HOMEPAGE + value: "https://crates.io/crates/tracing" + } + url { + type: ARCHIVE + value: "https://static.crates.io/crates/tracing/tracing-0.1.37.crate" + } + version: "0.1.37" + license_type: NOTICE + last_upgrade_date { + year: 2023 + month: 3 + day: 3 + } +} diff --git a/MODULE_LICENSE_MIT b/MODULE_LICENSE_MIT new file mode 100644 index 0000000..e69de29 --- /dev/null +++ b/MODULE_LICENSE_MIT @@ -0,0 +1 @@ +include platform/prebuilts/rust:master:/OWNERS diff --git a/README.md b/README.md new file mode 100644 index 0000000..6947345 --- /dev/null +++ b/README.md @@ -0,0 +1,465 @@ +![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 +[docs-badge]: https://docs.rs/tracing/badge.svg +[docs-url]: https://docs.rs/tracing +[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.49+][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.3/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_subscriber::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).entered(); + + 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, avoid using the `Span::enter` method. The following example +_will not_ work: + +```rust +async { + let _s = span.enter(); + // ... +} +``` +```rust +async { + let _s = tracing::span!(...).entered(); + // ... +} +``` + +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.37/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.37/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.42. 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-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. +- [`tracing-elastic-apm`] provides a layer for reporting traces to [Elastic APM]. +- [`tracing-etw`] provides a layer for emitting Windows [ETW] events. +- [`tracing-fluent-assertions`] provides a fluent assertions-style testing + framework for validating the behavior of `tracing` spans. +- [`sentry-tracing`] provides a layer for reporting events and traces to [Sentry]. +- [`tracing-loki`] provides a layer for shipping logs to [Grafana Loki]. +- [`tracing-logfmt`] provides a layer that formats events and spans into the logfmt format. + +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-log`]: https://crates.io/crates/test-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 +[`tracing-elastic-apm`]: https://crates.io/crates/tracing-elastic-apm +[Elastic APM]: https://www.elastic.co/apm +[`tracing-etw`]: https://github.com/microsoft/tracing-etw +[ETW]: https://docs.microsoft.com/en-us/windows/win32/etw/about-event-tracing +[`tracing-fluent-assertions`]: https://crates.io/crates/tracing-fluent-assertions +[`sentry-tracing`]: https://crates.io/crates/sentry-tracing +[Sentry]: https://sentry.io/welcome/ +[`tracing-loki`]: https://crates.io/crates/tracing-loki +[Grafana Loki]: https://grafana.com/oss/loki/ +[`tracing-logfmt`]: https://crates.io/crates/tracing-logfmt + +**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.49. 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/benches/baseline.rs b/benches/baseline.rs new file mode 100644 index 0000000..93c14f4 --- /dev/null +++ b/benches/baseline.rs @@ -0,0 +1,24 @@ +use criterion::{black_box, criterion_group, criterion_main, Criterion}; + +fn bench(c: &mut Criterion) { + use std::sync::atomic::{AtomicUsize, Ordering}; + + let mut group = c.benchmark_group("comparison"); + 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(); +} + +criterion_group!(benches, bench); +criterion_main!(benches); diff --git a/benches/dispatch_get_clone.rs b/benches/dispatch_get_clone.rs new file mode 100644 index 0000000..15577c6 --- /dev/null +++ b/benches/dispatch_get_clone.rs @@ -0,0 +1,15 @@ +use criterion::{black_box, criterion_group, criterion_main, Criterion}; + +mod shared; + +fn bench(c: &mut Criterion) { + shared::for_all_dispatches(&mut c.benchmark_group("Dispatch::get_clone"), |b| { + b.iter(|| { + let current = tracing::dispatcher::get_default(|current| current.clone()); + black_box(current); + }) + }); +} + +criterion_group!(benches, bench); +criterion_main!(benches); diff --git a/benches/dispatch_get_ref.rs b/benches/dispatch_get_ref.rs new file mode 100644 index 0000000..a59c343 --- /dev/null +++ b/benches/dispatch_get_ref.rs @@ -0,0 +1,16 @@ +use criterion::{black_box, criterion_group, criterion_main, Criterion}; + +mod shared; + +fn bench(c: &mut Criterion) { + shared::for_all_dispatches(&mut c.benchmark_group("Dispatch::get_ref"), |b| { + b.iter(|| { + tracing::dispatcher::get_default(|current| { + black_box(¤t); + }) + }) + }); +} + +criterion_group!(benches, bench); +criterion_main!(benches); diff --git a/benches/empty_span.rs b/benches/empty_span.rs new file mode 100644 index 0000000..fb38b08 --- /dev/null +++ b/benches/empty_span.rs @@ -0,0 +1,43 @@ +use criterion::{black_box, criterion_group, criterion_main, Criterion}; + +mod shared; + +fn bench(c: &mut Criterion) { + let mut group = c.benchmark_group("empty_span"); + shared::for_all_dispatches(&mut group, |b| { + b.iter(|| { + let span = tracing::span::Span::none(); + black_box(&span); + }) + }); + group.bench_function("baseline_struct", |b| { + b.iter(|| { + let span = FakeEmptySpan::new(); + black_box(&span); + }) + }); +} + +struct FakeEmptySpan { + inner: Option<(usize, std::sync::Arc<()>)>, + meta: Option<&'static ()>, +} + +impl FakeEmptySpan { + fn new() -> Self { + Self { + inner: None, + meta: None, + } + } +} + +impl Drop for FakeEmptySpan { + fn drop(&mut self) { + black_box(&self.inner); + black_box(&self.meta); + } +} + +criterion_group!(benches, bench); +criterion_main!(benches); diff --git a/benches/enter_span.rs b/benches/enter_span.rs new file mode 100644 index 0000000..757350a --- /dev/null +++ b/benches/enter_span.rs @@ -0,0 +1,16 @@ +use criterion::{criterion_group, criterion_main, Criterion}; +use tracing::{span, Level}; + +mod shared; + +fn bench(c: &mut Criterion) { + shared::for_all_dispatches(&mut c.benchmark_group("enter_span"), |b| { + let span = span!(Level::TRACE, "span"); + b.iter(|| { + let _span = span.enter(); + }) + }); +} + +criterion_group!(benches, bench); +criterion_main!(benches); diff --git a/benches/event.rs b/benches/event.rs new file mode 100644 index 0000000..1649325 --- /dev/null +++ b/benches/event.rs @@ -0,0 +1,12 @@ +use criterion::{criterion_group, criterion_main, Criterion}; + +mod shared; + +fn bench(c: &mut Criterion) { + shared::for_all_recording(&mut c.benchmark_group("event"), |b| { + b.iter(|| tracing::info!("hello world!")) + }); +} + +criterion_group!(benches, bench); +criterion_main!(benches); diff --git a/benches/shared.rs b/benches/shared.rs new file mode 100644 index 0000000..56508c4 --- /dev/null +++ b/benches/shared.rs @@ -0,0 +1,160 @@ +#![allow(dead_code)] +use criterion::{black_box, measurement::WallTime, Bencher}; +use tracing::{field, span, Event, Id, Metadata}; + +use std::{ + fmt::{self, Write}, + sync::{Mutex, MutexGuard}, +}; + +pub fn for_all_recording( + group: &mut criterion::BenchmarkGroup<'_, WallTime>, + mut iter: impl FnMut(&mut Bencher<'_, WallTime>), +) { + // first, run benchmarks with no subscriber + group.bench_function("none", &mut iter); + + // then, run benchmarks with a scoped default subscriber + tracing::subscriber::with_default(EnabledSubscriber, || { + group.bench_function("scoped", &mut iter) + }); + + let subscriber = VisitingSubscriber(Mutex::new(String::from(""))); + tracing::subscriber::with_default(subscriber, || { + group.bench_function("scoped_recording", &mut iter); + }); + + // finally, set a global default subscriber, and run the benchmarks again. + tracing::subscriber::set_global_default(EnabledSubscriber) + .expect("global default should not have already been set!"); + let _ = log::set_logger(&NOP_LOGGER); + log::set_max_level(log::LevelFilter::Trace); + group.bench_function("global", &mut iter); +} + +pub fn for_all_dispatches( + group: &mut criterion::BenchmarkGroup<'_, WallTime>, + mut iter: impl FnMut(&mut Bencher<'_, WallTime>), +) { + // first, run benchmarks with no subscriber + group.bench_function("none", &mut iter); + + // then, run benchmarks with a scoped default subscriber + tracing::subscriber::with_default(EnabledSubscriber, || { + group.bench_function("scoped", &mut iter) + }); + + // finally, set a global default subscriber, and run the benchmarks again. + tracing::subscriber::set_global_default(EnabledSubscriber) + .expect("global default should not have already been set!"); + let _ = log::set_logger(&NOP_LOGGER); + log::set_max_level(log::LevelFilter::Trace); + group.bench_function("global", &mut iter); +} + +const NOP_LOGGER: NopLogger = NopLogger; + +struct NopLogger; + +impl log::Log for NopLogger { + fn enabled(&self, _metadata: &log::Metadata) -> bool { + true + } + + fn log(&self, record: &log::Record) { + if self.enabled(record.metadata()) { + let mut this = self; + let _ = write!(this, "{}", record.args()); + } + } + + fn flush(&self) {} +} + +impl Write for &NopLogger { + fn write_str(&mut self, s: &str) -> std::fmt::Result { + black_box(s); + Ok(()) + } +} + +/// 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) { + 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; + } +} + +/// 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; + } +} diff --git a/benches/span_fields.rs b/benches/span_fields.rs new file mode 100644 index 0000000..5ad8289 --- /dev/null +++ b/benches/span_fields.rs @@ -0,0 +1,23 @@ +use criterion::{criterion_group, criterion_main, Criterion}; +use tracing::{span, Level}; + +mod shared; + +fn bench(c: &mut Criterion) { + shared::for_all_recording(&mut c.benchmark_group("span_fields"), |b| { + b.iter(|| { + let span = span!( + Level::TRACE, + "span", + foo = "foo", + bar = "bar", + baz = 3, + quuux = tracing::field::debug(0.99) + ); + criterion::black_box(span) + }) + }); +} + +criterion_group!(benches, bench); +criterion_main!(benches); diff --git a/benches/span_no_fields.rs b/benches/span_no_fields.rs new file mode 100644 index 0000000..8a1ff6e --- /dev/null +++ b/benches/span_no_fields.rs @@ -0,0 +1,13 @@ +use criterion::{criterion_group, criterion_main, Criterion}; +use tracing::{span, Level}; + +mod shared; + +fn bench(c: &mut Criterion) { + shared::for_all_recording(&mut c.benchmark_group("span_no_fields"), |b| { + b.iter(|| span!(Level::TRACE, "span")) + }); +} + +criterion_group!(benches, bench); +criterion_main!(benches); diff --git a/benches/span_repeated.rs b/benches/span_repeated.rs new file mode 100644 index 0000000..4c6ac40 --- /dev/null +++ b/benches/span_repeated.rs @@ -0,0 +1,20 @@ +use criterion::{black_box, criterion_group, criterion_main, Criterion}; +use tracing::{span, Level}; + +mod shared; + +fn bench(c: &mut Criterion) { + shared::for_all_recording(&mut c.benchmark_group("span_repeated"), |b| { + let n = black_box(N_SPANS); + b.iter(|| (0..n).fold(mk_span(0), |_, i| mk_span(i as u64))) + }); +} + +#[inline] +fn mk_span(i: u64) -> tracing::Span { + span!(Level::TRACE, "span", i = i) +} + +const N_SPANS: usize = 100; +criterion_group!(benches, bench); +criterion_main!(benches); diff --git a/src/dispatcher.rs b/src/dispatcher.rs new file mode 100644 index 0000000..a84b99f --- /dev/null +++ b/src/dispatcher.rs @@ -0,0 +1,145 @@ +//! 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 +//! ``` +//! +//! <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> +//! +//! ## 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`]: crate::Subscriber +#[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, WeakDispatch, +}; + +/// 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/src/field.rs b/src/field.rs new file mode 100644 index 0000000..b3f9fbd --- /dev/null +++ b/src/field.rs @@ -0,0 +1,170 @@ +//! `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`, `f64`, `bool`, and `&str`) or using a `fmt::Display` or +//! `fmt::Debug` implementation. `Subscriber`s are provided these primitive +//! value types as `dyn Value` trait objects. +//! +//! These trait objects can be formatted using `fmt::Debug`, but may also be +//! recorded as typed data by calling the [`Value::record`] method on these +//! trait objects with a _visitor_ implementing the [`Visit`] trait. This trait +//! represents the behavior used to record values of various types. For example, +//! an implementation of `Visit` might record integers by incrementing counters +//! for their field names rather than printing them. +//! +//! +//! # Using `valuable` +//! +//! `tracing`'s [`Value`] trait is intentionally minimalist: it supports only a small +//! number of Rust primitives as typed values, and only permits recording +//! user-defined types with their [`fmt::Debug`] or [`fmt::Display`] +//! implementations. However, there are some cases where it may be useful to record +//! nested values (such as arrays, `Vec`s, or `HashMap`s containing values), or +//! user-defined `struct` and `enum` types without having to format them as +//! unstructured text. +//! +//! To address `Value`'s limitations, `tracing` offers experimental support for +//! the [`valuable`] crate, which provides object-safe inspection of structured +//! values. User-defined types can implement the [`valuable::Valuable`] trait, +//! and be recorded as a `tracing` field by calling their [`as_value`] method. +//! If the [`Subscriber`] also supports the `valuable` crate, it can +//! then visit those types fields as structured values using `valuable`. +//! +//! <pre class="ignore" style="white-space:normal;font:inherit;"> +//! <strong>Note</strong>: <code>valuable</code> support is an +//! <a href = "../index.html#unstable-features">unstable feature</a>. See +//! the documentation on unstable features for details on how to enable it. +//! </pre> +//! +//! For example: +//! ```ignore +//! // Derive `Valuable` for our types: +//! use valuable::Valuable; +//! +//! #[derive(Clone, Debug, Valuable)] +//! struct User { +//! name: String, +//! age: u32, +//! address: Address, +//! } +//! +//! #[derive(Clone, Debug, Valuable)] +//! struct Address { +//! country: String, +//! city: String, +//! street: String, +//! } +//! +//! let user = User { +//! name: "Arwen Undomiel".to_string(), +//! age: 3000, +//! address: Address { +//! country: "Middle Earth".to_string(), +//! city: "Rivendell".to_string(), +//! street: "leafy lane".to_string(), +//! }, +//! }; +//! +//! // Recording `user` as a `valuable::Value` will allow the `tracing` subscriber +//! // to traverse its fields as a nested, typed structure: +//! tracing::info!(current_user = user.as_value()); +//! ``` +//! +//! Alternatively, the [`valuable()`] function may be used to convert a type +//! implementing [`Valuable`] into a `tracing` field value. +//! +//! When the `valuable` feature is enabled, the [`Visit`] trait will include an +//! optional [`record_value`] method. `Visit` implementations that wish to +//! record `valuable` values can implement this method with custom behavior. +//! If a visitor does not implement `record_value`, the [`valuable::Value`] will +//! be forwarded to the visitor's [`record_debug`] method. +//! +//! [`fmt::Debug`]: std::fmt::Debug +//! [`fmt::Display`]: std::fmt::Debug +//! [`valuable`]: https://crates.io/crates/valuable +//! [`valuable::Valuable`]: https://docs.rs/valuable/latest/valuable/trait.Valuable.html +//! [`as_value`]: https://docs.rs/valuable/latest/valuable/trait.Valuable.html#tymethod.as_value +//! [`valuable::Value`]: https://docs.rs/valuable/latest/valuable/enum.Value.html +//! [`Subscriber`]: crate::Subscriber +//! [`record_value`]: Visit::record_value +//! [`record_debug`]: Visit::record_debug +//! [span]: mod@crate::span +//! [`Event`]: crate::event::Event +//! [`Metadata`]: crate::Metadata +//! [`Attributes`]: crate::span::Attributes +//! [`Record`]: crate::span::Record +//! [`new_span`]: crate::Subscriber::new_span +//! [`record`]: crate::Subscriber::record +//! [`event`]: crate::Subscriber::event +pub use tracing_core::field::*; + +use crate::Metadata; + +/// Trait implemented to allow a type to be used as a field key. +/// +/// <pre class="ignore" style="white-space:normal;font:inherit;"> +/// <strong>Note</strong>: Although this is implemented for both the +/// <a href="./struct.Field.html"><code>Field</code></a> type <em>and</em> any +/// type that can be borrowed as an <code>&str</code>, only <code>Field</code> +/// allows <em>O</em>(1) access. +/// Indexing a field with a string results in an iterative search that performs +/// string comparisons. Thus, if possible, once the key for a field is known, it +/// should be used whenever possible. +/// </pre> +pub trait AsField: crate::sealed::Sealed { + /// Attempts to convert `&self` into a `Field` with the specified `metadata`. + /// + /// If `metadata` defines this field, then the field is returned. Otherwise, + /// this returns `None`. + fn as_field(&self, metadata: &Metadata<'_>) -> Option<Field>; +} + +// ===== impl AsField ===== + +impl AsField for Field { + #[inline] + fn as_field(&self, metadata: &Metadata<'_>) -> Option<Field> { + if self.callsite() == metadata.callsite() { + Some(self.clone()) + } else { + None + } + } +} + +impl<'a> AsField for &'a Field { + #[inline] + fn as_field(&self, metadata: &Metadata<'_>) -> Option<Field> { + if self.callsite() == metadata.callsite() { + Some((*self).clone()) + } else { + None + } + } +} + +impl AsField for str { + #[inline] + fn as_field(&self, metadata: &Metadata<'_>) -> Option<Field> { + metadata.fields().field(&self) + } +} + +impl crate::sealed::Sealed for Field {} +impl<'a> crate::sealed::Sealed for &'a Field {} +impl crate::sealed::Sealed for str {} diff --git a/src/instrument.rs b/src/instrument.rs new file mode 100644 index 0000000..46e5f57 --- /dev/null +++ b/src/instrument.rs @@ -0,0 +1,370 @@ +use crate::stdlib::pin::Pin; +use crate::stdlib::task::{Context, Poll}; +use crate::stdlib::{future::Future, marker::Sized}; +use crate::{ + dispatcher::{self, Dispatch}, + span::Span, +}; +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]: super::Span +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 + /// # } + /// ``` + /// + /// The [`Span::or_current`] combinator can be used in combination with + /// `instrument` to ensure that the [current span] is attached to the + /// future if the span passed to `instrument` is [disabled]: + /// + /// ``` + /// use tracing::Instrument; + /// # mod tokio { + /// # pub(super) fn spawn(_: impl std::future::Future) {} + /// # } + /// + /// let my_future = async { + /// // ... + /// }; + /// + /// let outer_span = tracing::info_span!("outer").entered(); + /// + /// // If the "my_future" span is enabled, then the spawned task will + /// // be within both "my_future" *and* "outer", since "outer" is + /// // "my_future"'s parent. However, if "my_future" is disabled, + /// // the spawned task will *not* be in any span. + /// tokio::spawn( + /// my_future + /// .instrument(tracing::debug_span!("my_future")) + /// ); + /// + /// // Using `Span::or_current` ensures the spawned task is instrumented + /// // with the current span, if the new span passed to `instrument` is + /// // not enabled. This means that if the "my_future" span is disabled, + /// // the spawned task will still be instrumented with the "outer" span: + /// # let my_future = async {}; + /// tokio::spawn( + /// my_future + /// .instrument(tracing::debug_span!("my_future").or_current()) + /// ); + /// ``` + /// + /// [entered]: super::Span::enter() + /// [`Span::or_current`]: super::Span::or_current() + /// [current span]: super::Span::current() + /// [disabled]: super::Span::is_disabled() + /// [`Future`]: std::future::Future + fn instrument(self, span: Span) -> Instrumented<Self> { + Instrumented { inner: self, span } + } + + /// Instruments this type with the [current] [`Span`], returning an + /// `Instrumented` wrapper. + /// + /// The attached [`Span`] will be [entered] every time the instrumented + /// [`Future`] is polled. + /// + /// This can be used to propagate the current span when spawning a new future. + /// + /// # Examples + /// + /// ```rust + /// use tracing::Instrument; + /// + /// # mod tokio { + /// # pub(super) fn spawn(_: impl std::future::Future) {} + /// # } + /// # 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]: super::Span::current() + /// [entered]: super::Span::enter() + /// [`Span`]: crate::Span + /// [`Future`]: std::future::Future + #[inline] + fn in_current_span(self) -> Instrumented<Self> { + self.instrument(Span::current()) + } +} + +/// Extension trait allowing futures to be instrumented with +/// a `tracing` [`Subscriber`](crate::Subscriber). +#[cfg_attr(docsrs, doc(cfg(feature = "std")))] +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. + /// + /// # Examples + /// + /// ``` + /// # use tracing::subscriber::NoSubscriber as MySubscriber; + /// # use tracing::subscriber::NoSubscriber as MyOtherSubscriber; + /// # async fn docs() { + /// use tracing::instrument::WithSubscriber; + /// + /// // Set the default `Subscriber` + /// let _default = tracing::subscriber::set_default(MySubscriber::default()); + /// + /// tracing::info!("this event will be recorded by the default `Subscriber`"); + /// + /// // Create a different `Subscriber` and attach it to a future. + /// let other_subscriber = MyOtherSubscriber::default(); + /// let future = async { + /// tracing::info!("this event will be recorded by the other `Subscriber`"); + /// // ... + /// }; + /// + /// future + /// // Attach the other `Subscriber` to the future before awaiting it + /// .with_subscriber(other_subscriber) + /// .await; + /// + /// // Once the future has completed, we return to the default `Subscriber`. + /// tracing::info!("this event will be recorded by the default `Subscriber`"); + /// # } + /// ``` + /// + /// [`Subscriber`]: super::Subscriber + /// [default]: crate::dispatcher#setting-the-default-subscriber + /// [`Future`]: std::future::Future + fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self> + where + S: Into<Dispatch>, + { + WithDispatch { + inner: self, + dispatcher: subscriber.into(), + } + } + + /// Attaches the current [default] [`Subscriber`] to this type, returning a + /// [`WithDispatch`] wrapper. + /// + /// The attached `Subscriber` will be set as the [default] when the returned + /// [`Future`] is polled. + /// + /// This can be used to propagate the current dispatcher context when + /// spawning a new future that may run on a different thread. + /// + /// # Examples + /// + /// ``` + /// # mod tokio { + /// # pub(super) fn spawn(_: impl std::future::Future) {} + /// # } + /// # use tracing::subscriber::NoSubscriber as MySubscriber; + /// # async fn docs() { + /// use tracing::instrument::WithSubscriber; + /// + /// // Using `set_default` (rather than `set_global_default`) sets the + /// // default `Subscriber` for *this* thread only. + /// let _default = tracing::subscriber::set_default(MySubscriber::default()); + /// + /// let future = async { + /// // ... + /// }; + /// + /// // If a multi-threaded async runtime is in use, this spawned task may + /// // run on a different thread, in a different default `Subscriber`'s context. + /// tokio::spawn(future); + /// + /// // However, calling `with_current_subscriber` on the future before + /// // spawning it, ensures that the current thread's default `Subscriber` is + /// // propagated to the spawned task, regardless of where it executes: + /// # let future = async { }; + /// tokio::spawn(future.with_current_subscriber()); + /// # } + /// ``` + /// [`Subscriber`]: super::Subscriber + /// [default]: crate::dispatcher#setting-the-default-subscriber + /// [`Future`]: std::future::Future + #[inline] + fn with_current_subscriber(self) -> WithDispatch<Self> { + WithDispatch { + inner: self, + dispatcher: crate::dispatcher::get_default(|default| default.clone()), + } + } +} + +pin_project! { + /// A [`Future`] that has been instrumented with a `tracing` [`Subscriber`]. + /// + /// This type is returned by the [`WithSubscriber`] extension trait. See that + /// trait's documentation for details. + /// + /// [`Future`]: std::future::Future + /// [`Subscriber`]: crate::Subscriber + #[derive(Clone, Debug)] + #[must_use = "futures do nothing unless you `.await` or poll them"] + #[cfg_attr(docsrs, doc(cfg(feature = "std")))] + pub struct WithDispatch<T> { + #[pin] + inner: T, + dispatcher: Dispatch, + } +} + +pin_project! { + /// A [`Future`] that has been instrumented with a `tracing` [`Span`]. + /// + /// This type is returned by the [`Instrument`] extension trait. See that + /// trait's documentation for details. + /// + /// [`Future`]: std::future::Future + /// [`Span`]: crate::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 Instrumented === + +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 + } +} + +// === impl WithDispatch === + +#[cfg(feature = "std")] +#[cfg_attr(docsrs, doc(cfg(feature = "std")))] +impl<T: Future> Future for WithDispatch<T> { + type Output = T::Output; + + fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output> { + let this = self.project(); + let dispatcher = this.dispatcher; + let future = this.inner; + let _default = dispatcher::set_default(dispatcher); + future.poll(cx) + } +} + +#[cfg_attr(docsrs, doc(cfg(feature = "std")))] +impl<T: Sized> WithSubscriber for T {} + +#[cfg(feature = "std")] +#[cfg_attr(docsrs, doc(cfg(feature = "std")))] +impl<T> WithDispatch<T> { + /// Borrows the [`Dispatch`] that is entered when this type is polled. + pub fn dispatcher(&self) -> &Dispatch { + &self.dispatcher + } + + /// 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/src/level_filters.rs b/src/level_filters.rs new file mode 100644 index 0000000..44f5e5f --- /dev/null +++ b/src/level_filters.rs @@ -0,0 +1,94 @@ +//! 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"] } +//! ``` +//! ## Notes +//! +//! Please note that `tracing`'s static max level features do *not* control the +//! [`log`] records that may be emitted when [`tracing`'s "log" feature flag][f] is +//! enabled. This is to allow `tracing` to be disabled entirely at compile time +//! while still emitting `log` records --- such as when a library using +//! `tracing` is used by an application using `log` that doesn't want to +//! generate any `tracing`-related code, but does want to collect `log` records. +//! +//! This means that if the "log" feature is in use, some code may be generated +//! for `log` records emitted by disabled `tracing` events. If this is not +//! desirable, `log` records may be disabled separately using [`log`'s static +//! max level features][`log` crate]. +//! +//! [`log`]: https://docs.rs/log/ +//! [`log` crate]: https://docs.rs/log/latest/log/#compile-time-filters +//! [f]: https://docs.rs/tracing/latest/tracing/#emitting-log-records +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]: super#compile-time-filters +pub const STATIC_MAX_LEVEL: LevelFilter = MAX_LEVEL; + +cfg_if::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/src/lib.rs b/src/lib.rs new file mode 100644 index 0000000..342e04a --- /dev/null +++ b/src/lib.rs @@ -0,0 +1,1115 @@ +//! 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.49+][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="example-wrap" style="display:inline-block"><pre class="compile_fail" style="white-space:normal;font:inherit;"> +//! +//! **Warning**: In asynchronous code that uses async/await syntax, +//! `Span::enter` may produce incorrect traces if the returned drop +//! guard is held across an await point. See +//! [the method documentation][Span#in-asynchronous-code] 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" +//! ``` +//! +//! ## 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() {} +//! ``` +//! +//! For functions which don't have built-in tracing support and can't have +//! the `#[instrument]` attribute applied (such as from an external crate), +//! the [`Span` struct][`Span`] has a [`in_scope()` method][`in_scope`] +//! which can be used to easily wrap synchonous code in a span. +//! +//! For example: +//! ```rust +//! use tracing::info_span; +//! +//! # fn doc() -> Result<(), ()> { +//! # mod serde_json { +//! # pub(crate) fn from_slice(buf: &[u8]) -> Result<(), ()> { Ok(()) } +//! # } +//! # let buf: [u8; 0] = []; +//! let json = info_span!("json.parse").in_scope(|| serde_json::from_slice(&buf))?; +//! # let _ = json; // suppress unused variable warning +//! # Ok(()) +//! # } +//! ``` +//! +//! You can find more examples showing how to use this crate [here][examples]. +//! +//! [RAII]: https://github.com/rust-unofficial/patterns/blob/master/patterns/behavioural/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 as well as the `#[instrument]` attribute +//! 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 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]: Metadata::target +//! [parent span]: span::Attributes::parent +//! [determined contextually]: span::Attributes::is_contextual +//! [`fmt::Debug`]: std::fmt::Debug +//! [`fmt::Display`]: std::fmt::Display +//! [fmt]: std::fmt#usage +//! [`Empty`]: field::Empty +//! +//! ### 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!`]: span! +//! [`event!`]: event! +//! [`trace!`]: trace! +//! [`debug!`]: debug! +//! [`info!`]: info! +//! [`warn!`]: warn! +//! [`error!`]: error! +//! [`trace_span!`]: trace_span! +//! [`debug_span!`]: debug_span! +//! [`info_span!`]: info_span! +//! [`warn_span!`]: warn_span! +//! [`error_span!`]: error_span! +//! +//! ### 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).entered(); +//! +//! 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"); +//! # } +//! ``` +//! +//! <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> +//! +//! 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-web`] provides `tracing` integration for the `actix-web` web framework. +//! - [`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`)]. +//! - [`tracing-web`] provides a layer implementation of level-aware logging of events +//! to web browsers' `console.*` and span events to the [User Timing API (`window.performance`)]. +//! - [`tide-tracing`] provides a [tide] middleware to trace all incoming requests and responses. +//! - [`test-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. +//! - [`tracing-elastic-apm`] provides a layer for reporting traces to [Elastic APM]. +//! - [`tracing-etw`] provides a layer for emitting Windows [ETW] events. +//! - [`tracing-fluent-assertions`] provides a fluent assertions-style testing +//! framework for validating the behavior of `tracing` spans. +//! - [`sentry-tracing`] provides a layer for reporting events and traces to [Sentry]. +//! - [`tracing-forest`] provides a subscriber that preserves contextual coherence by +//! grouping together logs from the same spans during writing. +//! - [`tracing-loki`] provides a layer for shipping logs to [Grafana Loki]. +//! - [`tracing-logfmt`] provides a layer that formats events and spans into the logfmt format. +//! - [`reqwest-tracing`] provides a middleware to trace [`reqwest`] HTTP requests. +//! +//! 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-web`]: https://crates.io/crates/tracing-actix-web +//! [`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 +//! [`tracing-web`]: https://docs.rs/tracing-web +//! [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-log`]: https://crates.io/crates/test-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 +//! [`tracing-elastic-apm`]: https://crates.io/crates/tracing-elastic-apm +//! [Elastic APM]: https://www.elastic.co/apm +//! [`tracing-etw`]: https://github.com/microsoft/tracing-etw +//! [ETW]: https://docs.microsoft.com/en-us/windows/win32/etw/about-event-tracing +//! [`tracing-fluent-assertions`]: https://crates.io/crates/tracing-fluent-assertions +//! [`sentry-tracing`]: https://crates.io/crates/sentry-tracing +//! [Sentry]: https://sentry.io/welcome/ +//! [`tracing-forest`]: https://crates.io/crates/tracing-forest +//! [`tracing-loki`]: https://crates.io/crates/tracing-loki +//! [Grafana Loki]: https://grafana.com/oss/loki/ +//! [`tracing-logfmt`]: https://crates.io/crates/tracing-logfmt +//! [`reqwest-tracing`]: https://crates.io/crates/reqwest-tracing +//! [`reqwest`]: https://crates.io/crates/reqwest +//! +//! <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> +//! +//! ## 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.37", default-features = false } +//! ``` +//! +//! <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> +//! +//! ### Unstable Features +//! +//! These feature flags enable **unstable** features. The public API may break in 0.1.x +//! releases. To enable these features, the `--cfg tracing_unstable` must be passed to +//! `rustc` when compiling. +//! +//! The following unstable feature flags are currently available: +//! +//! * `valuable`: Enables support for recording [field values] using the +//! [`valuable`] crate. +//! +//! #### Enabling Unstable Features +//! +//! The easiest way to set the `tracing_unstable` cfg is to use the `RUSTFLAGS` +//! env variable when running `cargo` commands: +//! +//! ```shell +//! RUSTFLAGS="--cfg tracing_unstable" cargo build +//! ``` +//! Alternatively, the following can be added to the `.cargo/config` file in a +//! project to automatically enable the cfg flag for that project: +//! +//! ```toml +//! [build] +//! rustflags = ["--cfg", "tracing_unstable"] +//! ``` +//! +//! [feature flags]: https://doc.rust-lang.org/cargo/reference/manifest.html#the-features-section +//! [field values]: crate::field +//! [`valuable`]: https://crates.io/crates/valuable +//! +//! ## Supported Rust Versions +//! +//! Tracing is built against the latest stable release. The minimum supported +//! version is 1.49. 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#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(rustdoc::broken_intra_doc_links))] +#![doc(html_root_url = "https://docs.rs/tracing/0.1.37")] +#![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; + +// 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::{subscriber::Interest, Metadata}; + pub use core::concat; + + /// 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. + pub use tracing_core::callsite::DefaultCallsite as MacroCallsite; + + /// /!\ WARNING: This is *not* a stable API! /!\ + /// This function, 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 fn __is_enabled(meta: &Metadata<'static>, interest: Interest) -> bool { + interest.is_always() || crate::dispatcher::get_default(|default| default.enabled(meta)) + } + + /// /!\ WARNING: This is *not* a stable API! /!\ + /// This function, 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] + #[cfg(feature = "log")] + pub fn __disabled_span(meta: &'static Metadata<'static>) -> crate::Span { + crate::Span::new_disabled(meta) + } + + /// /!\ WARNING: This is *not* a stable API! /!\ + /// This function, 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] + #[cfg(not(feature = "log"))] + pub fn __disabled_span(_: &'static Metadata<'static>) -> crate::Span { + crate::Span::none() + } + + /// /!\ WARNING: This is *not* a stable API! /!\ + /// This function, 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. + #[cfg(feature = "log")] + pub fn __tracing_log( + meta: &Metadata<'static>, + logger: &'static dyn log::Log, + log_meta: log::Metadata<'_>, + values: &tracing_core::field::ValueSet<'_>, + ) { + logger.log( + &crate::log::Record::builder() + .file(meta.file()) + .module_path(meta.module_path()) + .line(meta.line()) + .metadata(log_meta) + .args(format_args!( + "{}", + crate::log::LogValueSet { + values, + is_first: true + } + )) + .build(), + ); + } +} + +#[cfg(feature = "log")] +#[doc(hidden)] +pub mod log { + use core::fmt; + pub use log::*; + use tracing_core::field::{Field, ValueSet, Visit}; + + /// Utility to format [`ValueSet`]s for logging. + pub(crate) struct LogValueSet<'a> { + pub(crate) values: &'a ValueSet<'a>, + pub(crate) is_first: bool, + } + + impl<'a> fmt::Display for LogValueSet<'a> { + #[inline] + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + struct LogVisitor<'a, 'b> { + f: &'a mut fmt::Formatter<'b>, + is_first: bool, + result: fmt::Result, + } + + impl Visit for LogVisitor<'_, '_> { + fn record_debug(&mut self, field: &Field, value: &dyn fmt::Debug) { + let res = if self.is_first { + self.is_first = false; + if field.name() == "message" { + write!(self.f, "{:?}", value) + } else { + write!(self.f, "{}={:?}", field.name(), value) + } + } else { + write!(self.f, " {}={:?}", field.name(), value) + }; + if let Err(err) = res { + self.result = self.result.and(Err(err)); + } + } + + fn record_str(&mut self, field: &Field, value: &str) { + if field.name() == "message" { + self.record_debug(field, &format_args!("{}", value)) + } else { + self.record_debug(field, &value) + } + } + } + + let mut visit = LogVisitor { + f, + is_first: self.is_first, + result: Ok(()), + }; + self.values.record(&mut visit); + visit.result + } + } +} + +mod sealed { + pub trait Sealed {} +} diff --git a/src/macros.rs b/src/macros.rs new file mode 100644 index 0000000..f3968e5 --- /dev/null +++ b/src/macros.rs @@ -0,0 +1,2504 @@ +/// Constructs a new span. +/// +/// See [the top-level documentation][lib] for details on the syntax accepted by +/// this macro. +/// +/// [lib]: crate#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::callsite::DefaultCallsite = $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() } + && $crate::__macro_support::__is_enabled(CALLSITE.metadata(), interest) + { + let meta = CALLSITE.metadata(); + // span with explicit parent + $crate::Span::child_of( + $parent, + meta, + &$crate::valueset!(meta.fields(), $($fields)*), + ) + } else { + let span = $crate::__macro_support::__disabled_span(CALLSITE.metadata()); + $crate::if_log_enabled! { $lvl, { + 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::callsite::DefaultCallsite = $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() } + && $crate::__macro_support::__is_enabled(CALLSITE.metadata(), interest) + { + let meta = CALLSITE.metadata(); + // span with contextual parent + $crate::Span::new( + meta, + &$crate::valueset!(meta.fields(), $($fields)*), + ) + } else { + let span = $crate::__macro_support::__disabled_span(CALLSITE.metadata()); + $crate::if_log_enabled! { $lvl, { + 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]: crate#using-the-macros +/// [attributes]: crate#configuring-attributes +/// [Fields]: crate#recording-fields +/// [`span!`]: crate::span! +/// +/// # 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]: crate#using-the-macros +/// [attributes]: crate#configuring-attributes +/// [Fields]: crate#recording-fields +/// [`span!`]: crate::span! +/// +/// # 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]: crate#using-the-macros +/// [attributes]: crate#configuring-attributes +/// [Fields]: crate#recording-fields +/// [`span!`]: crate::span! +/// +/// # 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]: crate#using-the-macros +/// [attributes]: crate#configuring-attributes +/// [Fields]: crate#recording-fields +/// [`span!`]: crate::span! +/// +/// # 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]: crate#using-the-macros +/// [attributes]: crate#configuring-attributes +/// [Fields]: crate#recording-fields +/// [`span!`]: crate::span! +/// +/// # 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]: crate#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 +// /// # use tracing::{Level, event}; +// /// # 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)* } )=> ({ + use $crate::__macro_support::Callsite as _; + static CALLSITE: $crate::callsite::DefaultCallsite = $crate::callsite2! { + name: $crate::__macro_support::concat!( + "event ", + file!(), + ":", + line!() + ), + kind: $crate::metadata::Kind::EVENT, + target: $target, + level: $lvl, + fields: $($fields)* + }; + + let enabled = $crate::level_enabled!($lvl) && { + let interest = CALLSITE.interest(); + !interest.is_never() && $crate::__macro_support::__is_enabled(CALLSITE.metadata(), interest) + }; + if enabled { + (|value_set: $crate::field::ValueSet| { + $crate::__tracing_log!( + $lvl, + CALLSITE, + &value_set + ); + let meta = CALLSITE.metadata(); + // event with explicit parent + $crate::Event::child_of( + $parent, + meta, + &value_set + ); + })($crate::valueset!(CALLSITE.metadata().fields(), $($fields)*)); + } else { + $crate::__tracing_log!( + $lvl, + CALLSITE, + &$crate::valueset!(CALLSITE.metadata().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)* } )=> ({ + use $crate::__macro_support::Callsite as _; + static CALLSITE: $crate::callsite::DefaultCallsite = $crate::callsite2! { + name: $crate::__macro_support::concat!( + "event ", + file!(), + ":", + line!() + ), + kind: $crate::metadata::Kind::EVENT, + target: $target, + level: $lvl, + fields: $($fields)* + }; + let enabled = $crate::level_enabled!($lvl) && { + let interest = CALLSITE.interest(); + !interest.is_never() && $crate::__macro_support::__is_enabled(CALLSITE.metadata(), interest) + }; + if enabled { + (|value_set: $crate::field::ValueSet| { + let meta = CALLSITE.metadata(); + // event with contextual parent + $crate::Event::dispatch( + meta, + &value_set + ); + $crate::__tracing_log!( + $lvl, + CALLSITE, + &value_set + ); + })($crate::valueset!(CALLSITE.metadata().fields(), $($fields)*)); + } else { + $crate::__tracing_log!( + $lvl, + CALLSITE, + &$crate::valueset!(CALLSITE.metadata().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, $($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)+ }) + ); +} + +/// Tests whether an event with the specified level and target would be enabled. +/// +/// This is similar to [`enabled!`], but queries the current subscriber specifically for +/// an event, whereas [`enabled!`] queries for an event _or_ span. +/// +/// See the documentation for [`enabled!]` for more details on using this macro. +/// See also [`span_enabled!`]. +/// +/// # Examples +/// +/// ```rust +/// # use tracing::{event_enabled, Level}; +/// if event_enabled!(target: "my_crate", Level::DEBUG) { +/// // some expensive work... +/// } +/// // simpler +/// if event_enabled!(Level::DEBUG) { +/// // some expensive work... +/// } +/// // with fields +/// if event_enabled!(Level::DEBUG, foo_field) { +/// // some expensive work... +/// } +/// ``` +/// +/// [`enabled!`]: crate::enabled +/// [`span_enabled!`]: crate::span_enabled +#[macro_export] +macro_rules! event_enabled { + ($($rest:tt)*)=> ( + $crate::enabled!(kind: $crate::metadata::Kind::EVENT, $($rest)*) + ) +} + +/// Tests whether a span with the specified level and target would be enabled. +/// +/// This is similar to [`enabled!`], but queries the current subscriber specifically for +/// an event, whereas [`enabled!`] queries for an event _or_ span. +/// +/// See the documentation for [`enabled!]` for more details on using this macro. +/// See also [`span_enabled!`]. +/// +/// # Examples +/// +/// ```rust +/// # use tracing::{span_enabled, Level}; +/// if span_enabled!(target: "my_crate", Level::DEBUG) { +/// // some expensive work... +/// } +/// // simpler +/// if span_enabled!(Level::DEBUG) { +/// // some expensive work... +/// } +/// // with fields +/// if span_enabled!(Level::DEBUG, foo_field) { +/// // some expensive work... +/// } +/// ``` +/// +/// [`enabled!`]: crate::enabled +/// [`span_enabled!`]: crate::span_enabled +#[macro_export] +macro_rules! span_enabled { + ($($rest:tt)*)=> ( + $crate::enabled!(kind: $crate::metadata::Kind::SPAN, $($rest)*) + ) +} + +/// Checks whether a span or event is [enabled] based on the provided [metadata]. +/// +/// [enabled]: crate::Subscriber::enabled +/// [metadata]: crate::Metadata +/// +/// This macro is a specialized tool: it is intended to be used prior +/// to an expensive computation required *just* for that event, but +/// *cannot* be done as part of an argument to that event, such as +/// when multiple events are emitted (e.g., iterating over a collection +/// and emitting an event for each item). +/// +/// # Usage +/// +/// [Subscribers] can make filtering decisions based all the data included in a +/// span or event's [`Metadata`]. This means that it is possible for `enabled!` +/// to return a _false positive_ (indicating that something would be enabled +/// when it actually would not be) or a _false negative_ (indicating that +/// something would be disabled when it would actually be enabled). +/// +/// [Subscribers]: crate::subscriber::Subscriber +/// [`Metadata`]: crate::metadata::Metadata +/// +/// This occurs when a subscriber is using a _more specific_ filter than the +/// metadata provided to the `enabled!` macro. Some situations that can result +/// in false positives or false negatives include: +/// +/// - If a subscriber is using a filter which may enable a span or event based +/// on field names, but `enabled!` is invoked without listing field names, +/// `enabled!` may return a false negative if a specific field name would +/// cause the subscriber to enable something that would otherwise be disabled. +/// - If a subscriber is using a filter which enables or disables specific events by +/// file path and line number, a particular event may be enabled/disabled +/// even if an `enabled!` invocation with the same level, target, and fields +/// indicated otherwise. +/// - The subscriber can choose to enable _only_ spans or _only_ events, which `enabled` +/// will not reflect. +/// +/// `enabled!()` requires a [level](crate::Level) argument, an optional `target:` +/// argument, and an optional set of field names. If the fields are not provided, +/// they are considered to be unknown. `enabled!` attempts to match the +/// syntax of `event!()` as closely as possible, which can be seen in the +/// examples below. +/// +/// # Examples +/// +/// If the current subscriber is interested in recording `DEBUG`-level spans and +/// events in the current file and module path, this will evaluate to true: +/// ```rust +/// use tracing::{enabled, Level}; +/// +/// if enabled!(Level::DEBUG) { +/// // some expensive work... +/// } +/// ``` +/// +/// If the current subscriber is interested in recording spans and events +/// in the current file and module path, with the target "my_crate", and at the +/// level `DEBUG`, this will evaluate to true: +/// ```rust +/// # use tracing::{enabled, Level}; +/// if enabled!(target: "my_crate", Level::DEBUG) { +/// // some expensive work... +/// } +/// ``` +/// +/// If the current subscriber is interested in recording spans and events +/// in the current file and module path, with the target "my_crate", at +/// the level `DEBUG`, and with a field named "hello", this will evaluate +/// to true: +/// +/// ```rust +/// # use tracing::{enabled, Level}; +/// if enabled!(target: "my_crate", Level::DEBUG, hello) { +/// // some expensive work... +/// } +/// ``` +/// +/// # Alternatives +/// +/// `enabled!` queries subscribers with [`Metadata`] where +/// [`is_event`] and [`is_span`] both return `false`. Alternatively, +/// use [`event_enabled!`] or [`span_enabled!`] to ensure one of these +/// returns true. +/// +/// +/// [`Metadata`]: crate::Metadata +/// [`is_event`]: crate::Metadata::is_event +/// [`is_span`]: crate::Metadata::is_span +/// [`enabled!`]: crate::enabled +/// [`span_enabled!`]: crate::span_enabled +#[macro_export] +macro_rules! enabled { + (kind: $kind:expr, target: $target:expr, $lvl:expr, { $($fields:tt)* } )=> ({ + if $crate::level_enabled!($lvl) { + use $crate::__macro_support::Callsite as _; + static CALLSITE: $crate::callsite::DefaultCallsite = $crate::callsite2! { + name: $crate::__macro_support::concat!( + "enabled ", + file!(), + ":", + line!() + ), + kind: $kind.hint(), + target: $target, + level: $lvl, + fields: $($fields)* + }; + let interest = CALLSITE.interest(); + if !interest.is_never() && $crate::__macro_support::__is_enabled(CALLSITE.metadata(), interest) { + let meta = CALLSITE.metadata(); + $crate::dispatcher::get_default(|current| current.enabled(meta)) + } else { + false + } + } else { + false + } + }); + // Just target and level + (kind: $kind:expr, target: $target:expr, $lvl:expr ) => ( + $crate::enabled!(kind: $kind, target: $target, $lvl, { }) + ); + (target: $target:expr, $lvl:expr ) => ( + $crate::enabled!(kind: $crate::metadata::Kind::HINT, target: $target, $lvl, { }) + ); + + // These four cases handle fields with no values + (kind: $kind:expr, target: $target:expr, $lvl:expr, $($field:tt)*) => ( + $crate::enabled!( + kind: $kind, + target: $target, + $lvl, + { $($field)*} + ) + ); + (target: $target:expr, $lvl:expr, $($field:tt)*) => ( + $crate::enabled!( + kind: $crate::metadata::Kind::HINT, + target: $target, + $lvl, + { $($field)*} + ) + ); + + // Level and field case + (kind: $kind:expr, $lvl:expr, $($field:tt)*) => ( + $crate::enabled!( + kind: $kind, + target: module_path!(), + $lvl, + { $($field)*} + ) + ); + + // Simplest `enabled!` case + (kind: $kind:expr, $lvl:expr) => ( + $crate::enabled!(kind: $kind, target: module_path!(), $lvl, { }) + ); + ($lvl:expr) => ( + $crate::enabled!(kind: $crate::metadata::Kind::HINT, target: module_path!(), $lvl, { }) + ); + + // Fallthrough from above + ($lvl:expr, $($field:tt)*) => ( + $crate::enabled!( + kind: $crate::metadata::Kind::HINT, + target: module_path!(), + $lvl, + { $($field)*} + ) + ); +} + +/// 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!`]: crate::event! +/// [lib]: crate#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!`]: crate::event! +/// [lib]: crate#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!`]: crate::event! +/// [lib]: crate#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::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).+, $($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!`]: crate::event! +/// [lib]: crate#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::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).+, $($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!`]: crate::event! +/// [lib]: crate#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::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).+, $($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)* + ) => {{ + static META: $crate::Metadata<'static> = { + $crate::metadata! { + name: $name, + target: $target, + level: $lvl, + fields: $crate::fieldset!( $($fields)* ), + callsite: &CALLSITE, + kind: $kind, + } + }; + static CALLSITE: $crate::callsite::DefaultCallsite = $crate::callsite::DefaultCallsite::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)* + ) => {{ + static META: $crate::Metadata<'static> = { + $crate::metadata! { + name: $name, + target: $target, + level: $lvl, + fields: $crate::fieldset!( $($fields)* ), + callsite: &CALLSITE, + kind: $kind, + } + }; + $crate::callsite::DefaultCallsite::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 &dyn Value)) }, + $next, + $($rest)* + ) + }; + (@ { $(,)* $($out:expr),* }, $next:expr, $($k:ident).+ = %$val:expr, $($rest:tt)*) => { + $crate::valueset!( + @ { $($out),*, (&$next, Some(&display(&$val) as &dyn Value)) }, + $next, + $($rest)* + ) + }; + (@ { $(,)* $($out:expr),* }, $next:expr, $($k:ident).+ = $val:expr, $($rest:tt)*) => { + $crate::valueset!( + @ { $($out),*, (&$next, Some(&$val as &dyn Value)) }, + $next, + $($rest)* + ) + }; + (@ { $(,)* $($out:expr),* }, $next:expr, $($k:ident).+, $($rest:tt)*) => { + $crate::valueset!( + @ { $($out),*, (&$next, Some(&$($k).+ as &dyn Value)) }, + $next, + $($rest)* + ) + }; + (@ { $(,)* $($out:expr),* }, $next:expr, ?$($k:ident).+, $($rest:tt)*) => { + $crate::valueset!( + @ { $($out),*, (&$next, Some(&debug(&$($k).+) as &dyn Value)) }, + $next, + $($rest)* + ) + }; + (@ { $(,)* $($out:expr),* }, $next:expr, %$($k:ident).+, $($rest:tt)*) => { + $crate::valueset!( + @ { $($out),*, (&$next, Some(&display(&$($k).+) as &dyn Value)) }, + $next, + $($rest)* + ) + }; + (@ { $(,)* $($out:expr),* }, $next:expr, $($k:ident).+ = ?$val:expr) => { + $crate::valueset!( + @ { $($out),*, (&$next, Some(&debug(&$val) as &dyn Value)) }, + $next, + ) + }; + (@ { $(,)* $($out:expr),* }, $next:expr, $($k:ident).+ = %$val:expr) => { + $crate::valueset!( + @ { $($out),*, (&$next, Some(&display(&$val) as &dyn Value)) }, + $next, + ) + }; + (@ { $(,)* $($out:expr),* }, $next:expr, $($k:ident).+ = $val:expr) => { + $crate::valueset!( + @ { $($out),*, (&$next, Some(&$val as &dyn Value)) }, + $next, + ) + }; + (@ { $(,)* $($out:expr),* }, $next:expr, $($k:ident).+) => { + $crate::valueset!( + @ { $($out),*, (&$next, Some(&$($k).+ as &dyn Value)) }, + $next, + ) + }; + (@ { $(,)* $($out:expr),* }, $next:expr, ?$($k:ident).+) => { + $crate::valueset!( + @ { $($out),*, (&$next, Some(&debug(&$($k).+) as &dyn Value)) }, + $next, + ) + }; + (@ { $(,)* $($out:expr),* }, $next:expr, %$($k:ident).+) => { + $crate::valueset!( + @ { $($out),*, (&$next, Some(&display(&$($k).+) as &dyn Value)) }, + $next, + ) + }; + + // Handle literal names + (@ { $(,)* $($out:expr),* }, $next:expr, $k:literal = ?$val:expr, $($rest:tt)*) => { + $crate::valueset!( + @ { $($out),*, (&$next, Some(&debug(&$val) as &dyn Value)) }, + $next, + $($rest)* + ) + }; + (@ { $(,)* $($out:expr),* }, $next:expr, $k:literal = %$val:expr, $($rest:tt)*) => { + $crate::valueset!( + @ { $($out),*, (&$next, Some(&display(&$val) as &dyn Value)) }, + $next, + $($rest)* + ) + }; + (@ { $(,)* $($out:expr),* }, $next:expr, $k:literal = $val:expr, $($rest:tt)*) => { + $crate::valueset!( + @ { $($out),*, (&$next, Some(&$val as &dyn Value)) }, + $next, + $($rest)* + ) + }; + (@ { $(,)* $($out:expr),* }, $next:expr, $k:literal = ?$val:expr) => { + $crate::valueset!( + @ { $($out),*, (&$next, Some(&debug(&$val) as &dyn Value)) }, + $next, + ) + }; + (@ { $(,)* $($out:expr),* }, $next:expr, $k:literal = %$val:expr) => { + $crate::valueset!( + @ { $($out),*, (&$next, Some(&display(&$val) as &dyn Value)) }, + $next, + ) + }; + (@ { $(,)* $($out:expr),* }, $next:expr, $k:literal = $val:expr) => { + $crate::valueset!( + @ { $($out),*, (&$next, Some(&$val as &dyn 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 &dyn 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 { + ($level:expr, $callsite:expr, $value_set:expr) => {}; +} + +#[cfg(feature = "log")] +#[doc(hidden)] +#[macro_export] +macro_rules! __tracing_log { + ($level:expr, $callsite:expr, $value_set:expr) => { + $crate::if_log_enabled! { $level, { + use $crate::log; + let level = $crate::level_to_log!($level); + if level <= log::max_level() { + let meta = $callsite.metadata(); + let log_meta = log::Metadata::builder() + .level(level) + .target(meta.target()) + .build(); + let logger = log::logger(); + if logger.enabled(&log_meta) { + $crate::__macro_support::__tracing_log(meta, logger, log_meta, $value_set) + } + } + }} + }; +} + +#[cfg(not(feature = "log"))] +#[doc(hidden)] +#[macro_export] +macro_rules! if_log_enabled { + ($lvl:expr, $e:expr;) => { + $crate::if_log_enabled! { $lvl, $e } + }; + ($lvl:expr, $if_log:block) => { + $crate::if_log_enabled! { $lvl, $if_log else {} } + }; + ($lvl:expr, $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 { + ($lvl:expr, $e:expr;) => { + $crate::if_log_enabled! { $lvl, $e } + }; + ($lvl:expr, $if_log:block) => { + $crate::if_log_enabled! { $lvl, $if_log else {} } + }; + ($lvl:expr, $if_log:block else $else_block:block) => { + if $crate::level_to_log!($lvl) <= $crate::log::STATIC_MAX_LEVEL { + if !$crate::dispatcher::has_been_set() { + $if_log + } else { + $else_block + } + } else { + $else_block + } + }; +} + +#[cfg(all(feature = "log", feature = "log-always"))] +#[doc(hidden)] +#[macro_export] +macro_rules! if_log_enabled { + ($lvl:expr, $e:expr;) => { + $crate::if_log_enabled! { $lvl, $e } + }; + ($lvl:expr, $if_log:block) => { + $crate::if_log_enabled! { $lvl, $if_log else {} } + }; + ($lvl:expr, $if_log:block else $else_block:block) => { + if $crate::level_to_log!($lvl) <= $crate::log::STATIC_MAX_LEVEL { + #[allow(unused_braces)] + $if_log + } else { + $else_block + } + }; +} diff --git a/src/span.rs b/src/span.rs new file mode 100644 index 0000000..58822f4 --- /dev/null +++ b/src/span.rs @@ -0,0 +1,1623 @@ +//! 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`]: super::Metadata::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`], [`entered`], and [`in_scope`] methods. +//! +//! The [`enter`] method enters a span, returning a [guard] that exits the span +//! when dropped +//! ``` +//! # use tracing::{span, 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="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> +//! +//! The [`entered`] method is analogous to [`enter`], but moves the span into +//! the returned guard, rather than borrowing it. This allows creating and +//! entering a span in a single expression: +//! +//! ``` +//! # use tracing::{span, Level}; +//! // Create a span and enter it, returning a guard: +//! let span = span!(Level::INFO, "my_span").entered(); +//! +//! // We are now inside the span! Like `enter()`, the guard returned by +//! // `entered()` will exit the span when it is dropped... +//! +//! // ...but, it can also be exited explicitly, returning the `Span` +//! // struct: +//! let span = span.exit(); +//! ``` +//! +//! Finally, [`in_scope`] takes a closure or function pointer and executes it +//! inside the span: +//! +//! ``` +//! # use tracing::{span, 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`. +//! }); +//! ``` +//! +//! <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> +//! +//! ## 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. +//! +//! ``` +//! # use tracing::{Level, span}; +//! // 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 +//! # use tracing::{Level, span}; +//! // 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 +//! # use std::future::Future; +//! # use std::task::{Context, Poll}; +//! # use std::pin::Pin; +//! struct MyFuture { +//! // data +//! span: tracing::Span, +//! } +//! +//! impl Future for MyFuture { +//! type Output = (); +//! +//! fn poll(self: Pin<&mut Self>, _cx: &mut Context<'_>) -> Poll<Self::Output> { +//! let _enter = self.span.enter(); +//! // Do actual future work... +//! # Poll::Ready(()) +//! } +//! } +//! ``` +//! +//! If this future was spawned on an executor, it might yield one or more times +//! before `poll` returns [`Poll::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: +//! ``` +//! # use tracing::{Level, span}; +//! { +//! 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 +//! # use tracing::{Level, span}; +//! # 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 +//! # use tracing::{Level, span}; +//! # 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]: super::field +//! [Metadata]: super::Metadata +//! [verbosity level]: super::Level +//! [`Poll::Ready`]: std::task::Poll::Ready +//! [`span!`]: super::span! +//! [`trace_span!`]: super::trace_span! +//! [`debug_span!`]: super::debug_span! +//! [`info_span!`]: super::info_span! +//! [`warn_span!`]: super::warn_span! +//! [`error_span!`]: super::error_span! +//! [`clone_span`]: super::subscriber::Subscriber::clone_span() +//! [`drop_span`]: super::subscriber::Subscriber::drop_span() +//! [`exit`]: super::subscriber::Subscriber::exit +//! [`Subscriber`]: super::subscriber::Subscriber +//! [`enter`]: Span::enter() +//! [`entered`]: Span::entered() +//! [`in_scope`]: Span::in_scope() +//! [`follows_from`]: Span::follows_from() +//! [guard]: Entered +//! [parent]: #span-relationships +pub use tracing_core::span::{Attributes, Id, Record}; + +use crate::stdlib::{ + cmp, fmt, + hash::{Hash, Hasher}, + marker::PhantomData, + mem, + ops::Deref, +}; +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`]: super::Span::enter +#[derive(Debug)] +#[must_use = "once a span has been entered, it should be exited"] +pub struct Entered<'a> { + span: &'a Span, +} + +/// An owned version of [`Entered`], 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::entered`] function. +/// +/// [`Span::entered`]: super::Span::entered() +#[derive(Debug)] +#[must_use = "once a span has been entered, it should be exited"] +pub struct EnteredSpan { + span: Span, + + /// ```compile_fail + /// use tracing::span::*; + /// trait AssertSend: Send {} + /// + /// impl AssertSend for EnteredSpan {} + /// ``` + _not_send: PhantomNotSend, +} + +/// `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]: super::Metadata + /// [`Subscriber`]: super::subscriber::Subscriber + /// [field values]: super::field::ValueSet + /// [`follows_from`]: super::Span::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]: super::Metadata + /// [field values]: super::field::ValueSet + /// [`follows_from`]: super::Span::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]: super::Metadata + /// [field values]: super::field::ValueSet + /// [`follows_from`]: super::Span::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`]: + /// super::subscriber::Subscriber::current_span + 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! { *meta.level(), { + let target = if attrs.is_empty() { + LIFECYCLE_LOG_TARGET + } else { + meta.target() + }; + let values = attrs.values(); + span.log( + target, + level_to_log!(*meta.level()), + format_args!("++ {};{}", meta.name(), crate::log::LogValueSet { values, is_first: false }), + ); + }} + + 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"); + /// + /// // WARNING: This span will remain entered until this + /// // guard is dropped... + /// let _enter = span.enter(); + /// // ...but the `await` keyword may yield, causing the + /// // runtime to switch to another task, while remaining in + /// // this span! + /// 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`]: Span::in_scope() + /// [instrument]: crate::Instrument + /// [attr]: macro@crate::instrument + /// + /// # Examples + /// + /// ``` + /// # use tracing::{span, 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: + /// + /// ``` + /// # use tracing::trace_span; + /// 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: + /// + /// ``` + /// # use tracing::{info, info_span}; + /// 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`]: super::subscriber::Subscriber::enter() + /// [`Subscriber::exit`]: super::subscriber::Subscriber::exit() + /// [`Id`]: super::Id + #[inline(always)] + pub fn enter(&self) -> Entered<'_> { + self.do_enter(); + Entered { span: self } + } + + /// Enters this span, consuming it and returning a [guard][`EnteredSpan`] + /// that will exit the span when dropped. + /// + /// <pre class="compile_fail" style="white-space:normal;font:inherit;"> + /// <strong>Warning</strong>: In asynchronous code that uses async/await syntax, + /// <code>Span::entered</code> may produce incorrect traces if the returned drop + /// guard is held across an await point. See <a href="#in-asynchronous-code">the + /// <code>Span::enter</code> documentation</a> for details. + /// </pre> + /// + /// + /// 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. + /// + /// This is similar to the [`Span::enter`] method, except that it moves the + /// span by value into the returned guard, rather than borrowing it. + /// Therefore, this method can be used to create and enter a span in a + /// single expression, without requiring a `let`-binding. For example: + /// + /// ``` + /// # use tracing::info_span; + /// let _span = info_span!("something_interesting").entered(); + /// ``` + /// rather than: + /// ``` + /// # use tracing::info_span; + /// let span = info_span!("something_interesting"); + /// let _e = span.enter(); + /// ``` + /// + /// Furthermore, `entered` may be used when the span must be stored in some + /// other struct or be passed to a function while remaining entered. + /// + /// <pre class="ignore" style="white-space:normal;font:inherit;"> + /// <strong>Note</strong>: The returned <a href="../struct.EnteredSpan.html"> + /// <code>EnteredSpan</a></code> guard does not implement <code>Send</code>. + /// Dropping the guard will exit <em>this</em> span, and if the guard is sent + /// to another thread and dropped there, that thread may never have entered + /// this span. Thus, <code>EnteredSpan</code>s should not be sent between threads. + /// </pre> + /// + /// [syntax]: https://rust-lang.github.io/async-book/01_getting_started/04_async_await_primer.html + /// + /// # Examples + /// + /// The returned guard can be [explicitly exited][EnteredSpan::exit], + /// returning the un-entered span: + /// + /// ``` + /// # use tracing::{Level, span}; + /// let span = span!(Level::INFO, "doing_something").entered(); + /// + /// // code here is within the span + /// + /// // explicitly exit the span, returning it + /// let span = span.exit(); + /// + /// // code here is no longer within the span + /// + /// // enter the span again + /// let span = span.entered(); + /// + /// // now we are inside the span once again + /// ``` + /// + /// Guards need not be explicitly dropped: + /// + /// ``` + /// # use tracing::trace_span; + /// fn my_function() -> String { + /// // enter a span for the duration of this function. + /// let span = trace_span!("my_function").entered(); + /// + /// // 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() { + /// // ... + /// } + /// ``` + /// + /// Since the [`EnteredSpan`] guard can dereference to the [`Span`] itself, + /// the span may still be accessed while entered. For example: + /// + /// ```rust + /// # use tracing::info_span; + /// use tracing::field; + /// + /// // create the span with an empty field, and enter it. + /// let span = info_span!("my_span", some_field = field::Empty).entered(); + /// + /// // we can still record a value for the field while the span is entered. + /// span.record("some_field", &"hello world!"); + /// ``` + /// + + /// [`Subscriber::enter`]: super::subscriber::Subscriber::enter() + /// [`Subscriber::exit`]: super::subscriber::Subscriber::exit() + /// [`Id`]: super::Id + #[inline(always)] + pub fn entered(self) -> EnteredSpan { + self.do_enter(); + EnteredSpan { + span: self, + _not_send: PhantomNotSend, + } + } + + /// Returns this span, if it was [enabled] by the current [`Subscriber`], or + /// the [current span] (whose lexical distance may be further than expected), + /// if this span [is disabled]. + /// + /// This method can be useful when propagating spans to spawned threads or + /// [async tasks]. Consider the following: + /// + /// ``` + /// let _parent_span = tracing::info_span!("parent").entered(); + /// + /// // ... + /// + /// let child_span = tracing::debug_span!("child"); + /// + /// std::thread::spawn(move || { + /// let _entered = child_span.entered(); + /// + /// tracing::info!("spawned a thread!"); + /// + /// // ... + /// }); + /// ``` + /// + /// If the current [`Subscriber`] enables the [`DEBUG`] level, then both + /// the "parent" and "child" spans will be enabled. Thus, when the "spawaned + /// a thread!" event occurs, it will be inside of the "child" span. Because + /// "parent" is the parent of "child", the event will _also_ be inside of + /// "parent". + /// + /// However, if the [`Subscriber`] only enables the [`INFO`] level, the "child" + /// span will be disabled. When the thread is spawned, the + /// `child_span.entered()` call will do nothing, since "child" is not + /// enabled. In this case, the "spawned a thread!" event occurs outside of + /// *any* span, since the "child" span was responsible for propagating its + /// parent to the spawned thread. + /// + /// If this is not the desired behavior, `Span::or_current` can be used to + /// ensure that the "parent" span is propagated in both cases, either as a + /// parent of "child" _or_ directly. For example: + /// + /// ``` + /// let _parent_span = tracing::info_span!("parent").entered(); + /// + /// // ... + /// + /// // If DEBUG is enabled, then "child" will be enabled, and `or_current` + /// // returns "child". Otherwise, if DEBUG is not enabled, "child" will be + /// // disabled, and `or_current` returns "parent". + /// let child_span = tracing::debug_span!("child").or_current(); + /// + /// std::thread::spawn(move || { + /// let _entered = child_span.entered(); + /// + /// tracing::info!("spawned a thread!"); + /// + /// // ... + /// }); + /// ``` + /// + /// When spawning [asynchronous tasks][async tasks], `Span::or_current` can + /// be used similarly, in combination with [`instrument`]: + /// + /// ``` + /// use tracing::Instrument; + /// # // lol + /// # mod tokio { + /// # pub(super) fn spawn(_: impl std::future::Future) {} + /// # } + /// + /// let _parent_span = tracing::info_span!("parent").entered(); + /// + /// // ... + /// + /// let child_span = tracing::debug_span!("child"); + /// + /// tokio::spawn( + /// async { + /// tracing::info!("spawned a task!"); + /// + /// // ... + /// + /// }.instrument(child_span.or_current()) + /// ); + /// ``` + /// + /// In general, `or_current` should be preferred over nesting an + /// [`instrument`] call inside of an [`in_current_span`] call, as using + /// `or_current` will be more efficient. + /// + /// ``` + /// use tracing::Instrument; + /// # // lol + /// # mod tokio { + /// # pub(super) fn spawn(_: impl std::future::Future) {} + /// # } + /// async fn my_async_fn() { + /// // ... + /// } + /// + /// let _parent_span = tracing::info_span!("parent").entered(); + /// + /// // Do this: + /// tokio::spawn( + /// my_async_fn().instrument(tracing::debug_span!("child").or_current()) + /// ); + /// + /// // ...rather than this: + /// tokio::spawn( + /// my_async_fn() + /// .instrument(tracing::debug_span!("child")) + /// .in_current_span() + /// ); + /// ``` + /// + /// [enabled]: crate::Subscriber::enabled + /// [`Subscriber`]: crate::Subscriber + /// [current span]: Span::current + /// [is disabled]: Span::is_disabled + /// [`INFO`]: crate::Level::INFO + /// [`DEBUG`]: crate::Level::DEBUG + /// [async tasks]: std::task + /// [`instrument`]: crate::instrument::Instrument::instrument + /// [`in_current_span`]: crate::instrument::Instrument::in_current_span + pub fn or_current(self) -> Self { + if self.is_disabled() { + return Self::current(); + } + self + } + + #[inline(always)] + fn do_enter(&self) { + if let Some(inner) = self.inner.as_ref() { + inner.subscriber.enter(&inner.id); + } + + if_log_enabled! { crate::Level::TRACE, { + if let Some(_meta) = self.meta { + self.log(ACTIVITY_LOG_TARGET, log::Level::Trace, format_args!("-> {};", _meta.name())); + } + }} + } + + // Called from [`Entered`] and [`EnteredSpan`] drops. + // + // Running this behaviour on drop rather than with an explicit function + // call means that spans may still be exited when unwinding. + #[inline(always)] + fn do_exit(&self) { + if let Some(inner) = self.inner.as_ref() { + inner.subscriber.exit(&inner.id); + } + + if_log_enabled! { crate::Level::TRACE, { + if let Some(_meta) = self.meta { + self.log(ACTIVITY_LOG_TARGET, log::Level::Trace, format_args!("<- {};", _meta.name())); + } + }} + } + + /// 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 + /// + /// ``` + /// # use tracing::{trace, span, 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`][super::field::Field] 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`][super::field::Field] 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); + /// } + /// } + /// ``` + /// + /// <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> + /// + /// ``` + /// 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`]: super::field::Empty + /// [`Metadata`]: super::Metadata + pub fn record<Q: ?Sized, V>(&self, field: &Q, value: V) -> &Self + where + Q: field::AsField, + V: field::Value, + { + if let Some(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 let Some(_meta) = self.meta { + if_log_enabled! { *_meta.level(), { + let target = if record.is_empty() { + LIFECYCLE_LOG_TARGET + } else { + _meta.target() + }; + self.log( + target, + level_to_log!(*_meta.level()), + format_args!("{};{}", _meta.name(), crate::log::LogValueSet { values, is_first: false }), + ); + }} + } + + self + } + + /// Returns `true` if this span was disabled by the subscriber and does not + /// exist. + /// + /// See also [`is_none`]. + /// + /// [`is_none`]: Span::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`]: Span::none() + /// [`is_disabled`]: Span::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(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(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> From<&'a Span> for Option<&'a Id> { + fn from(span: &'a Span) -> Self { + span.inner.as_ref().map(|inner| &inner.id) + } +} + +impl<'a> From<&'a Span> for Option<Id> { + fn from(span: &'a Span) -> Self { + span.inner.as_ref().map(Inner::id) + } +} + +impl From<Span> for Option<Id> { + fn from(span: Span) -> Self { + span.inner.as_ref().map(Inner::id) + } +} + +impl<'a> From<&'a EnteredSpan> for Option<&'a Id> { + fn from(span: &'a EnteredSpan) -> Self { + span.inner.as_ref().map(|inner| &inner.id) + } +} + +impl<'a> From<&'a EnteredSpan> for Option<Id> { + fn from(span: &'a EnteredSpan) -> Self { + span.inner.as_ref().map(Inner::id) + } +} + +impl Drop for Span { + #[inline(always)] + fn drop(&mut self) { + if let Some(Inner { + ref id, + ref subscriber, + }) = self.inner + { + subscriber.try_close(id.clone()); + } + + if_log_enabled! { crate::Level::TRACE, { + if let Some(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 EnteredSpan { + /// Returns this span's `Id`, if it is enabled. + pub fn id(&self) -> Option<Id> { + self.inner.as_ref().map(Inner::id) + } + + /// Exits this span, returning the underlying [`Span`]. + #[inline] + pub fn exit(mut self) -> Span { + // One does not simply move out of a struct with `Drop`. + let span = mem::replace(&mut self.span, Span::none()); + span.do_exit(); + span + } +} + +impl Deref for EnteredSpan { + type Target = Span; + + #[inline] + fn deref(&self) -> &Span { + &self.span + } +} + +impl<'a> Drop for Entered<'a> { + #[inline(always)] + fn drop(&mut self) { + self.span.do_exit() + } +} + +impl Drop for EnteredSpan { + #[inline(always)] + fn drop(&mut self) { + self.span.do_exit() + } +} + +/// Technically, `EnteredSpan` _can_ implement both `Send` *and* +/// `Sync` safely. It doesn't, because it has a `PhantomNotSend` field, +/// specifically added in order to make it `!Send`. +/// +/// Sending an `EnteredSpan` guard between threads cannot cause memory unsafety. +/// However, it *would* result in incorrect behavior, so we add a +/// `PhantomNotSend` to prevent it from being sent between threads. This is +/// because it must be *dropped* on the same thread that it was created; +/// otherwise, the span will never be exited on the thread where it was entered, +/// and it will attempt to exit the span on a thread that may never have entered +/// it. However, we still want them to be `Sync` so that a struct holding an +/// `Entered` guard can be `Sync`. +/// +/// Thus, this is totally safe. +#[derive(Debug)] +struct PhantomNotSend { + ghost: PhantomData<*mut ()>, +} + +#[allow(non_upper_case_globals)] +const PhantomNotSend: PhantomNotSend = PhantomNotSend { ghost: PhantomData }; + +/// # Safety +/// +/// Trivially safe, as `PhantomNotSend` doesn't have any API. +unsafe impl Sync for PhantomNotSend {} + +#[cfg(test)] +mod test { + use super::*; + + trait AssertSend: Send {} + impl AssertSend for Span {} + + trait AssertSync: Sync {} + impl AssertSync for Span {} + impl AssertSync for Entered<'_> {} + impl AssertSync for EnteredSpan {} + + #[test] + fn test_record_backwards_compat() { + Span::current().record("some-key", &"some text"); + Span::current().record("some-key", &false); + } +} diff --git a/src/stdlib.rs b/src/stdlib.rs new file mode 100644 index 0000000..12b5408 --- /dev/null +++ b/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/src/subscriber.rs b/src/subscriber.rs new file mode 100644 index 0000000..f55698d --- /dev/null +++ b/src/subscriber.rs @@ -0,0 +1,65 @@ +//! 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 current thread for the +/// duration of a closure. +/// +/// The default subscriber is used when creating a new [`Span`] or +/// [`Event`]. +/// +/// +/// [`Span`]: super::span::Span +/// [`Subscriber`]: super::subscriber::Subscriber +/// [`Event`]: super::event::Event +#[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]: super::span +/// [`Subscriber`]: super::subscriber::Subscriber +/// [`Event`]: super::event::Event +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 current thread for the +/// duration of the lifetime of the returned [`DefaultGuard`]. +/// +/// The default subscriber is used when creating a new [`Span`] or [`Event`]. +/// +/// [`Span`]: super::span::Span +/// [`Subscriber`]: super::subscriber::Subscriber +/// [`Event`]: super::event::Event +/// [`DefaultGuard`]: super::dispatcher::DefaultGuard +#[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/tests/enabled.rs b/tests/enabled.rs new file mode 100644 index 0000000..ea1c698 --- /dev/null +++ b/tests/enabled.rs @@ -0,0 +1,54 @@ +#![cfg(feature = "std")] +use tracing::Level; +use tracing_mock::*; + +#[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)] +#[test] +fn level_and_target() { + let subscriber = subscriber::mock() + .with_filter(|meta| { + if meta.target() == "debug_module" { + meta.level() <= &Level::DEBUG + } else { + meta.level() <= &Level::INFO + } + }) + .done() + .run(); + + let _guard = tracing::subscriber::set_default(subscriber); + + assert!(tracing::enabled!(target: "debug_module", Level::DEBUG)); + assert!(tracing::enabled!(Level::ERROR)); + assert!(!tracing::enabled!(Level::DEBUG)); +} + +#[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)] +#[test] +fn span_and_event() { + let subscriber = subscriber::mock() + .with_filter(|meta| { + if meta.target() == "debug_module" { + meta.level() <= &Level::DEBUG + } else if meta.is_span() { + meta.level() <= &Level::TRACE + } else if meta.is_event() { + meta.level() <= &Level::DEBUG + } else { + meta.level() <= &Level::INFO + } + }) + .done() + .run(); + + let _guard = tracing::subscriber::set_default(subscriber); + + // Ensure that the `_event` and `_span` alternatives work corretly + assert!(!tracing::event_enabled!(Level::TRACE)); + assert!(tracing::event_enabled!(Level::DEBUG)); + assert!(tracing::span_enabled!(Level::TRACE)); + + // target variants + assert!(tracing::span_enabled!(target: "debug_module", Level::DEBUG)); + assert!(tracing::event_enabled!(target: "debug_module", Level::DEBUG)); +} diff --git a/tests/event.rs b/tests/event.rs new file mode 100644 index 0000000..61df19a --- /dev/null +++ b/tests/event.rs @@ -0,0 +1,500 @@ +// 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")] + +use tracing::{ + debug, error, + field::{debug, display}, + info, + subscriber::with_default, + trace, warn, Level, +}; +use tracing_mock::*; + +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::msg(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::msg(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::msg(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)) + .and(field::mock("like_a_butterfly").with_value(&42.0)) + .only(), + ) + .at_level(Level::ERROR) + .with_target("whatever"), + ) + .done() + .run_with_handle(); + + with_default(subscriber, || { + tracing::event!( + target: "whatever", + Level::ERROR, + { foo = 666, bar = false, like_a_butterfly = 42.0 }, + "{:#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"; + tracing::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, || { + tracing::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); + tracing::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, || { + tracing::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, || { + tracing::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, || { + tracing::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 = tracing::span!(Level::TRACE, "foo"); + tracing::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 = tracing::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(); +} + +#[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)] +#[test] +fn option_values() { + let (subscriber, handle) = subscriber::mock() + .event( + event::mock().with_fields( + field::mock("some_str") + .with_value(&"yes") + .and(field::mock("some_bool").with_value(&true)) + .and(field::mock("some_u64").with_value(&42_u64)) + .only(), + ), + ) + .done() + .run_with_handle(); + + with_default(subscriber, || { + let some_str = Some("yes"); + let none_str: Option<&'static str> = None; + let some_bool = Some(true); + let none_bool: Option<bool> = None; + let some_u64 = Some(42_u64); + let none_u64: Option<u64> = None; + trace!( + some_str = some_str, + none_str = none_str, + some_bool = some_bool, + none_bool = none_bool, + some_u64 = some_u64, + none_u64 = none_u64 + ); + }); + + handle.assert_finished(); +} + +#[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)] +#[test] +fn option_ref_values() { + let (subscriber, handle) = subscriber::mock() + .event( + event::mock().with_fields( + field::mock("some_str") + .with_value(&"yes") + .and(field::mock("some_bool").with_value(&true)) + .and(field::mock("some_u64").with_value(&42_u64)) + .only(), + ), + ) + .done() + .run_with_handle(); + + with_default(subscriber, || { + let some_str = &Some("yes"); + let none_str: &Option<&'static str> = &None; + let some_bool = &Some(true); + let none_bool: &Option<bool> = &None; + let some_u64 = &Some(42_u64); + let none_u64: &Option<u64> = &None; + trace!( + some_str = some_str, + none_str = none_str, + some_bool = some_bool, + none_bool = none_bool, + some_u64 = some_u64, + none_u64 = none_u64 + ); + }); + + handle.assert_finished(); +} + +#[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)] +#[test] +fn option_ref_mut_values() { + let (subscriber, handle) = subscriber::mock() + .event( + event::mock().with_fields( + field::mock("some_str") + .with_value(&"yes") + .and(field::mock("some_bool").with_value(&true)) + .and(field::mock("some_u64").with_value(&42_u64)) + .only(), + ), + ) + .done() + .run_with_handle(); + + with_default(subscriber, || { + let some_str = &mut Some("yes"); + let none_str: &mut Option<&'static str> = &mut None; + let some_bool = &mut Some(true); + let none_bool: &mut Option<bool> = &mut None; + let some_u64 = &mut Some(42_u64); + let none_u64: &mut Option<u64> = &mut None; + trace!( + some_str = some_str, + none_str = none_str, + some_bool = some_bool, + none_bool = none_bool, + some_u64 = some_u64, + none_u64 = none_u64 + ); + }); + + handle.assert_finished(); +} + +#[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)] +#[test] +fn string_field() { + let (subscriber, handle) = subscriber::mock() + .event(event::mock().with_fields(field::mock("my_string").with_value(&"hello").only())) + .event( + event::mock().with_fields(field::mock("my_string").with_value(&"hello world!").only()), + ) + .done() + .run_with_handle(); + with_default(subscriber, || { + let mut my_string = String::from("hello"); + + tracing::event!(Level::INFO, my_string); + + // the string is not moved by using it as a field! + my_string.push_str(" world!"); + + tracing::event!(Level::INFO, my_string); + }); + + handle.assert_finished(); +} diff --git a/tests/filter_caching_is_lexically_scoped.rs b/tests/filter_caching_is_lexically_scoped.rs new file mode 100644 index 0000000..e291103 --- /dev/null +++ b/tests/filter_caching_is_lexically_scoped.rs @@ -0,0 +1,65 @@ +// 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; + +use tracing::{span, Level}; +use tracing_mock::*; + +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/tests/filters_are_not_reevaluated_for_the_same_span.rs b/tests/filters_are_not_reevaluated_for_the_same_span.rs new file mode 100644 index 0000000..e9b2529 --- /dev/null +++ b/tests/filters_are_not_reevaluated_for_the_same_span.rs @@ -0,0 +1,70 @@ +// 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; + +use tracing::{span, Level}; +use tracing_mock::*; + +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/tests/filters_are_reevaluated_for_different_call_sites.rs b/tests/filters_are_reevaluated_for_different_call_sites.rs new file mode 100644 index 0000000..265d4a8 --- /dev/null +++ b/tests/filters_are_reevaluated_for_different_call_sites.rs @@ -0,0 +1,80 @@ +// 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; + +use tracing::{span, Level}; +use tracing_mock::*; + +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/tests/filters_dont_leak.rs b/tests/filters_dont_leak.rs new file mode 100644 index 0000000..2ef1c9c --- /dev/null +++ b/tests/filters_dont_leak.rs @@ -0,0 +1,81 @@ +#![cfg(feature = "std")] + +use tracing_mock::*; + +#[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/tests/future_send.rs b/tests/future_send.rs new file mode 100644 index 0000000..5e5f9f1 --- /dev/null +++ b/tests/future_send.rs @@ -0,0 +1,22 @@ +// These tests reproduce the following issues: +// - https://github.com/tokio-rs/tracing/issues/1487 +// - https://github.com/tokio-rs/tracing/issues/1793 + +use core::future::{self, Future}; +#[test] +fn async_fn_is_send() { + async fn some_async_fn() { + tracing::info!("{}", future::ready("test").await); + } + + assert_send(some_async_fn()) +} + +#[test] +fn async_block_is_send() { + assert_send(async { + tracing::info!("{}", future::ready("test").await); + }) +} + +fn assert_send<F: Future + Send>(_f: F) {} diff --git a/tests/macro_imports.rs b/tests/macro_imports.rs new file mode 100644 index 0000000..2d0a9d6 --- /dev/null +++ b/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/tests/macros.rs b/tests/macros.rs new file mode 100644 index 0000000..a9679a3 --- /dev/null +++ b/tests/macros.rs @@ -0,0 +1,963 @@ +#![deny(warnings)] +use tracing::{ + callsite, debug, debug_span, enabled, error, error_span, event, event_enabled, info, info_span, + span, span_enabled, trace, trace_span, warn, warn_span, Level, +}; + +// 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 enabled() { + enabled!(Level::DEBUG, foo, bar.baz, quux,); + enabled!(Level::DEBUG, message); + enabled!(Level::INFO, foo, bar.baz, quux, message,); + enabled!(Level::INFO, foo, bar., message,); + enabled!(Level::DEBUG, foo); + + enabled!(Level::DEBUG); + enabled!(target: "rando", Level::DEBUG); + enabled!(target: "rando", Level::DEBUG, field); +} + +#[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)] +#[test] +fn span_enabled() { + span_enabled!(Level::DEBUG, foo, bar.baz, quux,); + span_enabled!(Level::DEBUG, message); + span_enabled!(Level::INFO, foo, bar.baz, quux, message,); + span_enabled!(Level::INFO, foo, bar., message,); + span_enabled!(Level::DEBUG, foo); + + span_enabled!(Level::DEBUG); + span_enabled!(target: "rando", Level::DEBUG); + span_enabled!(target: "rando", Level::DEBUG, field); +} + +#[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)] +#[test] +fn event_enabled() { + event_enabled!(Level::DEBUG, foo, bar.baz, quux,); + event_enabled!(Level::DEBUG, message); + event_enabled!(Level::INFO, foo, bar.baz, quux, message,); + event_enabled!(Level::INFO, foo, bar., message,); + event_enabled!(Level::DEBUG, foo); + + event_enabled!(Level::DEBUG); + event_enabled!(target: "rando", Level::DEBUG); + event_enabled!(target: "rando", Level::DEBUG, field); +} + +#[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); + trace!(target: "foo_events", ?foo); + trace!(target: "foo_events", %foo); + trace!(target: "foo_events", foo); + trace!(target: "foo_events", ?foo, true, "message"); + trace!(target: "foo_events", %foo, true, "message"); + trace!(target: "foo_events", foo, true, "message"); +} + +#[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); + debug!(target: "foo_events", ?foo); + debug!(target: "foo_events", %foo); + debug!(target: "foo_events", foo); + debug!(target: "foo_events", ?foo, true, "message"); + debug!(target: "foo_events", %foo, true, "message"); + debug!(target: "foo_events", foo, true, "message"); +} + +#[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); + info!(target: "foo_events", ?foo); + info!(target: "foo_events", %foo); + info!(target: "foo_events", foo); + info!(target: "foo_events", ?foo, true, "message"); + info!(target: "foo_events", %foo, true, "message"); + info!(target: "foo_events", foo, true, "message"); +} + +#[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); + warn!(target: "foo_events", ?foo); + warn!(target: "foo_events", %foo); + warn!(target: "foo_events", foo); + warn!(target: "foo_events", ?foo, true, "message"); + warn!(target: "foo_events", %foo, true, "message"); + warn!(target: "foo_events", foo, true, "message"); +} + +#[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); + error!(target: "foo_events", ?foo); + error!(target: "foo_events", %foo); + error!(target: "foo_events", foo); + error!(target: "foo_events", ?foo, true, "message"); + error!(target: "foo_events", %foo, true, "message"); + error!(target: "foo_events", foo, true, "message"); +} + +#[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/tests/macros_incompatible_concat.rs b/tests/macros_incompatible_concat.rs new file mode 100644 index 0000000..bda6b96 --- /dev/null +++ b/tests/macros_incompatible_concat.rs @@ -0,0 +1,24 @@ +use tracing::{enabled, event, span, Level}; + +#[macro_export] +macro_rules! concat { + () => {}; +} + +#[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)] +#[test] +fn span() { + span!(Level::DEBUG, "foo"); +} + +#[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)] +#[test] +fn event() { + event!(Level::DEBUG, "foo"); +} + +#[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)] +#[test] +fn enabled() { + enabled!(Level::DEBUG); +} diff --git a/tests/macros_redefined_core.rs b/tests/macros_redefined_core.rs new file mode 100644 index 0000000..d830dcd --- /dev/null +++ b/tests/macros_redefined_core.rs @@ -0,0 +1,18 @@ +extern crate self as core; + +use tracing::{enabled, event, span, Level}; + +#[test] +fn span() { + span!(Level::DEBUG, "foo"); +} + +#[test] +fn event() { + event!(Level::DEBUG, "foo"); +} + +#[test] +fn enabled() { + enabled!(Level::DEBUG); +} diff --git a/tests/max_level_hint.rs b/tests/max_level_hint.rs new file mode 100644 index 0000000..63d3af6 --- /dev/null +++ b/tests/max_level_hint.rs @@ -0,0 +1,37 @@ +use tracing::Level; +use tracing_mock::*; + +#[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/tests/multiple_max_level_hints.rs b/tests/multiple_max_level_hints.rs new file mode 100644 index 0000000..dd50a19 --- /dev/null +++ b/tests/multiple_max_level_hints.rs @@ -0,0 +1,69 @@ +#![cfg(feature = "std")] + +use tracing::Level; +use tracing_mock::*; + +#[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/tests/no_subscriber.rs b/tests/no_subscriber.rs new file mode 100644 index 0000000..5f927c1 --- /dev/null +++ b/tests/no_subscriber.rs @@ -0,0 +1,15 @@ +#![cfg(feature = "std")] + +use tracing::subscriber::{self, NoSubscriber}; + +#[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)] +#[test] +fn no_subscriber_disables_global() { + // Reproduces https://github.com/tokio-rs/tracing/issues/1999 + let (subscriber, handle) = tracing_mock::subscriber::mock().done().run_with_handle(); + subscriber::set_global_default(subscriber).expect("setting global default must succeed"); + subscriber::with_default(NoSubscriber::default(), || { + tracing::info!("this should not be recorded"); + }); + handle.assert_finished(); +} diff --git a/tests/register_callsite_deadlock.rs b/tests/register_callsite_deadlock.rs new file mode 100644 index 0000000..e4c116c --- /dev/null +++ b/tests/register_callsite_deadlock.rs @@ -0,0 +1,47 @@ +use std::{sync::mpsc, thread, time::Duration}; +use tracing::{ + metadata::Metadata, + span, + subscriber::{self, Interest, Subscriber}, + Event, +}; + +#[test] +fn register_callsite_doesnt_deadlock() { + pub struct EvilSubscriber; + + impl Subscriber for EvilSubscriber { + fn register_callsite(&self, meta: &'static Metadata<'static>) -> Interest { + tracing::info!(?meta, "registered a callsite"); + Interest::always() + } + + 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) {} + } + + subscriber::set_global_default(EvilSubscriber).unwrap(); + + // spawn a thread, and assert it doesn't hang... + let (tx, didnt_hang) = mpsc::channel(); + let th = thread::spawn(move || { + tracing::info!("hello world!"); + tx.send(()).unwrap(); + }); + + didnt_hang + // Note: 60 seconds is *way* more than enough, but let's be generous in + // case of e.g. slow CI machines. + .recv_timeout(Duration::from_secs(60)) + .expect("the thread must not have hung!"); + th.join().expect("thread should join successfully"); +} diff --git a/tests/scoped_clobbers_default.rs b/tests/scoped_clobbers_default.rs new file mode 100644 index 0000000..362d34a --- /dev/null +++ b/tests/scoped_clobbers_default.rs @@ -0,0 +1,35 @@ +#![cfg(feature = "std")] +use tracing_mock::*; + +#[test] +fn scoped_clobbers_global() { + // Reproduces https://github.com/tokio-rs/tracing/issues/2050 + + let (scoped, scoped_handle) = subscriber::mock() + .event(event::msg("before global")) + .event(event::msg("before drop")) + .done() + .run_with_handle(); + + let (global, global_handle) = subscriber::mock() + .event(event::msg("after drop")) + .done() + .run_with_handle(); + + // Set a scoped default subscriber, returning a guard. + let guard = tracing::subscriber::set_default(scoped); + tracing::info!("before global"); + + // Now, set the global default. + tracing::subscriber::set_global_default(global) + .expect("global default should not already be set"); + // This event should still be collected by the scoped default. + tracing::info!("before drop"); + + // Drop the guard. Now, the global default subscriber should be used. + drop(guard); + tracing::info!("after drop"); + + scoped_handle.assert_finished(); + global_handle.assert_finished(); +} diff --git a/tests/span.rs b/tests/span.rs new file mode 100644 index 0000000..4ed6500 --- /dev/null +++ b/tests/span.rs @@ -0,0 +1,825 @@ +// 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")] + +use std::thread; + +use tracing::{ + field::{debug, display}, + subscriber::with_default, + Level, Span, +}; +use tracing_mock::*; + +#[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 = tracing::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 = tracing::span!(Level::TRACE, "foo", bar = 1u64, baz = false); + let foo2 = tracing::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 { + tracing::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 = tracing::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 = tracing::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 = tracing::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, || { + tracing::span!(Level::TRACE, "foo").in_scope(|| { + tracing::event!(Level::DEBUG, {}, "my tracing::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, || { + tracing::span!(Level::TRACE, "foo").in_scope(|| { + tracing::event!(Level::DEBUG, {}, "my tracing::event!"); + }); + tracing::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, || { + tracing::debug!("my tracing::event!"); + tracing::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 = tracing::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 = tracing::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 = tracing::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 = tracing::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 = tracing::span!(Level::TRACE, "foo"); + let _enter = foo.enter(); + tracing::debug!("dropping guard..."); + }); + + handle.assert_finished(); +} + +#[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)] +#[test] +fn entered() { + 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 _span = tracing::span!(Level::TRACE, "foo").entered(); + tracing::debug!("dropping guard..."); + }); + + handle.assert_finished(); +} + +#[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)] +#[test] +fn entered_api() { + 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 span = tracing::span!(Level::TRACE, "foo").entered(); + let _derefs_to_span = span.id(); + tracing::debug!("exiting span..."); + let _: Span = span.exit(); + }); + + 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 = tracing::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, || { + tracing::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 = tracing::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 = tracing::span!(Level::TRACE, "foo", x = debug(pos.x), y = debug(pos.y)); + let bar = tracing::span!(Level::TRACE, "bar", position = debug(pos)); + foo.in_scope(|| {}); + bar.in_scope(|| {}); + }); + + handle.assert_finished(); +} + +#[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)] +#[test] +fn float_values() { + let (subscriber, handle) = subscriber::mock() + .new_span( + span::mock().named("foo").with_field( + field::mock("x") + .with_value(&3.234) + .and(field::mock("y").with_value(&-1.223)) + .only(), + ), + ) + .run_with_handle(); + + with_default(subscriber, || { + let foo = tracing::span!(Level::TRACE, "foo", x = 3.234, y = -1.223); + foo.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 = tracing::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 = tracing::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 = tracing::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 = tracing::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, || { + tracing::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, || { + tracing::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, || { + tracing::span!(Level::TRACE, "foo").in_scope(|| { + tracing::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 = tracing::span!(Level::TRACE, "foo"); + tracing::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 = tracing::span!(Level::TRACE, "foo"); + tracing::trace_span!(parent: foo.id(), "a"); + tracing::debug_span!(parent: foo.id(), "b"); + tracing::info_span!(parent: foo.id(), "c"); + tracing::warn_span!(parent: foo.id(), "d"); + tracing::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 = tracing::span!(Level::TRACE, "foo"); + tracing::span!(Level::TRACE, "bar") + .in_scope(|| tracing::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, || { + tracing::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, || { + tracing::span!(Level::TRACE, "foo").in_scope(|| { + tracing::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, || { + tracing::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, || { + tracing::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, || { + tracing::span!(Level::TRACE, "my_span", display_field = %"hello world", debug_field = ?"hello world"); + }); + + handle.assert_finished(); +} diff --git a/tests/subscriber.rs b/tests/subscriber.rs new file mode 100644 index 0000000..15557c1 --- /dev/null +++ b/tests/subscriber.rs @@ -0,0 +1,130 @@ +// 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")] +use tracing::{ + field::display, + span::{Attributes, Id, Record}, + subscriber::{with_default, Interest, Subscriber}, + Event, Level, Metadata, +}; + +use tracing_mock::*; + +#[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")); + tracing::event!(Level::TRACE, bar = false); + true + } + + fn new_span(&self, _: &Attributes<'_>) -> Id { + Id::from_u64(0xAAAA) + } + + fn record(&self, _: &Id, _: &Record<'_>) {} + + fn record_follows_from(&self, _: &Id, _: &Id) {} + + fn event(&self, event: &Event<'_>) { + assert!(event.metadata().fields().iter().any(|f| f.name() == "foo")); + tracing::event!(Level::TRACE, baz = false); + } + + fn enter(&self, _: &Id) {} + + fn exit(&self, _: &Id) {} + } + + with_default(TestSubscriber, || { + tracing::event!(Level::TRACE, foo = false); + }) +} + +#[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)] +#[test] +fn boxed_subscriber() { + 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(); + let subscriber: Box<dyn Subscriber + Send + Sync + 'static> = Box::new(subscriber); + + with_default(subscriber, || { + let from = "my span"; + let span = tracing::span!( + Level::TRACE, + "foo", + bar = format_args!("hello from {}", from) + ); + span.in_scope(|| {}); + }); + + handle.assert_finished(); +} + +#[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)] +#[test] +fn arced_subscriber() { + use std::sync::Arc; + + 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")) + .event( + event::mock() + .with_fields(field::mock("message").with_value(&display("hello from my event"))), + ) + .done() + .run_with_handle(); + let subscriber: Arc<dyn Subscriber + Send + Sync + 'static> = Arc::new(subscriber); + + // Test using a clone of the `Arc`ed subscriber + with_default(subscriber.clone(), || { + let from = "my span"; + let span = tracing::span!( + Level::TRACE, + "foo", + bar = format_args!("hello from {}", from) + ); + span.in_scope(|| {}); + }); + + with_default(subscriber, || { + tracing::info!("hello from my event"); + }); + + handle.assert_finished(); +} |