From 8bc68011ac55b9e4d3dfcafa26208e8a013cfe74 Mon Sep 17 00:00:00 2001 From: koushiro Date: Wed, 4 Sep 2024 01:44:01 +0800 Subject: [PATCH] update builder --- core/src/layers/prometheus.rs | 12 +- core/src/layers/prometheus_client.rs | 183 ++++++++++++++++++++------- 2 files changed, 145 insertions(+), 50 deletions(-) diff --git a/core/src/layers/prometheus.rs b/core/src/layers/prometheus.rs index 85bb29edcdd..458afd36b96 100644 --- a/core/src/layers/prometheus.rs +++ b/core/src/layers/prometheus.rs @@ -319,7 +319,7 @@ impl PrometheusLayerBuilder { ), &labels, ) - .map_err(parse_prometheus_error)?; + .map_err(parse_prometheus_error)?; let operation_bytes = HistogramVec::new( histogram_opts!( observe::METRIC_OPERATION_BYTES.name(), @@ -328,7 +328,7 @@ impl PrometheusLayerBuilder { ), &labels, ) - .map_err(parse_prometheus_error)?; + .map_err(parse_prometheus_error)?; let labels = OperationLabels::names(true, self.path_label_level); let operation_errors_total = GenericCounterVec::new( @@ -338,7 +338,7 @@ impl PrometheusLayerBuilder { ), &labels, ) - .map_err(parse_prometheus_error)?; + .map_err(parse_prometheus_error)?; registry .register(Box::new(operation_duration_seconds.clone())) @@ -425,7 +425,7 @@ impl observe::MetricsIntercept for PrometheusInterceptor { error: None, path, } - .into_values(self.path_label_level); + .into_values(self.path_label_level); self.operation_duration_seconds .with_label_values(&labels) @@ -449,7 +449,7 @@ impl observe::MetricsIntercept for PrometheusInterceptor { error: None, path, } - .into_values(self.path_label_level); + .into_values(self.path_label_level); self.operation_bytes .with_label_values(&labels) @@ -473,7 +473,7 @@ impl observe::MetricsIntercept for PrometheusInterceptor { error: Some(error), path, } - .into_values(self.path_label_level); + .into_values(self.path_label_level); self.operation_errors_total.with_label_values(&labels).inc(); } diff --git a/core/src/layers/prometheus_client.rs b/core/src/layers/prometheus_client.rs index eb21585553e..38c4120d496 100644 --- a/core/src/layers/prometheus_client.rs +++ b/core/src/layers/prometheus_client.rs @@ -35,6 +35,11 @@ use crate::*; /// Add [prometheus-client](https://docs.rs/prometheus-client) for every operation. /// +/// # Prometheus Metrics +/// +/// We provide several metrics, please see the documentation of [`observe`] module. +/// For a more detailed explanation of these metrics and how they are used, please refer to the [Prometheus documentation](https://prometheus.io/docs/introduction/overview/). +/// /// # Examples /// /// ```no_run @@ -51,9 +56,8 @@ use crate::*; /// let builder = services::Memory::default(); /// let mut registry = prometheus_client::registry::Registry::default(); /// -/// let op = Operator::new(builder) -/// .expect("must init") -/// .layer(PrometheusClientLayer::new(&mut registry)) +/// let op = Operator::new(builder)? +/// .layer(PrometheusClientLayer::builder().register(&mut registry)) /// .finish(); /// debug!("operator: {op:?}"); /// @@ -81,37 +85,13 @@ pub struct PrometheusClientLayer { } impl PrometheusClientLayer { - /// Create a new [`PrometheusClientLayer`] and register its metrics to the given registry. - /// - /// # Examples - /// - /// ```no_run - /// # use log::debug; - /// # use opendal::layers::PrometheusClientLayer; - /// # use opendal::services; - /// # use opendal::Operator; - /// # use opendal::Result; - /// - /// # #[tokio::main] - /// # async fn main() -> Result<()> { - /// // Pick a builder and configure it. - /// let builder = services::Memory::default(); - /// let mut registry = prometheus_client::registry::Registry::default(); + /// Create a [`PrometheusClientLayerBuilder`] to set the configuration of metrics. /// - /// let op = Operator::new(builder) - /// .expect("must init") - /// .layer(PrometheusClientLayer::new(&mut registry)) - /// .finish(); - /// debug!("operator: {op:?}"); + /// # Default Configuration /// - /// Ok(()) - /// # } - /// ``` - pub fn new(registry: &mut Registry) -> Self { - PrometheusClientLayerBuilder::default().register(registry) - } - - /// Create a [`PrometheusClientLayerBuilder`] to modify the default metric configuration. + /// - `operation_duration_seconds_buckets`: `exponential_buckets(0.01, 2.0, 16)` + /// - `operation_bytes_buckets`: `exponential_buckets(1.0, 2.0, 16)` + /// - `path_label`: `0` /// /// # Examples /// @@ -130,13 +110,12 @@ impl PrometheusClientLayer { /// /// let duration_seconds_buckets = prometheus_client::metrics::histogram::exponential_buckets(0.01, 2.0, 16).collect(); /// let bytes_buckets = prometheus_client::metrics::histogram::exponential_buckets(1.0, 2.0, 16).collect(); - /// let op = Operator::new(builder) - /// .expect("must init") + /// let op = Operator::new(builder)? /// .layer( /// PrometheusClientLayer::builder() /// .operation_duration_seconds_buckets(duration_seconds_buckets) /// .operation_bytes_buckets(bytes_buckets) - /// .enable_path_label(1) + /// .path_label(0) /// .register(&mut registry) /// ) /// .finish(); @@ -146,7 +125,13 @@ impl PrometheusClientLayer { /// # } /// ``` pub fn builder() -> PrometheusClientLayerBuilder { - PrometheusClientLayerBuilder::default() + let operation_duration_seconds_buckets = exponential_buckets(0.01, 2.0, 16).collect(); + let operation_bytes_buckets = exponential_buckets(1.0, 2.0, 16).collect(); + PrometheusClientLayerBuilder::new( + operation_duration_seconds_buckets, + operation_bytes_buckets, + 0, + ) } } @@ -165,20 +150,49 @@ pub struct PrometheusClientLayerBuilder { path_label_level: usize, } -impl Default for PrometheusClientLayerBuilder { - fn default() -> Self { - let operation_duration_seconds_buckets = exponential_buckets(0.01, 2.0, 16).collect(); - let operation_bytes_buckets = exponential_buckets(1.0, 2.0, 16).collect(); +impl PrometheusClientLayerBuilder { + fn new( + operation_duration_seconds_buckets: Vec, + operation_bytes_buckets: Vec, + path_label_level: usize, + ) -> Self { Self { operation_duration_seconds_buckets, operation_bytes_buckets, - path_label_level: 0, + path_label_level, } } -} -impl PrometheusClientLayerBuilder { /// Set buckets for `operation_duration_seconds` histogram. + /// + /// # Examples + /// + /// ```no_run + /// # use log::debug; + /// # use opendal::layers::PrometheusClientLayer; + /// # use opendal::services; + /// # use opendal::Operator; + /// # use opendal::Result; + /// + /// # #[tokio::main] + /// # async fn main() -> Result<()> { + /// // Pick a builder and configure it. + /// let builder = services::Memory::default(); + /// let mut registry = prometheus_client::registry::Registry::default(); + /// + /// let buckets = prometheus_client::metrics::histogram::exponential_buckets(0.01, 2.0, 16).collect(); + /// let op = Operator::new(builder)? + /// .layer( + /// PrometheusClientLayer::builder() + /// .operation_duration_seconds_buckets(buckets) + /// .register(&mut registry) + /// ) + /// .finish(); + /// debug!("operator: {op:?}"); + /// + /// Ok(()) + /// # } + /// ``` pub fn operation_duration_seconds_buckets(mut self, buckets: Vec) -> Self { if !buckets.is_empty() { self.operation_duration_seconds_buckets = buckets; @@ -187,6 +201,35 @@ impl PrometheusClientLayerBuilder { } /// Set buckets for `operation_bytes` histogram. + /// + /// # Examples + /// + /// ```no_run + /// # use log::debug; + /// # use opendal::layers::PrometheusClientLayer; + /// # use opendal::services; + /// # use opendal::Operator; + /// # use opendal::Result; + /// + /// # #[tokio::main] + /// # async fn main() -> Result<()> { + /// // Pick a builder and configure it. + /// let builder = services::Memory::default(); + /// let mut registry = prometheus_client::registry::Registry::default(); + /// + /// let buckets = prometheus_client::metrics::histogram::exponential_buckets(1.0, 2.0, 16).collect(); + /// let op = Operator::new(builder)? + /// .layer( + /// PrometheusClientLayer::builder() + /// .operation_bytes_buckets(buckets) + /// .register(&mut registry) + /// ) + /// .finish(); + /// debug!("operator: {op:?}"); + /// + /// Ok(()) + /// # } + /// ``` pub fn operation_bytes_buckets(mut self, buckets: Vec) -> Self { if !buckets.is_empty() { self.operation_bytes_buckets = buckets; @@ -199,12 +242,64 @@ impl PrometheusClientLayerBuilder { /// - level = 0: we will ignore the path label. /// - level > 0: the path label will be the path split by "/" and get the last n level, /// if n=1 and input path is "abc/def/ghi", and then we will get "abc/" as the path label. - pub fn enable_path_label(mut self, level: usize) -> Self { + /// + /// # Examples + /// + /// ```no_run + /// # use log::debug; + /// # use opendal::layers::PrometheusClientLayer; + /// # use opendal::services; + /// # use opendal::Operator; + /// # use opendal::Result; + /// + /// # #[tokio::main] + /// # async fn main() -> Result<()> { + /// // Pick a builder and configure it. + /// let builder = services::Memory::default(); + /// let mut registry = prometheus_client::registry::Registry::default(); + /// + /// let op = Operator::new(builder)? + /// .layer( + /// PrometheusClientLayer::builder() + /// .path_label(1) + /// .register(&mut registry) + /// ) + /// .finish(); + /// debug!("operator: {op:?}"); + /// + /// Ok(()) + /// # } + /// ``` + pub fn path_label(mut self, level: usize) -> Self { self.path_label_level = level; self } /// Register the metrics into the registry and return a [`PrometheusClientLayer`]. + /// + /// # Examples + /// + /// ```no_run + /// # use log::debug; + /// # use opendal::layers::PrometheusClientLayer; + /// # use opendal::services; + /// # use opendal::Operator; + /// # use opendal::Result; + /// + /// # #[tokio::main] + /// # async fn main() -> Result<()> { + /// // Pick a builder and configure it. + /// let builder = services::Memory::default(); + /// let mut registry = prometheus_client::registry::Registry::default(); + /// + /// let op = Operator::new(builder)? + /// .layer(PrometheusClientLayer::builder().register(&mut registry)) + /// .finish(); + /// debug!("operator: {op:?}"); + /// + /// Ok(()) + /// # } + /// ``` pub fn register(self, registry: &mut Registry) -> PrometheusClientLayer { let operation_duration_seconds = Family::::new_with_constructor(HistogramConstructor {