refactor: centralize Prometheus metrics naming and sanitization DIS-554 (#2733)

Co-authored-by: Keiven Chang <keivenchang@users.noreply.github.com>
Signed-off-by: Jason Zhou <jasonzho@jasonzho-mlt.client.nvidia.com>

Author: keivenchang

Cargo.lock

@@ -43,6 +43,7 @@ def _get_average_metric(
             Average metric value or 0 if no data/error
         """
         try:
+            # TODO: use prometheus_names.rs
             full_metric_name = f"dynamo_frontend_{metric_name}"
             query = f"increase({full_metric_name}_sum[{interval}])/increase({full_metric_name}_count[{interval}])"
             result = self.prom.custom_query(query=query)

components/planner/src/dynamo/planner/utils/prometheus.py

@@ -155,6 +155,7 @@ reqwest = { workspace = true }
 rstest = "0.18.2"
 rstest_reuse = "0.7.0"
 serial_test = "3"
+temp-env = { version = "0.3.6", features = ["async_closure"] }
 tempfile = "3.17.1"
 insta = { version = "1.41", features = [
   "glob",

lib/llm/Cargo.toml

@@ -2,6 +2,9 @@
 // SPDX-License-Identifier: Apache-2.0
 
 use axum::{Router, extract::State, http::StatusCode, response::IntoResponse, routing::get};
+use dynamo_runtime::metrics::prometheus_names::{
+    frontend_service, name_prefix, sanitize_frontend_prometheus_prefix,
+};
 use prometheus::{Encoder, HistogramOpts, HistogramVec, IntCounterVec, IntGaugeVec, Opts};
 use std::{
     sync::Arc,
@@ -12,49 +15,6 @@ pub use prometheus::Registry;
 
 use super::RouteDoc;
 
-// Default metric prefix
-pub const FRONTEND_METRIC_PREFIX: &str = "dynamo_frontend";
-
-// Environment variable that overrides the default metric prefix if provided
-pub const METRICS_PREFIX_ENV: &str = "DYN_METRICS_PREFIX";
-
-/// Value for the `status` label in the request counter for successful requests
-pub const REQUEST_STATUS_SUCCESS: &str = "success";
-
-/// Value for the `status` label in the request counter if the request failed
-pub const REQUEST_STATUS_ERROR: &str = "error";
-
-/// Partial value for the `type` label in the request counter for streaming requests
-pub const REQUEST_TYPE_STREAM: &str = "stream";
-
-/// Partial value for the `type` label in the request counter for unary requests
-pub const REQUEST_TYPE_UNARY: &str = "unary";
-
-fn sanitize_prometheus_prefix(raw: &str) -> String {
-    // Prometheus metric name pattern: [a-zA-Z_:][a-zA-Z0-9_:]*
-    let mut s: String = raw
-        .chars()
-        .map(|c| {
-            if c.is_ascii_alphanumeric() || c == '_' || c == ':' {
-                c
-            } else {
-                '_'
-            }
-        })
-        .collect();
-
-    if s.is_empty() {
-        return FRONTEND_METRIC_PREFIX.to_string();
-    }
-
-    let first = s.as_bytes()[0];
-    let valid_first = first.is_ascii_alphabetic() || first == b'_' || first == b':';
-    if !valid_first {
-        s.insert(0, '_');
-    }
-    s
-}
-
 pub struct Metrics {
     request_counter: IntCounterVec,
     inflight_gauge: IntGaugeVec,
@@ -67,8 +27,8 @@ pub struct Metrics {
 
 /// RAII object for inflight gauge and request counters
 /// If this object is dropped without calling `mark_ok`, then the request will increment
-/// the request counter with the `status` label with [`REQUEST_STATUS_ERROR`]; otherwise, it will increment
-/// the counter with `status` label [`REQUEST_STATUS_SUCCESS`]
+/// the request counter with the `status` label with [`frontend_service::status::ERROR`]; otherwise, it will increment
+/// the counter with `status` label [`frontend_service::status::SUCCESS`]
 pub struct InflightGuard {
     metrics: Arc<Metrics>,
     model: String,
@@ -130,7 +90,7 @@ impl Default for Metrics {
 }
 
 impl Metrics {
-    /// Create Metrics with the standard prefix defined by [`FRONTEND_METRIC_PREFIX`] or specify custom prefix via the following environment variable:
+    /// Create Metrics with the standard prefix defined by [`name_prefix::FRONTEND`] or specify custom prefix via the following environment variable:
     /// - `DYN_METRICS_PREFIX`: Override the default metrics prefix
     ///
     /// The following metrics will be created with the configured prefix:
@@ -142,22 +102,22 @@ impl Metrics {
     /// - `{prefix}_time_to_first_token_seconds` - HistogramVec for time to first token in seconds
     /// - `{prefix}_inter_token_latency_seconds` - HistogramVec for inter-token latency in seconds
     pub fn new() -> Self {
-        let raw_prefix = std::env::var(METRICS_PREFIX_ENV)
-            .unwrap_or_else(|_| FRONTEND_METRIC_PREFIX.to_string());
-        let prefix = sanitize_prometheus_prefix(&raw_prefix);
+        let raw_prefix = std::env::var(frontend_service::METRICS_PREFIX_ENV)
+            .unwrap_or_else(|_| name_prefix::FRONTEND.to_string());
+        let prefix = sanitize_frontend_prometheus_prefix(&raw_prefix);
         if prefix != raw_prefix {
             tracing::warn!(
                 raw=%raw_prefix,
                 sanitized=%prefix,
-                env=%METRICS_PREFIX_ENV,
+                env=%frontend_service::METRICS_PREFIX_ENV,
                 "Sanitized HTTP metrics prefix"
             );
         }
         let frontend_metric_name = |suffix: &str| format!("{}_{}", &prefix, suffix);
 
         let request_counter = IntCounterVec::new(
             Opts::new(
-                frontend_metric_name("requests_total"),
+                frontend_metric_name(frontend_service::REQUESTS_TOTAL),
                 "Total number of LLM requests processed",
             ),
             &["model", "endpoint", "request_type", "status"],
@@ -166,7 +126,7 @@ impl Metrics {
 
         let inflight_gauge = IntGaugeVec::new(
             Opts::new(
-                frontend_metric_name("inflight_requests"),
+                frontend_metric_name(frontend_service::INFLIGHT_REQUESTS),
                 "Number of inflight requests",
             ),
             &["model"],
@@ -177,7 +137,7 @@ impl Metrics {
 
         let request_duration = HistogramVec::new(
             HistogramOpts::new(
-                frontend_metric_name("request_duration_seconds"),
+                frontend_metric_name(frontend_service::REQUEST_DURATION_SECONDS),
                 "Duration of LLM requests",
             )
             .buckets(buckets),
@@ -187,7 +147,7 @@ impl Metrics {
 
         let input_sequence_length = HistogramVec::new(
             HistogramOpts::new(
-                frontend_metric_name("input_sequence_tokens"),
+                frontend_metric_name(frontend_service::INPUT_SEQUENCE_TOKENS),
                 "Input sequence length in tokens",
             )
             .buckets(vec![
@@ -200,7 +160,7 @@ impl Metrics {
 
         let output_sequence_length = HistogramVec::new(
             HistogramOpts::new(
-                frontend_metric_name("output_sequence_tokens"),
+                frontend_metric_name(frontend_service::OUTPUT_SEQUENCE_TOKENS),
                 "Output sequence length in tokens",
             )
             .buckets(vec![
@@ -212,7 +172,7 @@ impl Metrics {
 
         let time_to_first_token = HistogramVec::new(
             HistogramOpts::new(
-                frontend_metric_name("time_to_first_token_seconds"),
+                frontend_metric_name(frontend_service::TIME_TO_FIRST_TOKEN_SECONDS),
                 "Time to first token in seconds",
             )
             .buckets(vec![
@@ -225,7 +185,7 @@ impl Metrics {
 
         let inter_token_latency = HistogramVec::new(
             HistogramOpts::new(
-                frontend_metric_name("inter_token_latency_seconds"),
+                frontend_metric_name(frontend_service::INTER_TOKEN_LATENCY_SECONDS),
                 "Inter-token latency in seconds",
             )
             .buckets(vec![
@@ -422,17 +382,17 @@ impl Endpoint {
 impl RequestType {
     pub fn as_str(&self) -> &'static str {
         match self {
-            RequestType::Unary => REQUEST_TYPE_UNARY,
-            RequestType::Stream => REQUEST_TYPE_STREAM,
+            RequestType::Unary => frontend_service::request_type::UNARY,
+            RequestType::Stream => frontend_service::request_type::STREAM,
         }
     }
 }
 
 impl Status {
     pub fn as_str(&self) -> &'static str {
         match self {
-            Status::Success => REQUEST_STATUS_SUCCESS,
-            Status::Error => REQUEST_STATUS_ERROR,
+            Status::Success => frontend_service::status::SUCCESS,
+            Status::Error => frontend_service::status::ERROR,
         }
     }
 }

lib/llm/src/http/service/metrics.rs

@@ -11,7 +11,7 @@ use dynamo_llm::http::{
     service::{
         Metrics,
         error::HttpError,
-        metrics::{Endpoint, FRONTEND_METRIC_PREFIX, RequestType, Status},
+        metrics::{Endpoint, RequestType, Status},
         service_v2::HttpService,
     },
 };
@@ -24,6 +24,7 @@ use dynamo_llm::protocols::{
         completions::{NvCreateCompletionRequest, NvCreateCompletionResponse},
     },
 };
+use dynamo_runtime::metrics::prometheus_names::{frontend_service, name_prefix};
 use dynamo_runtime::{
     CancellationToken,
     engine::AsyncEngineContext,
@@ -350,7 +351,14 @@ async fn test_http_service() {
     let families = registry.gather();
     let histogram_metric_family = families
         .into_iter()
-        .find(|m| m.get_name() == format!("{}_request_duration_seconds", FRONTEND_METRIC_PREFIX))
+        .find(|m| {
+            m.get_name()
+                == format!(
+                    "{}_{}",
+                    name_prefix::FRONTEND,
+                    frontend_service::REQUEST_DURATION_SECONDS
+                )
+        })
         .expect("Histogram metric not found");
 
     assert_eq!(