feat: deprecate DYN_SYSTEM_ENABLED in favor of DYN_SYSTEM_PORT (#4082)

Signed-off-by: Keiven Chang <keivenchang@users.noreply.github.com>
Co-authored-by: Keiven Chang <keivenchang@users.noreply.github.com>

lib/bindings/python/examples/metrics/server_with_loop.py

@@ -12,7 +12,7 @@ This shows an alternative approach where:
 4. The metrics are automatically served via the /metrics endpoint
 
 Usage:
-    DYN_SYSTEM_ENABLED=true DYN_SYSTEM_PORT=8081 ./server_with_loop.py
+    DYN_SYSTEM_PORT=8081 ./server_with_loop.py
 
     # In another terminal, query the metrics:
     curl http://localhost:8081/metrics

lib/runtime/src/config.rs

@@ -14,8 +14,8 @@ use validator::Validate;
 /// Default system host for health and metrics endpoints
 const DEFAULT_SYSTEM_HOST: &str = "0.0.0.0";
 
-/// Default system port for health and metrics endpoints
-const DEFAULT_SYSTEM_PORT: u16 = 9090;
+/// Default system port for health and metrics endpoints (-1 = disabled)
+const DEFAULT_SYSTEM_PORT: i16 = -1;
 
 /// Default health endpoint paths
 const DEFAULT_SYSTEM_HEALTH_PATH: &str = "/health";
@@ -94,14 +94,19 @@ pub struct RuntimeConfig {
     pub system_host: String,
 
     /// System status server port for health and metrics endpoints
-    /// If set to 0, the system will assign a random available port
+    /// Set to -1 to disable the system status server (default)
+    /// Set to a positive port number (e.g. 8081) to enable it
     /// Set this at runtime with environment variable DYN_SYSTEM_PORT
     #[builder(default = "DEFAULT_SYSTEM_PORT")]
     #[builder_field_attr(serde(skip_serializing_if = "Option::is_none"))]
-    pub system_port: u16,
-
-    /// Health and metrics System status server enabled
-    /// Set this at runtime with environment variable DYN_SYSTEM_ENABLED
+    pub system_port: i16,
+
+    /// Health and metrics System status server enabled (DEPRECATED)
+    /// This field is deprecated. Use system_port instead (set to positive value to enable)
+    /// Environment variable DYN_SYSTEM_ENABLED is deprecated
+    #[deprecated(
+        note = "Use system_port instead. Set DYN_SYSTEM_PORT to enable the system metrics server."
+    )]
     #[builder(default = "false")]
     #[builder_field_attr(serde(skip_serializing_if = "Option::is_none"))]
     pub system_enabled: bool,
