Merge pull request #3 from msalinas92/feature/prometheus-metrics

feat: prometheus-metrics

Author: msalinas92

Cargo.lock

@@ -52,11 +52,14 @@ hex = "0.4.3"
 bincode = "2.0.1"
 base64 = "0.22.1"
 regex = "1.11.1"
+metrics = "0.24.2"
+metrics-macros = "0.7.1"
+metrics-exporter-prometheus = "0.17.0"
 
 
 [dev-dependencies]
 tokio = { version = "1", features = ["macros", "rt-multi-thread", "test-util"] }
 ctor = "0.2"
 tempfile = "3"
 http-body-util = "0.1"
-http = "0.2"
+http = "0.2"

Cargo.toml

@@ -191,6 +191,62 @@ See `.github/workflows/release.yml` for cross-target examples.
 
 ---
 
+## 📊 Prometheus Metrics
+
+CacheBolt exposes Prometheus-compatible metrics at the `/metrics` endpoint on port `3000`. These metrics allow you to monitor request flow, latency thresholds, memory caching, and backend persistence.
+
+### Request Metrics
+
+- `cachebolt_proxy_requests_total{uri}`  
+  Total number of proxy requests received, labeled by URI.
+
+- `cachebolt_downstream_failures_total{uri}`  
+  Count of downstream request failures per URI.
+
+- `cachebolt_rejected_due_to_concurrency_total{uri}`  
+  Requests rejected due to max concurrency being exceeded.
+
+- `cachebolt_failover_total{uri}`  
+  Requests served via failover mode due to recent high latency.
+
+### In-Memory Cache Metrics
+
+- `cachebolt_memory_hits_total{uri}`  
+  Requests served directly from the in-memory cache.
+
+- `cachebolt_memory_store_total{uri}`  
+  Responses stored into the in-memory cache.
+
+- `cachebolt_memory_fallback_hits_total`  
+  Failover-mode requests served from memory cache.
+
+### Latency Monitoring
+
+- `cachebolt_proxy_request_latency_ms{uri}`  
+  Histogram of proxy request latency in milliseconds.
+
+- `cachebolt_latency_exceeded_ms{uri}`  
+  Histogram of requests whose latency exceeded the configured threshold.
+
+- `cachebolt_latency_exceeded_total{uri}`  
+  Count of latency threshold violations per URI.
+
+### Persistent Storage Metrics
+
+- `cachebolt_persist_attempts_total{backend}`  
+  Number of attempts to persist cache entries into the selected backend.
+
+- `cachebolt_persist_errors_total{backend}`  
+  Number of failed attempts to persist cache entries.
+
+- `cachebolt_persistent_fallback_hits_total`  
+  Requests served from persistent storage (GCS, S3, Azure, or local) during failover.
+
+- `cachebolt_fallback_miss_total`  
+  Count of failover attempts that missed both memory and persistent storage.
+
+---
+
 ## 📄 License
 
 Licensed under the [Apache License 2.0](./LICENSE).

README.md

@@ -22,4 +22,5 @@ latency_failover:
       max_latency_ms: 100
 
 ignored_headers:
-  - postman-token
+  - postman-token
+  - if-none-match

config.yaml

@@ -17,30 +17,31 @@
 // ----------------------
 // These are internal modules for handling the proxy logic, caching layers,
 // configuration loading, and in-memory eviction based on memory pressure.
-mod proxy;
-mod storage;
-mod memory;
 mod config;
 mod eviction;
+mod memory;
+mod proxy;
 mod rules;
+mod storage;
 
 // ----------------------
 // External dependencies
 // ----------------------
-use axum::{routing::get, Router};               // Axum: Web framework for routing and request handling
-use hyper::Server;                              // Hyper: High-performance HTTP server
-use std::{net::SocketAddr, process::exit};      // Network + system utilities
+use axum::{Router, routing::get}; // Axum: Web framework for routing and request handling
+use hyper::Server; // Hyper: High-performance HTTP server
+use std::{net::SocketAddr, process::exit}; // Network + system utilities
 
-use clap::Parser;                               // CLI argument parsing (via `--config`)
-use tracing::{info, warn, error};               // Structured logging macros
-use tracing_subscriber::EnvFilter;              // Log filtering via LOG_LEVEL
+use clap::Parser; // CLI argument parsing (via `--config`)
+use tracing::{error, info, warn}; // Structured logging macros
+use tracing_subscriber::EnvFilter; // Log filtering via LOG_LEVEL
 
 // ----------------------
 // Internal dependencies
 // ----------------------
-use crate::config::{Config, CONFIG, StorageBackend};             // App-wide config definitions
-use crate::eviction::start_background_eviction_task;             // Memory pressure eviction
-use crate::storage::{gcs, s3, azure};                             // Persistent storage backends
+use crate::config::{CONFIG, Config, StorageBackend}; // App-wide config definitions
+use crate::eviction::start_background_eviction_task; // Memory pressure eviction
+use crate::storage::{azure, gcs, s3}; // Persistent storage backends
+use metrics_exporter_prometheus::PrometheusBuilder;
 
 /// ----------------------------
 /// CLI ARGUMENT STRUCTURE
@@ -79,9 +80,9 @@ fn init_logging(app_id: &str) {
         .unwrap_or_else(|_| EnvFilter::new("info"));
 
     tracing_subscriber::fmt()
-        .with_env_filter(filter)   // Uses LOG_LEVEL to filter verbosity
-        .with_target(false)        // Hides the module path in each log line
-        .compact()                 // Compact single-line logs (less verbose)
+        .with_env_filter(filter) // Uses LOG_LEVEL to filter verbosity
+        .with_target(false) // Hides the module path in each log line
+        .compact() // Compact single-line logs (less verbose)
         .init();
 
     info!("🚀 Logging initialized for app_id: {app_id}");
@@ -159,11 +160,17 @@ async fn main() {
     // 3. Initialize the logger using app_id for context
     // ------------------------------------------------------
     init_logging(&config.app_id);
+    let builder = PrometheusBuilder::new();
+    let handle = builder
+        .install_recorder()
+        .expect("❌ Failed to install Prometheus recorder");
 
     // ------------------------------------------------------
     // 4. Set global CONFIG (OnceCell) for use across modules
     // ------------------------------------------------------
-    CONFIG.set(config).expect("❌ CONFIG was already initialized");
+    CONFIG
+        .set(config)
+        .expect("❌ CONFIG was already initialized");
 
     // ------------------------------------------------------
     // 5. Initialize persistent storage backend (GCS, S3, Azure, Local)
@@ -181,7 +188,9 @@ async fn main() {
     // 7. Define Axum router with a single wildcard route
     //    All incoming GET requests will be handled by the proxy logic.
     // ------------------------------------------------------
-    let app = Router::new().route("/*path", get(proxy::proxy_handler));
+    let app = Router::new()
+        .route("/metrics", get(move || async move { handle.render() }))
+        .route("/*path", get(proxy::proxy_handler));
 
     // ------------------------------------------------------
     // 8. Bind the server to all interfaces on port 3000
@@ -196,4 +205,4 @@ async fn main() {
         .serve(app.into_make_service())
         .await
         .unwrap();
-}
+}