dynamo_runtime/config/
environment_names.rs

1// SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
2// SPDX-License-Identifier: Apache-2.0
3
4//! Environment variable name constants for centralized management across the codebase
5//!
6//! This module provides centralized environment variable name constants to ensure
7//! consistency and avoid duplication across the codebase, similar to how
8//! `prometheus_names.rs` manages metric names.
9//!
10//! ## Organization
11//!
12//! Environment variables are organized by functional area:
13//! - **Logging**: Log level, configuration, and OTLP tracing
14//! - **Runtime**: Tokio runtime configuration and system server settings
15//! - **NATS**: NATS client connection and authentication
16//! - **ETCD**: ETCD client connection and authentication
17//! - **KVBM**: Key-Value Block Manager configuration
18//! - **LLM**: Language model inference configuration
19//! - **Model**: Model loading and caching
20//! - **Worker**: Worker lifecycle and shutdown
21//! - **Testing**: Test-specific configuration
22
23/// Logging and tracing environment variables
24pub mod logging {
25    /// Log level (e.g., "debug", "info", "warn", "error")
26    pub const DYN_LOG: &str = "DYN_LOG";
27
28    /// Path to logging configuration file
29    pub const DYN_LOGGING_CONFIG_PATH: &str = "DYN_LOGGING_CONFIG_PATH";
30
31    /// Enable JSONL logging format
32    pub const DYN_LOGGING_JSONL: &str = "DYN_LOGGING_JSONL";
33
34    /// Disable ANSI terminal colors in logs
35    pub const DYN_SDK_DISABLE_ANSI_LOGGING: &str = "DYN_SDK_DISABLE_ANSI_LOGGING";
36
37    /// Use local timezone for logging timestamps (default is UTC)
38    pub const DYN_LOG_USE_LOCAL_TZ: &str = "DYN_LOG_USE_LOCAL_TZ";
39
40    /// OTLP (OpenTelemetry Protocol) tracing configuration
41    pub mod otlp {
42        /// Enable OTLP trace exporting (set to "1" to enable)
43        pub const OTEL_EXPORT_ENABLED: &str = "OTEL_EXPORT_ENABLED";
44
45        /// OTLP exporter endpoint URL
46        /// Spec: https://opentelemetry.io/docs/specs/otel/protocol/exporter/
47        pub const OTEL_EXPORTER_OTLP_TRACES_ENDPOINT: &str = "OTEL_EXPORTER_OTLP_TRACES_ENDPOINT";
48
49        /// Service name for OTLP traces
50        pub const OTEL_SERVICE_NAME: &str = "OTEL_SERVICE_NAME";
51    }
52}
53
54/// Runtime configuration environment variables
55///
56/// These control the Tokio runtime, system health/metrics server, and worker behavior
57pub mod runtime {
58    /// Number of async worker threads for Tokio runtime
59    pub const DYN_RUNTIME_NUM_WORKER_THREADS: &str = "DYN_RUNTIME_NUM_WORKER_THREADS";
60
61    /// Maximum number of blocking threads for Tokio runtime
62    pub const DYN_RUNTIME_MAX_BLOCKING_THREADS: &str = "DYN_RUNTIME_MAX_BLOCKING_THREADS";
63
64    /// System status server configuration
65    pub mod system {
66        /// Enable system status server for health and metrics endpoints
67        /// ⚠️ DEPRECATED: will be removed soon
68        pub const DYN_SYSTEM_ENABLED: &str = "DYN_SYSTEM_ENABLED";
69
70        /// System status server host
71        pub const DYN_SYSTEM_HOST: &str = "DYN_SYSTEM_HOST";
72
73        /// System status server port
74        pub const DYN_SYSTEM_PORT: &str = "DYN_SYSTEM_PORT";
75
76        /// Use endpoint health status for system health
77        /// ⚠️ DEPRECATED: No longer used
78        pub const DYN_SYSTEM_USE_ENDPOINT_HEALTH_STATUS: &str =
79            "DYN_SYSTEM_USE_ENDPOINT_HEALTH_STATUS";
80
81        /// Starting health status for the system
82        pub const DYN_SYSTEM_STARTING_HEALTH_STATUS: &str = "DYN_SYSTEM_STARTING_HEALTH_STATUS";
83
84        /// Health check endpoint path
85        pub const DYN_SYSTEM_HEALTH_PATH: &str = "DYN_SYSTEM_HEALTH_PATH";
86
87        /// Liveness check endpoint path
88        pub const DYN_SYSTEM_LIVE_PATH: &str = "DYN_SYSTEM_LIVE_PATH";
89    }
90
91    /// Compute configuration
92    pub mod compute {
93        /// Prefix for compute-related environment variables
94        pub const PREFIX: &str = "DYN_COMPUTE_";
95    }
96
97    /// Canary deployment configuration
98    pub mod canary {
99        /// Wait time in seconds for canary deployments
100        pub const DYN_CANARY_WAIT_TIME: &str = "DYN_CANARY_WAIT_TIME";
101    }
102}
103
104/// Worker lifecycle environment variables
105pub mod worker {
106    /// Graceful shutdown timeout in seconds
107    pub const DYN_WORKER_GRACEFUL_SHUTDOWN_TIMEOUT: &str = "DYN_WORKER_GRACEFUL_SHUTDOWN_TIMEOUT";
108}
109
110/// NATS transport environment variables
111pub mod nats {
112    /// NATS server address (e.g., "nats://localhost:4222")
113    pub const NATS_SERVER: &str = "NATS_SERVER";
114
115    /// NATS authentication environment variables (checked in priority order)
116    pub mod auth {
117        /// Username for NATS authentication (use with NATS_AUTH_PASSWORD)
118        pub const NATS_AUTH_USERNAME: &str = "NATS_AUTH_USERNAME";
119
120        /// Password for NATS authentication (use with NATS_AUTH_USERNAME)
121        pub const NATS_AUTH_PASSWORD: &str = "NATS_AUTH_PASSWORD";
122
123        /// Token for NATS authentication
124        pub const NATS_AUTH_TOKEN: &str = "NATS_AUTH_TOKEN";
125
126        /// NKey for NATS authentication
127        pub const NATS_AUTH_NKEY: &str = "NATS_AUTH_NKEY";
128
129        /// Path to NATS credentials file
130        pub const NATS_AUTH_CREDENTIALS_FILE: &str = "NATS_AUTH_CREDENTIALS_FILE";
131    }
132
133    /// NATS stream configuration
134    pub mod stream {
135        /// Maximum age for messages in NATS stream (in seconds)
136        pub const DYN_NATS_STREAM_MAX_AGE: &str = "DYN_NATS_STREAM_MAX_AGE";
137    }
138}
139
140/// ETCD transport environment variables
141pub mod etcd {
142    /// ETCD endpoints (comma-separated list of URLs)
143    pub const ETCD_ENDPOINTS: &str = "ETCD_ENDPOINTS";
144
145    /// ETCD authentication environment variables
146    pub mod auth {
147        /// Username for ETCD authentication
148        pub const ETCD_AUTH_USERNAME: &str = "ETCD_AUTH_USERNAME";
149
150        /// Password for ETCD authentication
151        pub const ETCD_AUTH_PASSWORD: &str = "ETCD_AUTH_PASSWORD";
152
153        /// Path to CA certificate for ETCD TLS
154        pub const ETCD_AUTH_CA: &str = "ETCD_AUTH_CA";
155
156        /// Path to client certificate for ETCD TLS
157        pub const ETCD_AUTH_CLIENT_CERT: &str = "ETCD_AUTH_CLIENT_CERT";
158
159        /// Path to client key for ETCD TLS
160        pub const ETCD_AUTH_CLIENT_KEY: &str = "ETCD_AUTH_CLIENT_KEY";
161    }
162}
163
164/// Key-Value Block Manager (KVBM) environment variables
165pub mod kvbm {
166    /// Enable KVBM metrics endpoint
167    pub const DYN_KVBM_METRICS: &str = "DYN_KVBM_METRICS";
168
169    /// KVBM metrics endpoint port
170    pub const DYN_KVBM_METRICS_PORT: &str = "DYN_KVBM_METRICS_PORT";
171
172    /// Enable KVBM recording for debugging
173    pub const ENABLE_KVBM_RECORD: &str = "ENABLE_KVBM_RECORD";
174
175    /// Disable disk offload filter
176    pub const DYN_KVBM_DISABLE_DISK_OFFLOAD_FILTER: &str = "DYN_KVBM_DISABLE_DISK_OFFLOAD_FILTER";
177
178    /// CPU cache configuration
179    pub mod cpu_cache {
180        /// CPU cache size in GB
181        pub const DYN_KVBM_CPU_CACHE_GB: &str = "DYN_KVBM_CPU_CACHE_GB";
182
183        /// CPU cache size in number of blocks (override)
184        pub const DYN_KVBM_CPU_CACHE_OVERRIDE_NUM_BLOCKS: &str =
185            "DYN_KVBM_CPU_CACHE_OVERRIDE_NUM_BLOCKS";
186    }
187
188    /// Disk cache configuration
189    pub mod disk_cache {
190        /// Disk cache size in GB
191        pub const DYN_KVBM_DISK_CACHE_GB: &str = "DYN_KVBM_DISK_CACHE_GB";
192
193        /// Disk cache size in number of blocks (override)
194        pub const DYN_KVBM_DISK_CACHE_OVERRIDE_NUM_BLOCKS: &str =
195            "DYN_KVBM_DISK_CACHE_OVERRIDE_NUM_BLOCKS";
196    }
197
198    /// KVBM leader (distributed mode) configuration
199    pub mod leader {
200        /// Timeout in seconds for KVBM leader and worker initialization
201        pub const DYN_KVBM_LEADER_WORKER_INIT_TIMEOUT_SECS: &str =
202            "DYN_KVBM_LEADER_WORKER_INIT_TIMEOUT_SECS";
203
204        /// ZMQ host for KVBM leader
205        pub const DYN_KVBM_LEADER_ZMQ_HOST: &str = "DYN_KVBM_LEADER_ZMQ_HOST";
206
207        /// ZMQ publish port for KVBM leader
208        pub const DYN_KVBM_LEADER_ZMQ_PUB_PORT: &str = "DYN_KVBM_LEADER_ZMQ_PUB_PORT";
209
210        /// ZMQ acknowledgment port for KVBM leader
211        pub const DYN_KVBM_LEADER_ZMQ_ACK_PORT: &str = "DYN_KVBM_LEADER_ZMQ_ACK_PORT";
212    }
213
214    /// NIXL backend configuration
215    pub mod nixl {
216        /// Prefix for NIXL backend environment variables
217        /// Pattern: DYN_KVBM_NIXL_BACKEND_<backend>=true/false
218        /// Example: DYN_KVBM_NIXL_BACKEND_UCX=true
219        pub const PREFIX: &str = "DYN_KVBM_NIXL_BACKEND_";
220    }
221}
222
223/// LLM (Language Model) inference environment variables
224pub mod llm {
225    /// HTTP body size limit in MB
226    pub const DYN_HTTP_BODY_LIMIT_MB: &str = "DYN_HTTP_BODY_LIMIT_MB";
227
228    pub const DYN_HTTP_GRACEFUL_SHUTDOWN_TIMEOUT_SECS: &str =
229        "DYN_HTTP_GRACEFUL_SHUTDOWN_TIMEOUT_SECS";
230
231    /// Enable LoRA adapter support (set to "true" to enable)
232    pub const DYN_LORA_ENABLED: &str = "DYN_LORA_ENABLED";
233
234    /// LoRA cache directory path
235    pub const DYN_LORA_PATH: &str = "DYN_LORA_PATH";
236
237    /// Metrics configuration
238    pub mod metrics {
239        /// Custom metrics prefix (overrides default "dynamo_frontend")
240        pub const DYN_METRICS_PREFIX: &str = "DYN_METRICS_PREFIX";
241
242        /// Histogram bucket configuration (pattern: <PREFIX>_MIN, <PREFIX>_MAX, <PREFIX>_COUNT)
243        /// Example: DYN_HISTOGRAM_TTFT_MIN, DYN_HISTOGRAM_TTFT_MAX, DYN_HISTOGRAM_TTFT_COUNT
244        pub const HISTOGRAM_PREFIX: &str = "DYN_HISTOGRAM_";
245    }
246}
247
248/// Model loading and caching environment variables
249pub mod model {
250    /// Model Express configuration
251    pub mod model_express {
252        /// Model Express server endpoint URL
253        pub const MODEL_EXPRESS_URL: &str = "MODEL_EXPRESS_URL";
254
255        /// Model Express cache path
256        pub const MODEL_EXPRESS_CACHE_PATH: &str = "MODEL_EXPRESS_CACHE_PATH";
257    }
258
259    /// Hugging Face configuration
260    pub mod huggingface {
261        /// Hugging Face authentication token
262        pub const HF_TOKEN: &str = "HF_TOKEN";
263
264        /// Hugging Face Hub cache directory
265        pub const HF_HUB_CACHE: &str = "HF_HUB_CACHE";
266
267        /// Hugging Face home directory
268        pub const HF_HOME: &str = "HF_HOME";
269    }
270}
271
272/// CUDA and GPU environment variables
273pub mod cuda {
274    /// Path to custom CUDA fatbin file
275    ///
276    /// Note: build.rs files cannot import this constant at build time,
277    /// so they must define local constants with the same value.
278    pub const DYNAMO_FATBIN_PATH: &str = "DYNAMO_FATBIN_PATH";
279}
280
281/// Build-time environment variables
282pub mod build {
283    /// Cargo output directory for build artifacts
284    ///
285    /// Note: This constant cannot be used with the `env!()` macro,
286    /// which requires a string literal at compile time.
287    /// Build scripts (build.rs) also cannot import this constant.
288    pub const OUT_DIR: &str = "OUT_DIR";
289}
290
291/// Testing environment variables
292pub mod testing {
293    /// Enable queued-up request processing in tests
294    pub const DYN_QUEUED_UP_PROCESSING: &str = "DYN_QUEUED_UP_PROCESSING";
295
296    /// Soak test run duration (e.g., "3s", "5m")
297    pub const DYN_SOAK_RUN_DURATION: &str = "DYN_SOAK_RUN_DURATION";
298
299    /// Soak test batch load size
300    pub const DYN_SOAK_BATCH_LOAD: &str = "DYN_SOAK_BATCH_LOAD";
301}
302
303#[cfg(test)]
304mod tests {
305    use super::*;
306
307    #[test]
308    fn test_no_duplicate_env_var_names() {
309        use std::collections::HashSet;
310
311        let mut seen = HashSet::new();
312        let vars = [
313            // Logging
314            logging::DYN_LOG,
315            logging::DYN_LOGGING_CONFIG_PATH,
316            logging::DYN_LOGGING_JSONL,
317            logging::DYN_SDK_DISABLE_ANSI_LOGGING,
318            logging::DYN_LOG_USE_LOCAL_TZ,
319            logging::otlp::OTEL_EXPORT_ENABLED,
320            logging::otlp::OTEL_EXPORTER_OTLP_TRACES_ENDPOINT,
321            logging::otlp::OTEL_SERVICE_NAME,
322            // Runtime
323            runtime::DYN_RUNTIME_NUM_WORKER_THREADS,
324            runtime::DYN_RUNTIME_MAX_BLOCKING_THREADS,
325            runtime::system::DYN_SYSTEM_ENABLED,
326            runtime::system::DYN_SYSTEM_HOST,
327            runtime::system::DYN_SYSTEM_PORT,
328            runtime::system::DYN_SYSTEM_USE_ENDPOINT_HEALTH_STATUS,
329            runtime::system::DYN_SYSTEM_STARTING_HEALTH_STATUS,
330            runtime::system::DYN_SYSTEM_HEALTH_PATH,
331            runtime::system::DYN_SYSTEM_LIVE_PATH,
332            runtime::canary::DYN_CANARY_WAIT_TIME,
333            // Worker
334            worker::DYN_WORKER_GRACEFUL_SHUTDOWN_TIMEOUT,
335            // NATS
336            nats::NATS_SERVER,
337            nats::auth::NATS_AUTH_USERNAME,
338            nats::auth::NATS_AUTH_PASSWORD,
339            nats::auth::NATS_AUTH_TOKEN,
340            nats::auth::NATS_AUTH_NKEY,
341            nats::auth::NATS_AUTH_CREDENTIALS_FILE,
342            nats::stream::DYN_NATS_STREAM_MAX_AGE,
343            // ETCD
344            etcd::ETCD_ENDPOINTS,
345            etcd::auth::ETCD_AUTH_USERNAME,
346            etcd::auth::ETCD_AUTH_PASSWORD,
347            etcd::auth::ETCD_AUTH_CA,
348            etcd::auth::ETCD_AUTH_CLIENT_CERT,
349            etcd::auth::ETCD_AUTH_CLIENT_KEY,
350            // KVBM
351            kvbm::DYN_KVBM_METRICS,
352            kvbm::DYN_KVBM_METRICS_PORT,
353            kvbm::ENABLE_KVBM_RECORD,
354            kvbm::DYN_KVBM_DISABLE_DISK_OFFLOAD_FILTER,
355            kvbm::cpu_cache::DYN_KVBM_CPU_CACHE_GB,
356            kvbm::cpu_cache::DYN_KVBM_CPU_CACHE_OVERRIDE_NUM_BLOCKS,
357            kvbm::disk_cache::DYN_KVBM_DISK_CACHE_GB,
358            kvbm::disk_cache::DYN_KVBM_DISK_CACHE_OVERRIDE_NUM_BLOCKS,
359            kvbm::leader::DYN_KVBM_LEADER_WORKER_INIT_TIMEOUT_SECS,
360            kvbm::leader::DYN_KVBM_LEADER_ZMQ_HOST,
361            kvbm::leader::DYN_KVBM_LEADER_ZMQ_PUB_PORT,
362            kvbm::leader::DYN_KVBM_LEADER_ZMQ_ACK_PORT,
363            // LLM
364            llm::DYN_HTTP_BODY_LIMIT_MB,
365            llm::DYN_LORA_ENABLED,
366            llm::DYN_LORA_PATH,
367            llm::metrics::DYN_METRICS_PREFIX,
368            // Model
369            model::model_express::MODEL_EXPRESS_URL,
370            model::model_express::MODEL_EXPRESS_CACHE_PATH,
371            model::huggingface::HF_TOKEN,
372            model::huggingface::HF_HUB_CACHE,
373            model::huggingface::HF_HOME,
374            // CUDA
375            cuda::DYNAMO_FATBIN_PATH,
376            // Build
377            build::OUT_DIR,
378            // Testing
379            testing::DYN_QUEUED_UP_PROCESSING,
380            testing::DYN_SOAK_RUN_DURATION,
381            testing::DYN_SOAK_BATCH_LOAD,
382        ];
383
384        for var in &vars {
385            if !seen.insert(var) {
386                panic!("Duplicate environment variable name: {}", var);
387            }
388        }
389    }
390
391    #[test]
392    fn test_naming_conventions() {
393        // Dynamo-specific vars should start with DYN_
394        assert!(runtime::DYN_RUNTIME_NUM_WORKER_THREADS.starts_with("DYN_"));
395        assert!(runtime::system::DYN_SYSTEM_ENABLED.starts_with("DYN_"));
396        assert!(kvbm::DYN_KVBM_METRICS.starts_with("DYN_"));
397        assert!(worker::DYN_WORKER_GRACEFUL_SHUTDOWN_TIMEOUT.starts_with("DYN_"));
398
399        // NATS vars should start with NATS_
400        assert!(nats::NATS_SERVER.starts_with("NATS_"));
401        assert!(nats::auth::NATS_AUTH_USERNAME.starts_with("NATS_AUTH_"));
402
403        // ETCD vars should start with ETCD_
404        assert!(etcd::ETCD_ENDPOINTS.starts_with("ETCD_"));
405        assert!(etcd::auth::ETCD_AUTH_USERNAME.starts_with("ETCD_AUTH_"));
406
407        // OpenTelemetry vars should start with OTEL_
408        assert!(logging::otlp::OTEL_EXPORT_ENABLED.starts_with("OTEL_"));
409        assert!(logging::otlp::OTEL_SERVICE_NAME.starts_with("OTEL_"));
410    }
411}
dynamo_runtime/config/environment_names.rs

dynamo_runtime/config/
environment_names.rs