@@ -181,7 +186,6 @@ impl fmt::Display for RuntimeConfig {
         write!(f, "max_blocking_threads={}, ", self.max_blocking_threads)?;
         write!(f, "system_host={}, ", self.system_host)?;
         write!(f, "system_port={}, ", self.system_port)?;
-        write!(f, "system_enabled={}", self.system_enabled)?;
         write!(
             f,
             "use_endpoint_health_status={:?}",
@@ -304,7 +308,7 @@ impl RuntimeConfig {
     ///
     /// Environment variables are prefixed with `DYN_RUNTIME_` and `DYN_SYSTEM`
     pub fn from_settings() -> Result<RuntimeConfig> {
-        // Check for deprecated environment variable
+        // Check for deprecated environment variables
         if std::env::var("DYN_SYSTEM_USE_ENDPOINT_HEALTH_STATUS").is_ok() {
             tracing::warn!(
                 "DYN_SYSTEM_USE_ENDPOINT_HEALTH_STATUS is deprecated and no longer used. \
@@ -313,15 +317,25 @@ impl RuntimeConfig {
             );
         }
 
+        if std::env::var("DYN_SYSTEM_ENABLED").is_ok() {
+            tracing::warn!(
+                "DYN_SYSTEM_ENABLED is deprecated. \
+                System metrics server is now controlled solely by DYN_SYSTEM_PORT. \
+                Set DYN_SYSTEM_PORT to a positive value to enable the server, or set to -1 to disable (default)."
+            );
+        }
+
         let config: RuntimeConfig = Self::figment().extract()?;
         config.validate()?;
         Ok(config)
     }
 
     /// Check if System server should be enabled
-    /// System server is disabled by default, but can be enabled by setting DYN_SYSTEM_ENABLED to true
+    /// System server is enabled when DYN_SYSTEM_PORT is set to a positive value
+    /// Negative values disable the server
+    /// TODO: Support port = 0 to bind to a random available port
     pub fn system_server_enabled(&self) -> bool {
-        self.system_enabled
+        self.system_port > 0
     }
 
     pub fn single_threaded() -> Self {
@@ -330,6 +344,7 @@ impl RuntimeConfig {
             max_blocking_threads: 1,
             system_host: DEFAULT_SYSTEM_HOST.to_string(),
             system_port: DEFAULT_SYSTEM_PORT,
+            #[allow(deprecated)]
             system_enabled: false,
             starting_health_status: HealthStatus::NotReady,
             use_endpoint_health_status: vec![],
@@ -365,6 +380,7 @@ impl Default for RuntimeConfig {
             max_blocking_threads: num_cores,
             system_host: DEFAULT_SYSTEM_HOST.to_string(),
             system_port: DEFAULT_SYSTEM_PORT,
+            #[allow(deprecated)]
             system_enabled: false,
             starting_health_status: HealthStatus::NotReady,
             use_endpoint_health_status: vec![],
@@ -535,35 +551,29 @@ mod tests {
     }
 
     #[test]
-    fn test_system_server_enabled_by_default() {
-        temp_env::with_vars(vec![("DYN_SYSTEM_ENABLED", None::<&str>)], || {
+    fn test_system_server_disabled_by_default() {
+        temp_env::with_vars(vec![("DYN_SYSTEM_PORT", None::<&str>)], || {
             let config = RuntimeConfig::from_settings().unwrap();
             assert!(!config.system_server_enabled());
+            assert_eq!(config.system_port, -1);
         });
     }
 
     #[test]
-    fn test_system_server_disabled_explicitly() {
-        temp_env::with_vars(vec![("DYN_SYSTEM_ENABLED", Some("false"))], || {
+    fn test_system_server_disabled_with_negative_port() {
+        temp_env::with_vars(vec![("DYN_SYSTEM_PORT", Some("-1"))], || {
             let config = RuntimeConfig::from_settings().unwrap();
             assert!(!config.system_server_enabled());
+            assert_eq!(config.system_port, -1);
         });
     }
 
     #[test]
-    fn test_system_server_enabled_explicitly() {
-        temp_env::with_vars(vec![("DYN_SYSTEM_ENABLED", Some("true"))], || {
+    fn test_system_server_enabled_with_port() {
+        temp_env::with_vars(vec![("DYN_SYSTEM_PORT", Some("9527"))], || {
             let config = RuntimeConfig::from_settings().unwrap();
             assert!(config.system_server_enabled());
-        });
-    }
-
-    #[test]
-    fn test_system_server_enabled_by_port() {
-        temp_env::with_vars(vec![("DYN_SYSTEM_PORT", Some("8080"))], || {
-            let config = RuntimeConfig::from_settings().unwrap();
-            assert!(!config.system_server_enabled());
-            assert_eq!(config.system_port, 8080);
+            assert_eq!(config.system_port, 9527);
         });
     }
 

lib/runtime/src/distributed.rs

@@ -143,7 +143,7 @@ impl DistributedRuntime {
         if let Some(cancel_token) = cancel_token {
             // System server is enabled - start both the state and HTTP server
             let host = config.system_host.clone();
-            let port = config.system_port;
+            let port = config.system_port as u16;
 
             // Start system status server (it creates SystemStatusState internally)
             match crate::system_status_server::spawn_system_status_server(
@@ -379,7 +379,7 @@ mod tests {
     #[tokio::test]
     async fn test_drt_uptime_after_delay_system_enabled() {
         // Test uptime with system status server enabled
-        temp_env::async_with_vars([("DYN_SYSTEM_ENABLED", Some("true"))], async {
+        temp_env::async_with_vars([("DYN_SYSTEM_PORT", Some("8081"))], async {
             // Start a DRT
             let drt = create_test_drt_async().await;
 

lib/runtime/src/system_status_server.rs

@@ -551,8 +551,7 @@ mod integration_tests {
                 // Ensure system status server was spawned by DRT
                 assert!(
                     system_info_opt.is_some(),
-                    "System status server was not spawned by DRT. Expected DRT to spawn server when DYN_SYSTEM_ENABLED=true, but system_status_server_info() returned None. Environment: DYN_SYSTEM_ENABLED={:?}, DYN_SYSTEM_PORT={:?}",
-                    std::env::var("DYN_SYSTEM_ENABLED"),
+                    "System status server was not spawned by DRT. Expected DRT to spawn server when DYN_SYSTEM_PORT is set to a positive value, but system_status_server_info() returned None. Environment: DYN_SYSTEM_PORT={:?}",
                     std::env::var("DYN_SYSTEM_PORT")
                 );
 

tests/fault_tolerance/cancellation/test_sglang.py

@@ -85,7 +85,6 @@ class DynamoWorkerProcess(ManagedProcess):
         # Set debug logging environment
         env = os.environ.copy()
         env["DYN_LOG"] = "debug"
-        env["DYN_SYSTEM_ENABLED"] = "true"
         env["DYN_SYSTEM_USE_ENDPOINT_HEALTH_STATUS"] = '["generate"]'
         env["DYN_SYSTEM_PORT"] = port
 

tests/fault_tolerance/cancellation/test_trtllm.py

@@ -78,7 +78,6 @@ class DynamoWorkerProcess(ManagedProcess):
         # Set debug logging environment
         env = os.environ.copy()
         env["DYN_LOG"] = "debug"
-        env["DYN_SYSTEM_ENABLED"] = "true"
         env["DYN_SYSTEM_USE_ENDPOINT_HEALTH_STATUS"] = '["generate"]'
         env["DYN_SYSTEM_PORT"] = port
 

tests/fault_tolerance/cancellation/test_vllm.py

@@ -60,7 +60,6 @@ class DynamoWorkerProcess(ManagedProcess):
         # Set debug logging environment
         env = os.environ.copy()
         env["DYN_LOG"] = "debug"
-        env["DYN_SYSTEM_ENABLED"] = "true"
         env["DYN_SYSTEM_USE_ENDPOINT_HEALTH_STATUS"] = '["generate"]'
         env["DYN_SYSTEM_PORT"] = port
 

tests/fault_tolerance/cancellation/utils.py

@@ -29,6 +29,8 @@ class DynamoFrontendProcess(ManagedProcess):
         # Set debug logging environment
         env = os.environ.copy()
         env["DYN_LOG"] = "debug"
+        # Unset DYN_SYSTEM_PORT - frontend doesn't use system metrics server
+        env.pop("DYN_SYSTEM_PORT", None)
 
         log_dir = f"{request.node.name}_frontend"
 

tests/fault_tolerance/etcd_ha/utils.py

@@ -28,6 +28,8 @@ class DynamoFrontendProcess(ManagedProcess):
         env = os.environ.copy()
         env["DYN_LOG"] = "debug"
         env["ETCD_ENDPOINTS"] = ",".join(etcd_endpoints)
+        # Unset DYN_SYSTEM_PORT - frontend doesn't use system metrics server
+        env.pop("DYN_SYSTEM_PORT", None)
 
         log_dir = f"{request.node.name}_frontend"
 

tests/fault_tolerance/migration/test_vllm.py

@@ -51,7 +51,6 @@ class DynamoWorkerProcess(ManagedProcess):
         env["VLLM_NIXL_SIDE_CHANNEL_PORT"] = f"560{worker_id[-1]}"
 
         env["DYN_LOG"] = "debug"
-        env["DYN_SYSTEM_ENABLED"] = "true"
         env["DYN_SYSTEM_USE_ENDPOINT_HEALTH_STATUS"] = '["generate"]'
         env["DYN_SYSTEM_PORT"] = f"808{worker_id[-1]}"
 

tests/fault_tolerance/migration/utils.py

@@ -2,6 +2,7 @@
 # SPDX-License-Identifier: Apache-2.0
 
 import logging
+import os
 import shutil
 import threading
 import time
@@ -22,6 +23,10 @@ class DynamoFrontendProcess(ManagedProcess):
     def __init__(self, request):
         command = ["python", "-m", "dynamo.frontend", "--router-mode", "round-robin"]
 
+        # Unset DYN_SYSTEM_PORT - frontend doesn't use system metrics server
+        env = os.environ.copy()
+        env.pop("DYN_SYSTEM_PORT", None)
+
         log_dir = f"{request.node.name}_frontend"
 
         # Clean up any existing log directory from previous runs
@@ -34,6 +39,7 @@ class DynamoFrontendProcess(ManagedProcess):
 
         super().__init__(
             command=command,
+            env=env,
             display_output=True,
             terminate_existing=True,
             log_dir=log_dir,

tests/fault_tolerance/test_vllm_health_check.py

@@ -23,6 +23,10 @@ class DynamoFrontendProcess(ManagedProcess):
     def __init__(self, request):
         command = ["python", "-m", "dynamo.frontend", "--router-mode", "round-robin"]
 
+        # Unset DYN_SYSTEM_PORT - frontend doesn't use system metrics server
+        env = os.environ.copy()
+        env.pop("DYN_SYSTEM_PORT", None)
+
         log_dir = f"{request.node.name}_frontend"
 
         # Clean up any existing log directory from previous runs
@@ -35,6 +39,7 @@ class DynamoFrontendProcess(ManagedProcess):
 
         super().__init__(
             command=command,
+            env=env,
             display_output=True,
             terminate_existing=True,
             log_dir=log_dir,
@@ -67,7 +72,6 @@ class DynamoWorkerProcess(ManagedProcess):
         # Set debug logging environment
         env = os.environ.copy()
         env["DYN_LOG"] = "debug"
-        env["DYN_SYSTEM_ENABLED"] = "true"
         env["DYN_SYSTEM_USE_ENDPOINT_HEALTH_STATUS"] = '["generate"]'
         env["DYN_SYSTEM_PORT"] = "9345"
 

tests/frontend/grpc/test_tensor_mocker_engine.py

@@ -26,6 +26,10 @@ class DynamoFrontendProcess(ManagedProcess):
     def __init__(self, request):
         command = ["python", "-m", "dynamo.frontend", "--kserve-grpc-server"]
 
+        # Unset DYN_SYSTEM_PORT - frontend doesn't use system metrics server
+        env = os.environ.copy()
+        env.pop("DYN_SYSTEM_PORT", None)
+
         log_dir = f"{request.node.name}_frontend"
 
         # Clean up any existing log directory from previous runs
@@ -38,6 +42,7 @@ class DynamoFrontendProcess(ManagedProcess):
 
         super().__init__(
             command=command,
+            env=env,
             display_output=True,
             terminate_existing=True,
             log_dir=log_dir,
@@ -55,7 +60,6 @@ class MockWorkerProcess(ManagedProcess):
 
         env = os.environ.copy()
         env["DYN_LOG"] = "debug"
-        env["DYN_SYSTEM_ENABLED"] = "true"
         env["DYN_SYSTEM_USE_ENDPOINT_HEALTH_STATUS"] = '["generate"]'
         env["DYN_SYSTEM_PORT"] = "8083"
 

tests/frontend/grpc/test_tensor_parameters.py

@@ -22,8 +22,13 @@ class DynamoFrontendProcess(ManagedProcess):
         log_dir = f"{request.node.name}_frontend"
         shutil.rmtree(log_dir, ignore_errors=True)
 
+        # Unset DYN_SYSTEM_PORT - frontend doesn't use system metrics server
+        env = os.environ.copy()
+        env.pop("DYN_SYSTEM_PORT", None)
+
         super().__init__(
             command=command,
+            env=env,
             display_output=True,
             terminate_existing=True,
             log_dir=log_dir,
@@ -39,7 +44,6 @@ class EchoTensorWorkerProcess(ManagedProcess):
 
         env = os.environ.copy()
         env["DYN_LOG"] = "debug"
-        env["DYN_SYSTEM_ENABLED"] = "true"
         env["DYN_SYSTEM_USE_ENDPOINT_HEALTH_STATUS"] = '["generate"]'
         env["DYN_SYSTEM_PORT"] = "8083"
 

tests/frontend/test_completion_mocker_engine.py

@@ -29,6 +29,10 @@ class DynamoFrontendProcess(ManagedProcess):
     def __init__(self, request):
         command = ["python", "-m", "dynamo.frontend", "--router-mode", "round-robin"]
 
+        # Unset DYN_SYSTEM_PORT - frontend doesn't use system metrics server
+        env = os.environ.copy()
+        env.pop("DYN_SYSTEM_PORT", None)
+
         log_dir = f"{request.node.name}_frontend"
 
         # Clean up any existing log directory from previous runs
@@ -41,6 +45,7 @@ class DynamoFrontendProcess(ManagedProcess):
 
         super().__init__(
             command=command,
+            env=env,
             display_output=True,
             terminate_existing=True,
             log_dir=log_dir,
@@ -63,7 +68,6 @@ class MockWorkerProcess(ManagedProcess):
 
         env = os.environ.copy()
         env["DYN_LOG"] = "debug"
-        env["DYN_SYSTEM_ENABLED"] = "true"
         env["DYN_SYSTEM_USE_ENDPOINT_HEALTH_STATUS"] = '["generate"]'
         env["DYN_SYSTEM_PORT"] = "8083"
 

tests/frontend/test_vllm.py

@@ -61,6 +61,10 @@ class DynamoFrontendProcess(ManagedProcess):
     def __init__(self, request):
         command = ["python", "-m", "dynamo.frontend", "--router-mode", "round-robin"]
 
+        # Unset DYN_SYSTEM_PORT - frontend doesn't use system metrics server
+        env = os.environ.copy()
+        env.pop("DYN_SYSTEM_PORT", None)
+
         log_dir = f"{request.node.name}_frontend"
 
         # Clean up any existing log directory from previous runs
@@ -73,6 +77,7 @@ class DynamoFrontendProcess(ManagedProcess):
 
         super().__init__(
             command=command,
+            env=env,
             display_output=True,
             terminate_existing=True,
             log_dir=log_dir,
@@ -101,7 +106,6 @@ class VllmWorkerProcess(ManagedProcess):
 
         env = os.environ.copy()
         env["DYN_LOG"] = "debug"
-        env["DYN_SYSTEM_ENABLED"] = "true"
         env["DYN_SYSTEM_USE_ENDPOINT_HEALTH_STATUS"] = '["generate"]'
         env["DYN_SYSTEM_PORT"] = "8083"
 

tests/kvbm_integration/test_cuda_graph.py

@@ -54,7 +54,6 @@ class DynamoWorkerProcess(ManagedProcess):
         # Set debug logging environment
         env = os.environ.copy()
         env["DYN_LOG"] = "debug"
-        env["DYN_SYSTEM_ENABLED"] = "true"
         env["DYN_SYSTEM_USE_ENDPOINT_HEALTH_STATUS"] = '["generate"]'
         env["DYN_SYSTEM_PORT"] = "9345"
         env["DYN_KVBM_CPU_CACHE_GB"] = "20"

tests/planner/perf_test_configs/agg_8b.yaml

@@ -74,8 +74,6 @@ spec:
           memory: "100Gi"
           gpu: "1"
       envs:
-        - name: DYN_SYSTEM_ENABLED
-          value: "true"
         - name: DYN_SYSTEM_PORT
           value: "9090"
         - name: DYN_SYSTEM_USE_ENDPOINT_HEALTH_STATUS

tests/planner/perf_test_configs/disagg_8b_2p2d.yaml

@@ -74,8 +74,6 @@ spec:
           memory: "100Gi"
           gpu: "1"
       envs:
-        - name: DYN_SYSTEM_ENABLED
-          value: "true"
         - name: DYN_SYSTEM_USE_ENDPOINT_HEALTH_STATUS
           value: "[\"generate\"]"
         - name: DYN_SYSTEM_PORT
@@ -124,8 +122,6 @@ spec:
           memory: "100Gi"
           gpu: "1"
       envs:
-        - name: DYN_SYSTEM_ENABLED
-          value: "true"
         - name: DYN_SYSTEM_USE_ENDPOINT_HEALTH_STATUS
           value: "[\"generate\"]"
         - name: DYN_SYSTEM_PORT

tests/planner/perf_test_configs/disagg_8b_3p1d.yaml

@@ -74,8 +74,6 @@ spec:
           memory: "100Gi"
           gpu: "1"
       envs:
-        - name: DYN_SYSTEM_ENABLED
-          value: "true"
         - name: DYN_SYSTEM_USE_ENDPOINT_HEALTH_STATUS
           value: "[\"generate\"]"
         - name: DYN_SYSTEM_PORT
@@ -124,8 +122,6 @@ spec:
           memory: "100Gi"
           gpu: "1"
       envs:
-        - name: DYN_SYSTEM_ENABLED
-          value: "true"
         - name: DYN_SYSTEM_USE_ENDPOINT_HEALTH_STATUS
           value: "[\"generate\"]"
         - name: DYN_SYSTEM_PORT