feat: add Prometheus metrics foundation with /metrics admin endpoint

- Add /metrics scrape endpoint to the admin listener alongside /healthy and /ready.
- Install metrics + metrics-exporter-prometheus as workspace dependencies.
- Emit praxis_http_requests_total counter and
  praxis_http_request_duration_seconds histogram from both HTTP handler logging hooks.
- Labels: method, status_class (2xx/3xx/4xx/5xx), route (placeholder unknown),
  cluster (from router or none).

Signed-off-by: Brent Salisbury <bsalisbu@redhat.com>

Author: nerdalert

Cargo.lock

@@ -45,6 +45,8 @@ criterion = { version = "0.8.2", features = ["async_tokio"] }
 futures = "0.3.32"
 h2 = "0.4.13"
 http = "1.4.0"
+metrics = "0.24.2"
+metrics-exporter-prometheus = { version = "0.16.2", default-features = false }
 # Pinned to match Pingora's dependency.
 nix = "0.24.3"
 notify = "7.0.0"

Cargo.toml

@@ -20,15 +20,22 @@ insecure_options:      # Optional. Dev/test overrides. See development.md.
 ## Admin
 
 `admin.address` binds a separate HTTP listener that serves
-`/ready` and `/healthy`. `/healthy` returns `200 OK` with
-`{"status":"ok"}` once the server is accepting
-connections (liveness). `/ready` returns per-cluster
-health status with healthy/unhealthy/total counts when
-active health checks are configured; it returns 503
-when any cluster has zero healthy endpoints. Without
-health checks, `/ready` returns `{"status":"ok"}`. Any
-other path returns 404. Useful for orchestrator health
-checks without exposing them on the main listeners.
+`/healthy`, `/ready`, and `/metrics`.
+
+- `/healthy` returns `200 OK` with `{"status":"ok"}`
+  once the server is accepting connections (liveness).
+- `/ready` returns per-cluster health status with
+  healthy/unhealthy/total counts when active health
+  checks are configured; it returns 503 when any
+  cluster has zero healthy endpoints. Without health
+  checks, `/ready` returns `{"status":"ok"}`.
+- `/metrics` returns Prometheus text exposition format
+  with HTTP request metrics (`praxis_http_requests_total`,
+  `praxis_http_request_duration_seconds`).
+
+Any other path returns 404. Useful for orchestrator
+health checks and monitoring without exposing them on
+the main listeners.
 
 ```yaml
 admin:

docs/configuration.md

@@ -1,19 +1,21 @@
 # Admin Interface
 #
-# Exposes an admin endpoint for operational health checks
-# and readiness probes. The admin listener is separate from
-# data-plane traffic and serves:
+# Exposes an admin endpoint for operational health checks,
+# readiness probes, and Prometheus metrics. The admin listener
+# is separate from data-plane traffic and serves:
 #
-#   GET /health   liveness probe (always 200)
+#   GET /healthy  liveness probe (always 200)
 #   GET /ready    readiness probe (checks upstream clusters)
+#   GET /metrics  Prometheus text exposition format
 #
 # With `verbose: true`, the /ready response includes
 # per-cluster health detail in the body.
 #
 # Usage:
 #   cargo run -p praxis -- -c examples/configs/operations/admin-interface.yaml
-#   curl http://localhost:9901/health     # liveness
+#   curl http://localhost:9901/healthy    # liveness
 #   curl http://localhost:9901/ready      # readiness (verbose)
+#   curl http://localhost:9901/metrics    # prometheus scrape
 
 admin:
   address: "127.0.0.1:9901"

examples/configs/operations/admin-interface.yaml

@@ -21,6 +21,8 @@ async-trait = { workspace = true }
 bytes = { workspace = true }
 futures = { workspace = true }
 http = { workspace = true }
+metrics = { workspace = true }
+metrics-exporter-prometheus = { workspace = true }
 pingora-core = { workspace = true }
 pingora-http = { workspace = true }
 pingora-proxy = { workspace = true }

protocol/Cargo.toml

@@ -53,6 +53,11 @@ pub struct PingoraRequestCtx {
     /// bytes are raw protocol frames (e.g. `WebSocket`), not HTTP bodies.
     pub connection_upgraded: bool,
 
+    /// Cluster name snapshot retained for metrics emission in the
+    /// `logging()` hook, after `cluster` has been consumed by filter
+    /// context construction.
+    pub metrics_cluster: Option<Arc<str>>,
+
     /// Pre-read body chunks (`StreamBuffer` mode). When `StreamBuffer` is
     /// active, the body is read during `request_filter` (before upstream
     /// selection) so that body-based routing can influence `upstream_peer`.
@@ -237,6 +242,7 @@ impl Default for PingoraRequestCtx {
             client_http_version: None,
             cluster: None,
             connection_upgraded: false,
+            metrics_cluster: None,
             pre_read_body: None,
             request_body_buffer: None,
             request_body_bytes: 0,

protocol/src/http/pingora/context.rs

@@ -11,7 +11,7 @@ use praxis_filter::{CompressionConfig, FilterPipeline};
 use tokio::sync::Semaphore;
 use tracing::{debug, warn};
 
-use super::context::PingoraRequestCtx;
+use super::{context::PingoraRequestCtx, metrics};
 
 /// Shared hop-by-hop header stripping logic.
 mod hop_by_hop;
@@ -213,6 +213,27 @@ async fn logging_cleanup(pipeline: &FilterPipeline, ctx: &mut PingoraRequestCtx)
     }
 }
 
+/// Emit Prometheus metrics for a completed HTTP request.
+fn emit_request_metrics(session: &Session, ctx: &PingoraRequestCtx) {
+    let status_code = session.response_written().map_or(0, |resp| resp.status.as_u16());
+    let status_class = metrics::status_class(status_code);
+
+    let raw_method = ctx.request_snapshot.as_ref().map_or("UNKNOWN", |r| r.method.as_str());
+    let method = metrics::method_label(raw_method);
+
+    let cluster_name: &str = ctx.metrics_cluster.as_deref().unwrap_or("none");
+
+    let labels = metrics::RequestMetricLabels {
+        method,
+        status_class,
+        route: "unknown",
+        cluster: cluster_name,
+    };
+
+    let duration_secs = ctx.request_start.elapsed().as_secs_f64();
+    metrics::record_request_metrics(&labels, duration_secs);
+}
+
 /// Build [`HttpServerOptions`] with h2c enabled.
 ///
 /// [`HttpServerOptions`]: pingora_core::apps::HttpServerOptions

protocol/src/http/pingora/handler/mod.rs

@@ -17,8 +17,8 @@ use tokio::sync::Semaphore;
 use tracing::{debug, warn};
 
 use super::{
-    adjust_compression, handle_connect_failure, logging_cleanup, request_filter, response_filter, upstream_peer,
-    upstream_request, via,
+    adjust_compression, emit_request_metrics, handle_connect_failure, logging_cleanup, request_filter, response_filter,
+    upstream_peer, upstream_request, via,
 };
 use crate::http::pingora::context::PingoraRequestCtx;
 
@@ -164,7 +164,8 @@ impl ProxyHttp for PingoraHttpHandlerNoBody {
         upstream_peer::execute(ctx)
     }
 
-    async fn logging(&self, _session: &mut Session, _e: Option<&pingora_core::Error>, ctx: &mut Self::CTX) {
+    async fn logging(&self, session: &mut Session, _e: Option<&pingora_core::Error>, ctx: &mut Self::CTX) {
+        emit_request_metrics(session, ctx);
         logging_cleanup(&self.pipeline, ctx).await;
     }
 }

protocol/src/http/pingora/handler/no_body.rs

@@ -148,6 +148,7 @@ async fn run_pipeline(
     };
 
     ctx.request_snapshot = Some(request);
+    ctx.metrics_cluster = cluster.clone();
 
     match action {
         Ok(FilterAction::Continue | FilterAction::Release) => {

protocol/src/http/pingora/handler/request_filter/mod.rs

@@ -18,8 +18,8 @@ use tokio::sync::Semaphore;
 use tracing::{debug, warn};
 
 use super::{
-    adjust_compression, handle_connect_failure, logging_cleanup, request_body_filter, request_filter,
-    response_body_filter, response_filter, upstream_peer, upstream_request, via,
+    adjust_compression, emit_request_metrics, handle_connect_failure, logging_cleanup, request_body_filter,
+    request_filter, response_body_filter, response_filter, upstream_peer, upstream_request, via,
 };
 use crate::http::pingora::context::PingoraRequestCtx;
 
@@ -199,7 +199,8 @@ impl ProxyHttp for PingoraHttpHandler {
         upstream_peer::execute(ctx)
     }
 
-    async fn logging(&self, _session: &mut Session, _e: Option<&pingora_core::Error>, ctx: &mut Self::CTX) {
+    async fn logging(&self, session: &mut Session, _e: Option<&pingora_core::Error>, ctx: &mut Self::CTX) {
+        emit_request_metrics(session, ctx);
         logging_cleanup(&self.pipeline, ctx).await;
     }
 }