From 8d4d5ac1a95770230046cc860e81d25ae3261a1d Mon Sep 17 00:00:00 2001 From: Eliza Weisman Date: Wed, 3 Nov 2021 10:31:51 -0700 Subject: [PATCH] subscriber: document `time`'s `--cfg unsound_local_offset` (#1699) ## Motivation The `time` crate must be compiled with `--cfg unsound_local_offset` in order for local timestamps to be enabled. For users whose first exposure to the `time` crate's API is via `tracing-subscriber`'s `time` timestamp formatters, this is potentially _very_ surprising! Therefore, although this cfg is not part of `tracing`'s API surface, we should probably document this aspect of `time`'s API in the `tracing-subscriber::fmt::time` documentation. ## Solution This branch adds warnings in the `time::LocalTime` type's API docs, in the struct-level documentation and on the `new` constructor, describing that `--cfg unsound_local_offset` is necessary to record local timestamps and referring users to the `time` documentation. I also added `unsound_local_offset` to the `doc(cfg(...))` attributes for the `LocalTime` type. While I was changing `tracing-subscriber`'s docs, I also fixed a couple formatting issues I noticed. Fixes #1688 --- tracing-subscriber/src/fmt/time/mod.rs | 2 +- tracing-subscriber/src/fmt/time/time_crate.rs | 37 ++++++++++++++++--- tracing-subscriber/src/lib.rs | 2 +- 3 files changed, 34 insertions(+), 7 deletions(-) diff --git a/tracing-subscriber/src/fmt/time/mod.rs b/tracing-subscriber/src/fmt/time/mod.rs index e8331445cf..ea3a21b781 100644 --- a/tracing-subscriber/src/fmt/time/mod.rs +++ b/tracing-subscriber/src/fmt/time/mod.rs @@ -12,7 +12,7 @@ mod time_crate; pub use time_crate::UtcTime; #[cfg(feature = "local-time")] -#[cfg_attr(docsrs, doc(cfg(feature = "local-time")))] +#[cfg_attr(docsrs, doc(cfg(unsound_local_offset, feature = "local-time")))] pub use time_crate::LocalTime; /// A type that can measure and format the current time. diff --git a/tracing-subscriber/src/fmt/time/time_crate.rs b/tracing-subscriber/src/fmt/time/time_crate.rs index bb5fdd0ed4..656677e8d4 100644 --- a/tracing-subscriber/src/fmt/time/time_crate.rs +++ b/tracing-subscriber/src/fmt/time/time_crate.rs @@ -6,12 +6,26 @@ use time::{format_description::well_known, formatting::Formattable, OffsetDateTi /// /// To format the current [UTC time] instead, use the [`UtcTime`] type. /// +///
+/// 
+///     Warning: The time
+///     crate must be compiled with --cfg unsound_local_offset in order to use
+///     local timestamps. When this cfg is not enabled, local timestamps cannot be recorded, and
+///     events will be logged without timestamps.
+///
+///    See the time
+///    documentation for more details.
+///
+/// /// [local time]: https://docs.rs/time/0.3/time/struct.OffsetDateTime.html#method.now_local /// [UTC time]: https://docs.rs/time/0.3/time/struct.OffsetDateTime.html#method.now_utc /// [formatter]: https://docs.rs/time/0.3/time/formatting/trait.Formattable.html /// [`time` crate]: https://docs.rs/time/0.3/time/ #[derive(Clone, Debug)] -#[cfg_attr(docsrs, doc(cfg(all(feature = "time", feature = "local-time"))))] +#[cfg_attr( + docsrs, + doc(cfg(all(unsound_local_offset, feature = "time", feature = "local-time"))) +)] #[cfg(feature = "local-time")] pub struct LocalTime { format: F, @@ -62,15 +76,28 @@ impl LocalTime { /// [`time` crate] with the provided provided format. The format may be any /// type that implements the [`Formattable`] trait. /// + /// + ///
+ /// 
+    ///     Warning: The 
+    ///     time crate must be compiled with --cfg
+    ///     unsound_local_offset in order to use local timestamps. When this
+    ///     cfg is not enabled, local timestamps cannot be recorded, and
+    ///     events will be logged without timestamps.
+    ///
+    ///    See the 
+    ///    time documentation for more details.
+    ///
+ /// /// Typically, the format will be a format description string, or one of the /// `time` crate's [well-known formats]. /// /// If the format description is statically known, then the /// [`format_description!`] macro should be used. This is identical to the - /// [`time::format_description::parse] method, but runs at compile-time, + /// [`time::format_description::parse`] method, but runs at compile-time, /// throwing an error if the format description is invalid. If the desired format /// is not known statically (e.g., a user is providing a format string), then the - /// [`time::format_description::parse]` method should be used. Note that this + /// [`time::format_description::parse`] method should be used. Note that this /// method is fallible. /// /// See the [`time` book] for details on the format description syntax. @@ -184,10 +211,10 @@ impl UtcTime { /// /// If the format description is statically known, then the /// [`format_description!`] macro should be used. This is identical to the - /// [`time::format_description::parse] method, but runs at compile-time, + /// [`time::format_description::parse`] method, but runs at compile-time, /// failing an error if the format description is invalid. If the desired format /// is not known statically (e.g., a user is providing a format string), then the - /// [`time::format_description::parse]` method should be used. Note that this + /// [`time::format_description::parse`] method should be used. Note that this /// method is fallible. /// /// See the [`time` book] for details on the format description syntax. diff --git a/tracing-subscriber/src/lib.rs b/tracing-subscriber/src/lib.rs index 3f89401191..c71e2e6d07 100644 --- a/tracing-subscriber/src/lib.rs +++ b/tracing-subscriber/src/lib.rs @@ -36,7 +36,7 @@ //! **Requires "std"**. //! - `json`: Enables `fmt` support for JSON output. In JSON output, the ANSI //! feature does nothing. **Requires "fmt" and "std"**. -//! - [`local-time`]: Enables local time formatting when using the [`time` +//! - `local-time`: Enables local time formatting when using the [`time` //! crate]'s timestamp formatters with the `fmt` subscriber. //! //! ### Optional Dependencies