diff --git a/crates/stackable-telemetry/src/instrumentation/axum/mod.rs b/crates/stackable-telemetry/src/instrumentation/axum/mod.rs index d4ea09639..7ef2fc22f 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 a400d96d6..a4ca1c8a0 100644 --- a/crates/stackable-telemetry/src/tracing/mod.rs +++ b/crates/stackable-telemetry/src/tracing/mod.rs @@ -25,23 +25,36 @@ 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, }, - #[snafu(display("unable to set the global default subscriber"))] - SetGlobalDefaultSubscriber { source: SetGlobalDefaultError }, - + /// Indicates that [`Tracing`] failed to install the rolling file appender. #[snafu(display("failed to initialize rolling file appender"))] - InitRollingFileAppender { source: InitError }, + InitRollingFileAppender { + #[allow(missing_docs)] + source: InitError, + }, + + /// Indicates that [`Tracing`] failed to set the global default subscriber. + #[snafu(display("unable to set the global default subscriber"))] + SetGlobalDefaultSubscriber { + #[allow(missing_docs)] + source: SetGlobalDefaultError, + }, } /// Easily initialize a set of pre-configured [`Subscriber`][1] layers. @@ -225,6 +238,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..2823d774a 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,19 @@ 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..45cf00db5 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,19 @@ 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,