From 455026d223b8db611c260b3fb0a1614ab05f81b3 Mon Sep 17 00:00:00 2001 From: Techassi Date: Fri, 17 Jan 2025 16:35:27 +0100 Subject: [PATCH 1/3] docs(stackable-telemetry): Add #![warn(missing_docs)] --- .../src/instrumentation/axum/mod.rs | 24 +++++++++++++++---- crates/stackable-telemetry/src/lib.rs | 6 +++-- crates/stackable-telemetry/src/tracing/mod.rs | 12 +++++++++- .../src/tracing/settings/console_log.rs | 10 ++++---- .../src/tracing/settings/otlp_log.rs | 8 +++++++ .../src/tracing/settings/otlp_trace.rs | 8 +++++++ 6 files changed, 56 insertions(+), 12 deletions(-) diff --git a/crates/stackable-telemetry/src/instrumentation/axum/mod.rs b/crates/stackable-telemetry/src/instrumentation/axum/mod.rs index 5b88c437b..807ad472e 100644 --- a/crates/stackable-telemetry/src/instrumentation/axum/mod.rs +++ b/crates/stackable-telemetry/src/instrumentation/axum/mod.rs @@ -173,20 +173,34 @@ where } } +/// Errors which can be encountered when extracting the server host from a [`Request`]. #[derive(Debug, Snafu)] pub enum ServerHostError { + /// Indicates that parsing the port of the server host from the [`Request`] as a `u16` failed. #[snafu(display("failed to parse port {port:?} as u16 from string"))] - ParsePort { source: ParseIntError, port: String }, + ParsePort { + #[allow(missing_docs)] + source: ParseIntError, + // TODO (@Techassi): Make snafu re-emit this + /// The original input which was attempted to be parsed. + port: String, + }, + + /// Indicates that the server host from the [`Request`] contains an invalid/unknown scheme. #[snafu(display("encountered invalid request scheme {scheme:?}"))] - InvalidScheme { scheme: String }, + InvalidScheme { + /// The original scheme. + scheme: String, + }, + // TODO (@Techassi): Make snafu re-emit this + /// Indicates that no method of extracting the server host from the [`Request`] succeeded. #[snafu(display("failed to extract any host information from request"))] ExtractHost, } -/// This trait provides various helper functions to extract data from a -/// HTTP [`Request`]. +/// This trait provides various helper functions to extract data from a HTTP [`Request`]. pub trait RequestExt { /// Returns the client socket address, if available. fn client_socket_address(&self) -> Option; @@ -429,7 +443,7 @@ impl SpanExt for Span { // Therefore, we have to made a decision about linking the two traces. // These are the options: // 1. Link to the trace id supplied in the incoming request, or - // 2. Link to the current trace id, then set the parent contex based on + // 2. Link to the current trace id, then set the parent context based on // trace information supplied in the incoming request. // // Neither is ideal, as it means there are (at least) two traces to look diff --git a/crates/stackable-telemetry/src/lib.rs b/crates/stackable-telemetry/src/lib.rs index 7cc6c6461..c7d926992 100644 --- a/crates/stackable-telemetry/src/lib.rs +++ b/crates/stackable-telemetry/src/lib.rs @@ -1,5 +1,7 @@ -//! This crate contains various Tracing, Logging, and OpenTelemtry primitives to -//! easily instrument code. +#![warn(missing_docs)] + +//! This crate contains various Tracing, Logging, and OpenTelemetry primitives to easily instrument +//! code. pub mod instrumentation; pub mod tracing; diff --git a/crates/stackable-telemetry/src/tracing/mod.rs b/crates/stackable-telemetry/src/tracing/mod.rs index 8493d8106..cf50dfc51 100644 --- a/crates/stackable-telemetry/src/tracing/mod.rs +++ b/crates/stackable-telemetry/src/tracing/mod.rs @@ -24,20 +24,29 @@ pub mod settings; type Result = std::result::Result; +/// Errors which can be encountered when initialising [`Tracing`]. #[derive(Debug, Snafu)] pub enum Error { + /// Indicates that [`Tracing`] failed to install the OpenTelemetry trace exporter. #[snafu(display("unable to install opentelemetry trace exporter"))] InstallOtelTraceExporter { + #[allow(missing_docs)] source: opentelemetry::trace::TraceError, }, + /// Indicates that [`Tracing`] failed to install the OpenTelemetry log exporter. #[snafu(display("unable to install opentelemetry log exporter"))] InstallOtelLogExporter { + #[allow(missing_docs)] source: opentelemetry::logs::LogError, }, + /// Indicates that [`Tracing`] failed to set the global default subscriber. #[snafu(display("unable to set the global default subscriber"))] - SetGlobalDefaultSubscriber { source: SetGlobalDefaultError }, + SetGlobalDefaultSubscriber { + #[allow(missing_docs)] + source: SetGlobalDefaultError, + }, } /// Easily initialize a set of pre-configured [`Subscriber`][1] layers. @@ -220,6 +229,7 @@ pub struct Tracing { } impl Tracing { + /// Creates and returns a [`TracingBuilder`]. pub fn builder() -> TracingBuilder { TracingBuilder::default() } diff --git a/crates/stackable-telemetry/src/tracing/settings/console_log.rs b/crates/stackable-telemetry/src/tracing/settings/console_log.rs index dc26379fd..71515d77e 100644 --- a/crates/stackable-telemetry/src/tracing/settings/console_log.rs +++ b/crates/stackable-telemetry/src/tracing/settings/console_log.rs @@ -6,13 +6,13 @@ use tracing::level_filters::LevelFilter; use super::{Settings, SettingsBuilder}; -/// Configure specific settings for the Console Log subscriber. +/// Configure specific settings for the console log subscriber. #[derive(Debug, Default, PartialEq)] pub struct ConsoleLogSettings { - /// Common subscriber settings that apply to the Console Log Subscriber. + /// Common subscriber settings that apply to the console log subscriber. pub common_settings: Settings, - /// Console Subscriber log event output format. + /// Console subscriber log event output format. pub log_format: Format, } @@ -24,7 +24,7 @@ impl Deref for ConsoleLogSettings { } } -/// Console Subscriber log event output formats. +/// Console subscriber log event output formats. /// /// Currently, only [Plain][Format::Plain] is supported. #[derive(Debug, Default, PartialEq)] @@ -52,11 +52,13 @@ pub struct ConsoleLogSettingsBuilder { } impl ConsoleLogSettingsBuilder { + /// Overrides the default log [`Format`]. pub fn with_log_format(mut self, format: Format) -> Self { self.log_format = format; self } + /// Consumes `self` and builds [`ConsoleLogSettings`]. pub fn build(self) -> ConsoleLogSettings { ConsoleLogSettings { common_settings: self.common_settings, diff --git a/crates/stackable-telemetry/src/tracing/settings/otlp_log.rs b/crates/stackable-telemetry/src/tracing/settings/otlp_log.rs index e885faaaa..5c3a46e34 100644 --- a/crates/stackable-telemetry/src/tracing/settings/otlp_log.rs +++ b/crates/stackable-telemetry/src/tracing/settings/otlp_log.rs @@ -6,8 +6,10 @@ use tracing::level_filters::LevelFilter; use super::{Settings, SettingsBuilder}; +/// Configure specific settings for the OpenTelemetry log subscriber. #[derive(Debug, Default, PartialEq)] pub struct OtlpLogSettings { + /// Common subscriber settings that apply to the OpenTelemetry log subscriber. pub common_settings: Settings, } @@ -19,11 +21,17 @@ impl Deref for OtlpLogSettings { } } +/// For building [`OtlpLogSettings`]. +/// +///
+/// Do not use directly, instead use the [`Settings::builder`] associated function. +///
pub struct OtlpLogSettingsBuilder { pub(crate) common_settings: Settings, } impl OtlpLogSettingsBuilder { + /// Consumes `self` and builds [`OtlpLogSettings`]. pub fn build(self) -> OtlpLogSettings { OtlpLogSettings { common_settings: self.common_settings, diff --git a/crates/stackable-telemetry/src/tracing/settings/otlp_trace.rs b/crates/stackable-telemetry/src/tracing/settings/otlp_trace.rs index 98f9ab6fa..ccdd6fd89 100644 --- a/crates/stackable-telemetry/src/tracing/settings/otlp_trace.rs +++ b/crates/stackable-telemetry/src/tracing/settings/otlp_trace.rs @@ -6,8 +6,10 @@ use tracing::level_filters::LevelFilter; use super::{Settings, SettingsBuilder}; +/// Configure specific settings for the OpenTelemetry trace subscriber. #[derive(Debug, Default, PartialEq)] pub struct OtlpTraceSettings { + /// Common subscriber settings that apply to the OpenTelemetry trace subscriber. pub common_settings: Settings, } @@ -19,11 +21,17 @@ impl Deref for OtlpTraceSettings { } } +/// For building [`OtlpTraceSettings`]. +/// +///
+/// Do not use directly, instead use the [`Settings::builder`] associated function. +///
pub struct OtlpTraceSettingsBuilder { pub(crate) common_settings: Settings, } impl OtlpTraceSettingsBuilder { + /// Consumes `self` and builds [`OtlpTraceSettings`]. pub fn build(self) -> OtlpTraceSettings { OtlpTraceSettings { common_settings: self.common_settings, From 53d60a3bf1622e2d1677ac733af7b979365e1fd9 Mon Sep 17 00:00:00 2001 From: Techassi Date: Tue, 18 Feb 2025 12:13:17 +0100 Subject: [PATCH 2/3] chore: Apply suggestions Co-authored-by: Siegfried Weber --- crates/stackable-telemetry/src/tracing/settings/otlp_log.rs | 2 ++ crates/stackable-telemetry/src/tracing/settings/otlp_trace.rs | 2 ++ 2 files changed, 4 insertions(+) diff --git a/crates/stackable-telemetry/src/tracing/settings/otlp_log.rs b/crates/stackable-telemetry/src/tracing/settings/otlp_log.rs index 5c3a46e34..2823d774a 100644 --- a/crates/stackable-telemetry/src/tracing/settings/otlp_log.rs +++ b/crates/stackable-telemetry/src/tracing/settings/otlp_log.rs @@ -24,7 +24,9 @@ impl Deref for OtlpLogSettings { /// For building [`OtlpLogSettings`]. /// ///
+/// /// Do not use directly, instead use the [`Settings::builder`] associated function. +/// ///
pub struct OtlpLogSettingsBuilder { pub(crate) common_settings: Settings, diff --git a/crates/stackable-telemetry/src/tracing/settings/otlp_trace.rs b/crates/stackable-telemetry/src/tracing/settings/otlp_trace.rs index ccdd6fd89..45cf00db5 100644 --- a/crates/stackable-telemetry/src/tracing/settings/otlp_trace.rs +++ b/crates/stackable-telemetry/src/tracing/settings/otlp_trace.rs @@ -24,7 +24,9 @@ impl Deref for OtlpTraceSettings { /// For building [`OtlpTraceSettings`]. /// ///
+/// /// Do not use directly, instead use the [`Settings::builder`] associated function. +/// ///
pub struct OtlpTraceSettingsBuilder { pub(crate) common_settings: Settings, From 077f506b83145fd317146267cb8f0fdfd876d0b5 Mon Sep 17 00:00:00 2001 From: Techassi Date: Tue, 18 Feb 2025 12:37:01 +0100 Subject: [PATCH 3/3] chore: Apply suggestion Co-authored-by: Siegfried Weber --- crates/stackable-telemetry/src/tracing/mod.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/crates/stackable-telemetry/src/tracing/mod.rs b/crates/stackable-telemetry/src/tracing/mod.rs index 200382083..a4ca1c8a0 100644 --- a/crates/stackable-telemetry/src/tracing/mod.rs +++ b/crates/stackable-telemetry/src/tracing/mod.rs @@ -42,7 +42,7 @@ pub enum Error { source: opentelemetry::logs::LogError, }, - /// Indicates that [`Tracing`] failed to installed the rolling file appender subscriber. + /// Indicates that [`Tracing`] failed to install the rolling file appender. #[snafu(display("failed to initialize rolling file appender"))] InitRollingFileAppender { #[allow(missing_docs)]