refactor(layers/prometheus): provide builder APIs (#5072)

* refactor(layers/prometheus): provide consistent APIs

* fix fmt

* add feature attr for observe mod

* add some comments

* update

* fix fmt

* update doc

* apply review suggestions

* adjust imports

* fix doc

* improve prometheus error handling

* move parse_prometheus_error

* fix doc example

* move register_default and align path_label

* update doc

core/src/layers/mod.rs

@@ -62,7 +62,7 @@ pub use self::mime_guess::MimeGuessLayer;
 #[cfg(feature = "layers-prometheus")]
 mod prometheus;
 #[cfg(feature = "layers-prometheus")]
-pub use self::prometheus::PrometheusLayer;
+pub use self::prometheus::{PrometheusLayer, PrometheusLayerBuilder};
 
 #[cfg(feature = "layers-prometheus-client")]
 mod prometheus_client;

core/src/layers/observe/mod.rs

@@ -18,8 +18,20 @@
 //! OpenDAL Observability Layer
 //!
 //! This module offers essential components to facilitate the implementation of observability in OpenDAL.
+//!
+//! # Prometheus Metrics
+//!
+//! These metrics are essential for understanding the behavior and performance of our applications.
+//!
+//! | Metric Name                  | Type      | Description                                                  | Labels                                          |
+//! |------------------------------|-----------|--------------------------------------------------------------|-------------------------------------------------|
+//! | operation_duration_seconds   | Histogram | Histogram of time spent during opendal operations            | scheme, namespace, root, operation, path        |
+//! | operation_bytes.             | Histogram | Histogram of the bytes transferred during opendal operations | scheme, operation, root, operation, path        |
+//! | operation_errors_total       | Counter   | Error counter during opendal operations                      | scheme, operation, root, operation, path, error |
+//!
 
 mod metrics;
+
 pub use metrics::MetricMetadata;
 pub use metrics::MetricsAccessor;
 pub use metrics::MetricsIntercept;
@@ -33,3 +45,42 @@ pub use metrics::LABEL_SCHEME;
 pub use metrics::METRIC_OPERATION_BYTES;
 pub use metrics::METRIC_OPERATION_DURATION_SECONDS;
 pub use metrics::METRIC_OPERATION_ERRORS_TOTAL;
+
+/// Return the path label value according to the given `path` and `level`.
+///
+/// - level = 0: return `None`, which means we 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'll use "abc/" as the path label.
+pub fn path_label_value(path: &str, level: usize) -> Option<&str> {
+    if path.is_empty() {
+        return None;
+    }
+
+    if level > 0 {
+        let label_value = path
+            .char_indices()
+            .filter(|&(_, c)| c == '/')
+            .nth(level - 1)
+            .map_or(path, |(i, _)| &path[..i]);
+        Some(label_value)
+    } else {
+        None
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_path_label_value() {
+        let path = "abc/def/ghi";
+        assert_eq!(path_label_value(path, 0), None);
+        assert_eq!(path_label_value(path, 1), Some("abc"));
+        assert_eq!(path_label_value(path, 2), Some("abc/def"));
+        assert_eq!(path_label_value(path, 3), Some("abc/def/ghi"));
+        assert_eq!(path_label_value(path, usize::MAX), Some("abc/def/ghi"));
+
+        assert_eq!(path_label_value("", 1), None);
+    }
+}