doc: add example for export metrics with prometheus and hyper

.github/workflows/ci.yml

@@ -195,6 +195,7 @@ jobs:
           cargo llvm-cov --no-report run --features "tracing,jaeger" --example tail_based_tracing
           cargo llvm-cov --no-report run --features "tracing,ot" --example tail_based_tracing
           cargo llvm-cov --no-report run --example equivalent
+          cargo llvm-cov --no-report run --example export_metrics_prometheus_hyper
       - name: Run foyer-bench with coverage
         if: runner.os == 'Linux'
         env:

Cargo.toml

@@ -28,8 +28,6 @@ clap = { version = "4", features = ["derive"] }
 crossbeam = "0.8"
 equivalent = "1"
 fastrace = "0.7"
-fastrace-jaeger = "0.7"
-fastrace-opentelemetry = "0.7"
 hashbrown = "0.14"
 itertools = "0.13"
 parking_lot = { version = "0.12" }
@@ -48,6 +46,7 @@ tokio = { package = "madsim-tokio", version = "0.2", features = [
     "signal",
     "fs",
 ] }
+tracing = "0.1"
 prometheus = "0.13"
 opentelemetry_0_27 = { package = "opentelemetry", version = "0.27" }
 opentelemetry_0_26 = { package = "opentelemetry", version = "0.26" }

Makefile

@@ -45,6 +45,7 @@ example:
 	cargo run --features "tracing,jaeger" --example tail_based_tracing
 	cargo run --features "tracing,ot" --example tail_based_tracing
 	cargo run --example equivalent
+	cargo run --example export_metrics_prometheus_hyper
 
 full: check-all test-all example udeps
 

examples/Cargo.toml

@@ -19,18 +19,26 @@ anyhow = "1"
 chrono = "0.4"
 equivalent = { workspace = true }
 fastrace = { workspace = true }
-fastrace-jaeger = { workspace = true, optional = true }
-fastrace-opentelemetry = { workspace = true, optional = true }
-foyer = { workspace = true }
+fastrace-jaeger = { version = "0.7", optional = true }
+fastrace-opentelemetry = { version = "0.7", optional = true }
+foyer = { workspace = true, features = ["prometheus"] }
+http-body-util = "0.1"
+hyper = { version = "1", default-features = false, features = [
+    "server",
+    "http1",
+] }
+hyper-util = { version = "0.1", default-features = false, features = ["tokio"] }
 opentelemetry = { version = "0.26", optional = true }
 opentelemetry-otlp = { version = "0.26", optional = true }
 opentelemetry-semantic-conventions = { version = "0.26", optional = true }
 opentelemetry_sdk = { version = "0.26", features = [
     "rt-tokio",
     "trace",
 ], optional = true }
+prometheus = { workspace = true }
 tempfile = "3"
 tokio = { version = "1", features = ["rt"] }
+tracing = { workspace = true }
 
 [features]
 jaeger = ["fastrace-jaeger"]
@@ -65,3 +73,7 @@ path = "tail_based_tracing.rs"
 [[example]]
 name = "equivalent"
 path = "equivalent.rs"
+
+[[example]]
+name = "export_metrics_prometheus_hyper"
+path = "export_metrics_prometheus_hyper.rs"

examples/export_metrics_prometheus_hyper.rs

