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//! - **Event Plane**: Event transport selection (NATS)
18//! - **KVBM**: Key-Value Block Manager configuration
19//! - **LLM**: Language model inference configuration
20//! - **Model**: Model loading and caching
21//! - **Worker**: Worker lifecycle and shutdown
22//! - **Testing**: Test-specific configuration
23
24/// Logging and tracing environment variables
25pub mod logging {
26    /// Log level (e.g., "debug", "info", "warn", "error")
27    pub const DYN_LOG: &str = "DYN_LOG";
28
29    /// Path to logging configuration file
30    pub const DYN_LOGGING_CONFIG_PATH: &str = "DYN_LOGGING_CONFIG_PATH";
31
32    /// Enable JSONL logging format
33    pub const DYN_LOGGING_JSONL: &str = "DYN_LOGGING_JSONL";
34
35    /// Disable ANSI terminal colors in logs
36    pub const DYN_SDK_DISABLE_ANSI_LOGGING: &str = "DYN_SDK_DISABLE_ANSI_LOGGING";
37
38    /// Use local timezone for logging timestamps (default is UTC)
39    pub const DYN_LOG_USE_LOCAL_TZ: &str = "DYN_LOG_USE_LOCAL_TZ";
40
41    /// Enable span event logging (create/close events)
42    pub const DYN_LOGGING_SPAN_EVENTS: &str = "DYN_LOGGING_SPAN_EVENTS";
43
44    /// OTLP (OpenTelemetry Protocol) tracing configuration
45    pub mod otlp {
46        /// Enable OTLP trace exporting (set to "1" to enable)
47        pub const OTEL_EXPORT_ENABLED: &str = "OTEL_EXPORT_ENABLED";
48
49        /// OTLP exporter endpoint URL
50        /// Spec: https://opentelemetry.io/docs/specs/otel/protocol/exporter/
51        pub const OTEL_EXPORTER_OTLP_TRACES_ENDPOINT: &str = "OTEL_EXPORTER_OTLP_TRACES_ENDPOINT";
52
53        /// Service name for OTLP traces
54        pub const OTEL_SERVICE_NAME: &str = "OTEL_SERVICE_NAME";
55    }
56}
57
58/// Runtime configuration environment variables
59///
60/// These control the Tokio runtime, system health/metrics server, and worker behavior
61pub mod runtime {
62    /// Number of async worker threads for Tokio runtime
63    pub const DYN_RUNTIME_NUM_WORKER_THREADS: &str = "DYN_RUNTIME_NUM_WORKER_THREADS";
64
65    /// Maximum number of blocking threads for Tokio runtime
66    pub const DYN_RUNTIME_MAX_BLOCKING_THREADS: &str = "DYN_RUNTIME_MAX_BLOCKING_THREADS";
67
68    /// System status server configuration
69    pub mod system {
70        /// Enable system status server for health and metrics endpoints
71        /// ⚠️ DEPRECATED: will be removed soon
72        pub const DYN_SYSTEM_ENABLED: &str = "DYN_SYSTEM_ENABLED";
73
74        /// System status server host
75        pub const DYN_SYSTEM_HOST: &str = "DYN_SYSTEM_HOST";
76
77        /// System status server port
78        pub const DYN_SYSTEM_PORT: &str = "DYN_SYSTEM_PORT";
79
80        /// Use endpoint health status for system health
81        /// ⚠️ DEPRECATED: No longer used
82        pub const DYN_SYSTEM_USE_ENDPOINT_HEALTH_STATUS: &str =
83            "DYN_SYSTEM_USE_ENDPOINT_HEALTH_STATUS";
84
85        /// Starting health status for the system
86        pub const DYN_SYSTEM_STARTING_HEALTH_STATUS: &str = "DYN_SYSTEM_STARTING_HEALTH_STATUS";
87
88        /// Health check endpoint path
89        pub const DYN_SYSTEM_HEALTH_PATH: &str = "DYN_SYSTEM_HEALTH_PATH";
90
91        /// Liveness check endpoint path
92        pub const DYN_SYSTEM_LIVE_PATH: &str = "DYN_SYSTEM_LIVE_PATH";
93    }
94
95    /// Compute configuration
96    pub mod compute {
97        /// Prefix for compute-related environment variables
98        pub const PREFIX: &str = "DYN_COMPUTE_";
99    }
100
101    /// Canary deployment configuration
102    pub mod canary {
103        /// Wait time in seconds for canary deployments
104        pub const DYN_CANARY_WAIT_TIME: &str = "DYN_CANARY_WAIT_TIME";
105    }
106}
107
108/// Worker lifecycle environment variables
109pub mod worker {
110    /// Graceful shutdown timeout in seconds
111    pub const DYN_WORKER_GRACEFUL_SHUTDOWN_TIMEOUT: &str = "DYN_WORKER_GRACEFUL_SHUTDOWN_TIMEOUT";
112}
113
114/// NATS transport environment variables
115pub mod nats {
116    /// NATS server address (e.g., "nats://localhost:4222")
117    pub const NATS_SERVER: &str = "NATS_SERVER";
118
119    /// NATS authentication environment variables (checked in priority order)
120    pub mod auth {
121        /// Username for NATS authentication (use with NATS_AUTH_PASSWORD)
122        pub const NATS_AUTH_USERNAME: &str = "NATS_AUTH_USERNAME";
123
124        /// Password for NATS authentication (use with NATS_AUTH_USERNAME)
125        pub const NATS_AUTH_PASSWORD: &str = "NATS_AUTH_PASSWORD";
126
127        /// Token for NATS authentication
128        pub const NATS_AUTH_TOKEN: &str = "NATS_AUTH_TOKEN";
129
130        /// NKey for NATS authentication
131        pub const NATS_AUTH_NKEY: &str = "NATS_AUTH_NKEY";
132
133        /// Path to NATS credentials file
134        pub const NATS_AUTH_CREDENTIALS_FILE: &str = "NATS_AUTH_CREDENTIALS_FILE";
135    }
136
137    /// NATS stream configuration
138    pub mod stream {
139        /// Maximum age for messages in NATS stream (in seconds)
140        pub const DYN_NATS_STREAM_MAX_AGE: &str = "DYN_NATS_STREAM_MAX_AGE";
141    }
142}
143
144/// ETCD transport environment variables
145pub mod etcd {
146    /// ETCD endpoints (comma-separated list of URLs)
147    pub const ETCD_ENDPOINTS: &str = "ETCD_ENDPOINTS";
148
149    /// ETCD authentication environment variables
150    pub mod auth {
151        /// Username for ETCD authentication
152        pub const ETCD_AUTH_USERNAME: &str = "ETCD_AUTH_USERNAME";
153
154        /// Password for ETCD authentication
155        pub const ETCD_AUTH_PASSWORD: &str = "ETCD_AUTH_PASSWORD";
156
157        /// Path to CA certificate for ETCD TLS
158        pub const ETCD_AUTH_CA: &str = "ETCD_AUTH_CA";
159
160        /// Path to client certificate for ETCD TLS
161        pub const ETCD_AUTH_CLIENT_CERT: &str = "ETCD_AUTH_CLIENT_CERT";
162
163        /// Path to client key for ETCD TLS
164        pub const ETCD_AUTH_CLIENT_KEY: &str = "ETCD_AUTH_CLIENT_KEY";
165    }
166}
167
168/// Key-Value Block Manager (KVBM) environment variables
169pub mod kvbm {
170    /// Enable KVBM metrics endpoint
171    pub const DYN_KVBM_METRICS: &str = "DYN_KVBM_METRICS";
172
173    /// KVBM metrics endpoint port
174    pub const DYN_KVBM_METRICS_PORT: &str = "DYN_KVBM_METRICS_PORT";
175
176    /// Enable KVBM recording for debugging
177    pub const ENABLE_KVBM_RECORD: &str = "ENABLE_KVBM_RECORD";
178
179    /// Disable disk offload filter
180    pub const DYN_KVBM_DISABLE_DISK_OFFLOAD_FILTER: &str = "DYN_KVBM_DISABLE_DISK_OFFLOAD_FILTER";
181
182    /// CPU cache configuration
183    pub mod cpu_cache {
184        /// CPU cache size in GB
185        pub const DYN_KVBM_CPU_CACHE_GB: &str = "DYN_KVBM_CPU_CACHE_GB";
186
187        /// CPU cache size in number of blocks (override)
188        pub const DYN_KVBM_CPU_CACHE_OVERRIDE_NUM_BLOCKS: &str =
189            "DYN_KVBM_CPU_CACHE_OVERRIDE_NUM_BLOCKS";
190    }
191
192    /// Disk cache configuration
193    pub mod disk_cache {
194        /// Disk cache size in GB
195        pub const DYN_KVBM_DISK_CACHE_GB: &str = "DYN_KVBM_DISK_CACHE_GB";
196
197        /// Disk cache size in number of blocks (override)
198        pub const DYN_KVBM_DISK_CACHE_OVERRIDE_NUM_BLOCKS: &str =
199            "DYN_KVBM_DISK_CACHE_OVERRIDE_NUM_BLOCKS";
200    }
201
202    /// Object storage configuration
203    pub mod object_storage {
204        /// Enable object storage. Set to "1" to enable.
205        pub const DYN_KVBM_OBJECT_ENABLED: &str = "DYN_KVBM_OBJECT_ENABLED";
206
207        /// Bucket name for object storage cache
208        /// Supports `{worker_id}` template for per-worker buckets
209        /// Example: "kv-cache-{worker_id}"
210        pub const DYN_KVBM_OBJECT_BUCKET: &str = "DYN_KVBM_OBJECT_BUCKET";
211
212        /// Endpoint for object storage
213        pub const DYN_KVBM_OBJECT_ENDPOINT: &str = "DYN_KVBM_OBJECT_ENDPOINT";
214
215        /// Region for object storage
216        pub const DYN_KVBM_OBJECT_REGION: &str = "DYN_KVBM_OBJECT_REGION";
217
218        /// Access key for authentication
219        pub const DYN_KVBM_OBJECT_ACCESS_KEY: &str = "DYN_KVBM_OBJECT_ACCESS_KEY";
220
221        /// Secret key for authentication
222        pub const DYN_KVBM_OBJECT_SECRET_KEY: &str = "DYN_KVBM_OBJECT_SECRET_KEY";
223
224        /// Number of blocks to store in object storage
225        pub const DYN_KVBM_OBJECT_NUM_BLOCKS: &str = "DYN_KVBM_OBJECT_NUM_BLOCKS";
226    }
227    /// Transfer configuration
228    pub mod transfer {
229        /// Maximum number of blocks per transfer batch
230        pub const DYN_KVBM_TRANSFER_BATCH_SIZE: &str = "DYN_KVBM_TRANSFER_BATCH_SIZE";
231    }
232
233    /// KVBM leader (distributed mode) configuration
234    pub mod leader {
235        /// Timeout in seconds for KVBM leader and worker initialization
236        pub const DYN_KVBM_LEADER_WORKER_INIT_TIMEOUT_SECS: &str =
237            "DYN_KVBM_LEADER_WORKER_INIT_TIMEOUT_SECS";
238
239        /// ZMQ host for KVBM leader
240        pub const DYN_KVBM_LEADER_ZMQ_HOST: &str = "DYN_KVBM_LEADER_ZMQ_HOST";
241
242        /// ZMQ publish port for KVBM leader
243        pub const DYN_KVBM_LEADER_ZMQ_PUB_PORT: &str = "DYN_KVBM_LEADER_ZMQ_PUB_PORT";
244
245        /// ZMQ acknowledgment port for KVBM leader
246        pub const DYN_KVBM_LEADER_ZMQ_ACK_PORT: &str = "DYN_KVBM_LEADER_ZMQ_ACK_PORT";
247    }
248
249    /// NIXL backend configuration
250    pub mod nixl {
251        /// Prefix for NIXL backend environment variables
252        /// Pattern: DYN_KVBM_NIXL_BACKEND_<backend>=true/false
253        /// Example: DYN_KVBM_NIXL_BACKEND_UCX=true
254        pub const PREFIX: &str = "DYN_KVBM_NIXL_BACKEND_";
255    }
256}
257
258/// LLM (Language Model) inference environment variables
259pub mod llm {
260    /// HTTP body size limit in MB
261    pub const DYN_HTTP_BODY_LIMIT_MB: &str = "DYN_HTTP_BODY_LIMIT_MB";
262
263    pub const DYN_HTTP_GRACEFUL_SHUTDOWN_TIMEOUT_SECS: &str =
264        "DYN_HTTP_GRACEFUL_SHUTDOWN_TIMEOUT_SECS";
265
266    /// Enable LoRA adapter support (set to "true" to enable)
267    pub const DYN_LORA_ENABLED: &str = "DYN_LORA_ENABLED";
268
269    /// LoRA cache directory path
270    pub const DYN_LORA_PATH: &str = "DYN_LORA_PATH";
271
272    /// Metrics configuration
273    pub mod metrics {
274        /// Custom metrics prefix (overrides default "dynamo_frontend")
275        pub const DYN_METRICS_PREFIX: &str = "DYN_METRICS_PREFIX";
276
277        /// Histogram bucket configuration (pattern: <PREFIX>_MIN, <PREFIX>_MAX, <PREFIX>_COUNT)
278        /// Example: DYN_HISTOGRAM_TTFT_MIN, DYN_HISTOGRAM_TTFT_MAX, DYN_HISTOGRAM_TTFT_COUNT
279        pub const HISTOGRAM_PREFIX: &str = "DYN_HISTOGRAM_";
280    }
281}
282
283/// Model loading and caching environment variables
284pub mod model {
285    /// Model Express configuration
286    pub mod model_express {
287        /// Model Express server endpoint URL
288        pub const MODEL_EXPRESS_URL: &str = "MODEL_EXPRESS_URL";
289
290        /// Model Express cache path
291        pub const MODEL_EXPRESS_CACHE_PATH: &str = "MODEL_EXPRESS_CACHE_PATH";
292    }
293
294    /// Hugging Face configuration
295    pub mod huggingface {
296        /// Hugging Face authentication token
297        pub const HF_TOKEN: &str = "HF_TOKEN";
298
299        /// Hugging Face Hub cache directory
300        pub const HF_HUB_CACHE: &str = "HF_HUB_CACHE";
301
302        /// Hugging Face home directory
303        pub const HF_HOME: &str = "HF_HOME";
304    }
305}
306
307/// Event Plane transport environment variables
308pub mod event_plane {
309    /// Event transport selection: "zmq" or "nats". Default: "nats"
310    pub const DYN_EVENT_PLANE: &str = "DYN_EVENT_PLANE";
311
312    /// Event plane codec selection: "json" or "msgpack".
313    pub const DYN_EVENT_PLANE_CODEC: &str = "DYN_EVENT_PLANE_CODEC";
314}
315
316/// ZMQ Broker environment variables
317pub mod zmq_broker {
318    /// Explicit ZMQ broker URL (takes precedence over discovery)
319    /// Format: "xsub=<url1>[;<url2>...] , xpub=<url1>[;<url2>...]"
320    /// Example: "xsub=tcp://broker:5555 , xpub=tcp://broker:5556"
321    pub const DYN_ZMQ_BROKER_URL: &str = "DYN_ZMQ_BROKER_URL";
322
323    /// Enable ZMQ broker discovery mode
324    pub const DYN_ZMQ_BROKER_ENABLED: &str = "DYN_ZMQ_BROKER_ENABLED";
325
326    /// XSUB bind address (broker binary only)
327    pub const ZMQ_BROKER_XSUB_BIND: &str = "ZMQ_BROKER_XSUB_BIND";
328
329    /// XPUB bind address (broker binary only)
330    pub const ZMQ_BROKER_XPUB_BIND: &str = "ZMQ_BROKER_XPUB_BIND";
331
332    /// Namespace for broker discovery registration
333    pub const ZMQ_BROKER_NAMESPACE: &str = "ZMQ_BROKER_NAMESPACE";
334}
335
336/// CUDA and GPU environment variables
337pub mod cuda {
338    /// Path to custom CUDA fatbin file
339    ///
340    /// Note: build.rs files cannot import this constant at build time,
341    /// so they must define local constants with the same value.
342    pub const DYNAMO_FATBIN_PATH: &str = "DYNAMO_FATBIN_PATH";
343}
344
345/// Build-time environment variables
346pub mod build {
347    /// Cargo output directory for build artifacts
348    ///
349    /// Note: This constant cannot be used with the `env!()` macro,
350    /// which requires a string literal at compile time.
351    /// Build scripts (build.rs) also cannot import this constant.
352    pub const OUT_DIR: &str = "OUT_DIR";
353}
354
355/// Testing environment variables
356pub mod testing {
357    /// Enable queued-up request processing in tests
358    pub const DYN_QUEUED_UP_PROCESSING: &str = "DYN_QUEUED_UP_PROCESSING";
359
360    /// Soak test run duration (e.g., "3s", "5m")
361    pub const DYN_SOAK_RUN_DURATION: &str = "DYN_SOAK_RUN_DURATION";
362
363    /// Soak test batch load size
364    pub const DYN_SOAK_BATCH_LOAD: &str = "DYN_SOAK_BATCH_LOAD";
365}
366
367#[cfg(test)]
368mod tests {
369    use super::*;
370
371    #[test]
372    fn test_no_duplicate_env_var_names() {
373        use std::collections::HashSet;
374
375        let mut seen = HashSet::new();
376        let vars = [
377            // Logging
378            logging::DYN_LOG,
379            logging::DYN_LOGGING_CONFIG_PATH,
380            logging::DYN_LOGGING_JSONL,
381            logging::DYN_SDK_DISABLE_ANSI_LOGGING,
382            logging::DYN_LOG_USE_LOCAL_TZ,
383            logging::DYN_LOGGING_SPAN_EVENTS,
384            logging::otlp::OTEL_EXPORT_ENABLED,
385            logging::otlp::OTEL_EXPORTER_OTLP_TRACES_ENDPOINT,
386            logging::otlp::OTEL_SERVICE_NAME,
387            // Runtime
388            runtime::DYN_RUNTIME_NUM_WORKER_THREADS,
389            runtime::DYN_RUNTIME_MAX_BLOCKING_THREADS,
390            runtime::system::DYN_SYSTEM_ENABLED,
391            runtime::system::DYN_SYSTEM_HOST,
392            runtime::system::DYN_SYSTEM_PORT,
393            runtime::system::DYN_SYSTEM_USE_ENDPOINT_HEALTH_STATUS,
394            runtime::system::DYN_SYSTEM_STARTING_HEALTH_STATUS,
395            runtime::system::DYN_SYSTEM_HEALTH_PATH,
396            runtime::system::DYN_SYSTEM_LIVE_PATH,
397            runtime::canary::DYN_CANARY_WAIT_TIME,
398            // Worker
399            worker::DYN_WORKER_GRACEFUL_SHUTDOWN_TIMEOUT,
400            // NATS
401            nats::NATS_SERVER,
402            nats::auth::NATS_AUTH_USERNAME,
403            nats::auth::NATS_AUTH_PASSWORD,
404            nats::auth::NATS_AUTH_TOKEN,
405            nats::auth::NATS_AUTH_NKEY,
406            nats::auth::NATS_AUTH_CREDENTIALS_FILE,
407            nats::stream::DYN_NATS_STREAM_MAX_AGE,
408            // ETCD
409            etcd::ETCD_ENDPOINTS,
410            etcd::auth::ETCD_AUTH_USERNAME,
411            etcd::auth::ETCD_AUTH_PASSWORD,
412            etcd::auth::ETCD_AUTH_CA,
413            etcd::auth::ETCD_AUTH_CLIENT_CERT,
414            etcd::auth::ETCD_AUTH_CLIENT_KEY,
415            // KVBM
416            kvbm::DYN_KVBM_METRICS,
417            kvbm::DYN_KVBM_METRICS_PORT,
418            kvbm::ENABLE_KVBM_RECORD,
419            kvbm::DYN_KVBM_DISABLE_DISK_OFFLOAD_FILTER,
420            kvbm::cpu_cache::DYN_KVBM_CPU_CACHE_GB,
421            kvbm::cpu_cache::DYN_KVBM_CPU_CACHE_OVERRIDE_NUM_BLOCKS,
422            kvbm::disk_cache::DYN_KVBM_DISK_CACHE_GB,
423            kvbm::disk_cache::DYN_KVBM_DISK_CACHE_OVERRIDE_NUM_BLOCKS,
424            kvbm::leader::DYN_KVBM_LEADER_WORKER_INIT_TIMEOUT_SECS,
425            kvbm::leader::DYN_KVBM_LEADER_ZMQ_HOST,
426            kvbm::leader::DYN_KVBM_LEADER_ZMQ_PUB_PORT,
427            kvbm::leader::DYN_KVBM_LEADER_ZMQ_ACK_PORT,
428            // LLM
429            llm::DYN_HTTP_BODY_LIMIT_MB,
430            llm::DYN_LORA_ENABLED,
431            llm::DYN_LORA_PATH,
432            llm::metrics::DYN_METRICS_PREFIX,
433            // Model
434            model::model_express::MODEL_EXPRESS_URL,
435            model::model_express::MODEL_EXPRESS_CACHE_PATH,
436            model::huggingface::HF_TOKEN,
437            model::huggingface::HF_HUB_CACHE,
438            model::huggingface::HF_HOME,
439            // Event Plane
440            event_plane::DYN_EVENT_PLANE,
441            event_plane::DYN_EVENT_PLANE_CODEC,
442            // ZMQ Broker
443            zmq_broker::DYN_ZMQ_BROKER_URL,
444            zmq_broker::DYN_ZMQ_BROKER_ENABLED,
445            zmq_broker::ZMQ_BROKER_XSUB_BIND,
446            zmq_broker::ZMQ_BROKER_XPUB_BIND,
447            zmq_broker::ZMQ_BROKER_NAMESPACE,
448            // CUDA
449            cuda::DYNAMO_FATBIN_PATH,
450            // Build
451            build::OUT_DIR,
452            // Testing
453            testing::DYN_QUEUED_UP_PROCESSING,
454            testing::DYN_SOAK_RUN_DURATION,
455            testing::DYN_SOAK_BATCH_LOAD,
456        ];
457
458        for var in &vars {
459            if !seen.insert(var) {
460                panic!("Duplicate environment variable name: {}", var);
461            }
462        }
463    }
464
465    #[test]
466    fn test_naming_conventions() {
467        // Dynamo-specific vars should start with DYN_
468        assert!(runtime::DYN_RUNTIME_NUM_WORKER_THREADS.starts_with("DYN_"));
469        assert!(runtime::system::DYN_SYSTEM_ENABLED.starts_with("DYN_"));
470        assert!(kvbm::DYN_KVBM_METRICS.starts_with("DYN_"));
471        assert!(worker::DYN_WORKER_GRACEFUL_SHUTDOWN_TIMEOUT.starts_with("DYN_"));
472
473        // NATS vars should start with NATS_
474        assert!(nats::NATS_SERVER.starts_with("NATS_"));
475        assert!(nats::auth::NATS_AUTH_USERNAME.starts_with("NATS_AUTH_"));
476
477        // ETCD vars should start with ETCD_
478        assert!(etcd::ETCD_ENDPOINTS.starts_with("ETCD_"));
479        assert!(etcd::auth::ETCD_AUTH_USERNAME.starts_with("ETCD_AUTH_"));
480
481        // OpenTelemetry vars should start with OTEL_
482        assert!(logging::otlp::OTEL_EXPORT_ENABLED.starts_with("OTEL_"));
483        assert!(logging::otlp::OTEL_SERVICE_NAME.starts_with("OTEL_"));
484    }
485}
dynamo_runtime/config/environment_names.rs

dynamo_runtime/config/
environment_names.rs