@@ -0,0 +1,125 @@
+//  Copyright 2024 foyer Project Authors
+//
+//  Licensed under the Apache License, Version 2.0 (the "License");
+//  you may not use this file except in compliance with the License.
+//  You may obtain a copy of the License at
+//
+//  http://www.apache.org/licenses/LICENSE-2.0
+//
+//  Unless required by applicable law or agreed to in writing, software
+//  distributed under the License is distributed on an "AS IS" BASIS,
+//  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+//  See the License for the specific language governing permissions and
+//  limitations under the License.
+
+use std::{future::Future, net::SocketAddr, pin::Pin};
+
+use anyhow::Ok;
+use foyer::{Cache, CacheBuilder, PrometheusMetricsRegistry};
+use http_body_util::Full;
+use hyper::{
+    body::{Bytes, Incoming},
+    header::CONTENT_TYPE,
+    server::conn::http1,
+    service::Service,
+    Request, Response,
+};
+use hyper_util::rt::TokioIo;
+use prometheus::{Encoder, Registry, TextEncoder};
+use tokio::net::TcpListener;
+
+pub struct PrometheusExporter {
+    registry: Registry,
+    addr: SocketAddr,
+}
+
+impl PrometheusExporter {
+    pub fn new(registry: Registry, addr: SocketAddr) -> Self {
+        Self { registry, addr }
+    }
+
+    pub fn run(self) {
+        tokio::spawn(async move {
+            let listener = TcpListener::bind(&self.addr).await.unwrap();
+            loop {
+                let (stream, _) = match listener.accept().await {
+                    Result::Ok(res) => res,
+                    Err(e) => {
+                        tracing::error!("[prometheus exporter]: accept connection error: {e}");
+                        continue;
+                    }
+                };
+
+                let io = TokioIo::new(stream);
+                let handle = Handle {
+                    registry: self.registry.clone(),
+                };
+
+                tokio::spawn(async move {
+                    if let Err(e) = http1::Builder::new().serve_connection(io, handle).await {
+                        tracing::error!("[prometheus exporter]: serve request error: {e}");
+                    }
+                });
+            }
+        });
+    }
+}
+
+struct Handle {
+    registry: Registry,
+}
+
+impl Service<Request<Incoming>> for Handle {
+    type Response = Response<Full<Bytes>>;
+    type Error = anyhow::Error;
+    type Future = Pin<Box<dyn Future<Output = Result<Self::Response, Self::Error>> + Send>>;
+
+    fn call(&self, _: Request<Incoming>) -> Self::Future {
+        let mfs = self.registry.gather();
+
+        Box::pin(async move {
+            let encoder = TextEncoder::new();
+            let mut buffer = vec![];
+            encoder.encode(&mfs, &mut buffer)?;
+
+            Ok(Response::builder()
+                .status(200)
+                .header(CONTENT_TYPE, encoder.format_type())
+                .body(Full::new(Bytes::from(buffer)))
+                .unwrap())
+        })
+    }
+}
+
+#[tokio::main]
+async fn main() {
+    // Create a new registry or use the global registry of `prometheus` lib.
+    let registry = Registry::new();
+
+    // Create a `PrometheusExporter` powered by hyper and run it.
+    let addr = "127.0.0.1:19970".parse().unwrap();
+    PrometheusExporter::new(registry.clone(), addr).run();
+
+    // Build a cache with `PrometheusMetricsRegistry`.
+    let _: Cache<String, String> = CacheBuilder::new(100)
+        .with_metrics_registry(PrometheusMetricsRegistry::new(registry))
+        .build();
+
+    // > curl http://127.0.0.1:7890
+    //
+    // # HELP foyer_hybrid_op_duration foyer hybrid cache operation durations
+    // # TYPE foyer_hybrid_op_duration histogram
+    // foyer_hybrid_op_duration_bucket{name="foyer",op="fetch",le="0.005"} 0
+    // foyer_hybrid_op_duration_bucket{name="foyer",op="fetch",le="0.01"} 0
+    // foyer_hybrid_op_duration_bucket{name="foyer",op="fetch",le="0.025"} 0
+    // foyer_hybrid_op_duration_bucket{name="foyer",op="fetch",le="0.05"} 0
+    // foyer_hybrid_op_duration_bucket{name="foyer",op="fetch",le="0.1"} 0
+    // foyer_hybrid_op_duration_bucket{name="foyer",op="fetch",le="0.25"} 0
+    // foyer_hybrid_op_duration_bucket{name="foyer",op="fetch",le="0.5"} 0
+    // foyer_hybrid_op_duration_bucket{name="foyer",op="fetch",le="1"} 0
+    // foyer_hybrid_op_duration_bucket{name="foyer",op="fetch",le="2.5"} 0
+    // foyer_hybrid_op_duration_bucket{name="foyer",op="fetch",le="5"} 0
+    // foyer_hybrid_op_duration_bucket{name="foyer",op="fetch",le="10"} 0
+    // foyer_hybrid_op_duration_bucket{name="foyer",op="fetch",le="+Inf"} 0
+    // ... ...
+}

foyer-bench/Cargo.toml

@@ -18,7 +18,7 @@ bytesize = { workspace = true }
 clap = { workspace = true }
 console-subscriber = { version = "0.4", optional = true }
 fastrace = { workspace = true, optional = true }
-fastrace-jaeger = { workspace = true, optional = true }
+fastrace-jaeger = { version = "0.7", optional = true }
 foyer = { workspace = true, features = ["prometheus"] }
 futures = "0.3"
 hdrhistogram = "7"
@@ -36,7 +36,7 @@ rand = "0.8.5"
 serde = { workspace = true }
 serde_bytes = "0.11.15"
 tokio = { workspace = true, features = ["net"] }
-tracing = "0.1"
+tracing = { workspace = true }
 tracing-opentelemetry = { version = "0.27", optional = true }
 tracing-subscriber = { version = "0.3", features = ["env-filter"] }
 zipf = "7"

foyer-memory/Cargo.toml

@@ -29,7 +29,7 @@ pin-project = "1"
 serde = { workspace = true }
 thiserror = { workspace = true }
 tokio = { workspace = true }
-tracing = "0.1"
+tracing = { workspace = true }
 
 [dev-dependencies]
 csv = "1.3.0"

foyer-storage/Cargo.toml

@@ -45,7 +45,7 @@ rand = "0.8"
 serde = { workspace = true }
 thiserror = { workspace = true }
 tokio = { workspace = true }
-tracing = "0.1"
+tracing = { workspace = true }
 twox-hash = "1"
 zstd = "0.13"
 

foyer/Cargo.toml

@@ -23,7 +23,7 @@ foyer-storage = { workspace = true }
 futures = "0.3"
 pin-project = "1"
 tokio = { workspace = true }
-tracing = "0.1"
+tracing = { workspace = true }
 
 [dev-dependencies]
 tempfile = "3"