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//! - **TCP Response Stream**: TCP response stream server (CallHome) port and host
18//! - **Event Plane**: Event transport selection (NATS)
19//! - **KVBM**: Key-Value Block Manager configuration
20//! - **LLM**: Language model inference configuration
21//! - **Model**: Model loading and caching
22//! - **Worker**: Worker lifecycle and shutdown
23//! - **Testing**: Test-specific configuration
24//! - **Mocker**: Mocker (mock scheduler/KV manager) configuration
25
26/// Logging and tracing environment variables
27pub mod logging {
28 /// Log level (e.g., "debug", "info", "warn", "error")
29 pub const DYN_LOG: &str = "DYN_LOG";
30
31 /// Path to logging configuration file
32 pub const DYN_LOGGING_CONFIG_PATH: &str = "DYN_LOGGING_CONFIG_PATH";
33
34 /// Enable JSONL logging format
35 pub const DYN_LOGGING_JSONL: &str = "DYN_LOGGING_JSONL";
36
37 /// Disable ANSI terminal colors in logs
38 pub const DYN_SDK_DISABLE_ANSI_LOGGING: &str = "DYN_SDK_DISABLE_ANSI_LOGGING";
39
40 /// Use local timezone for logging timestamps (default is UTC)
41 pub const DYN_LOG_USE_LOCAL_TZ: &str = "DYN_LOG_USE_LOCAL_TZ";
42
43 /// Enable span event logging (create/close events)
44 pub const DYN_LOGGING_SPAN_EVENTS: &str = "DYN_LOGGING_SPAN_EVENTS";
45
46 /// OTLP (OpenTelemetry Protocol) tracing and logging configuration
47 pub mod otlp {
48 /// Enable OTLP export for traces and logs (set to "1" to enable)
49 pub const OTEL_EXPORT_ENABLED: &str = "OTEL_EXPORT_ENABLED";
50
51 /// OTLP exporter endpoint URL for traces
52 /// Spec: https://opentelemetry.io/docs/specs/otel/protocol/exporter/
53 pub const OTEL_EXPORTER_OTLP_TRACES_ENDPOINT: &str = "OTEL_EXPORTER_OTLP_TRACES_ENDPOINT";
54
55 /// OTLP exporter endpoint URL for logs (defaults to traces endpoint if unset)
56 pub const OTEL_EXPORTER_OTLP_LOGS_ENDPOINT: &str = "OTEL_EXPORTER_OTLP_LOGS_ENDPOINT";
57
58 /// Service name for OTLP traces and logs
59 pub const OTEL_SERVICE_NAME: &str = "OTEL_SERVICE_NAME";
60 }
61}
62
63/// Runtime configuration environment variables
64///
65/// These control the Tokio runtime, system health/metrics server, and worker behavior
66pub mod runtime {
67 /// Number of async worker threads for Tokio runtime
68 pub const DYN_RUNTIME_NUM_WORKER_THREADS: &str = "DYN_RUNTIME_NUM_WORKER_THREADS";
69
70 /// Maximum number of blocking threads for Tokio runtime
71 pub const DYN_RUNTIME_MAX_BLOCKING_THREADS: &str = "DYN_RUNTIME_MAX_BLOCKING_THREADS";
72
73 /// Enable Tokio task poll-time histogram (calls enable_metrics_poll_time_histogram on builder).
74 /// Set to "1", "true", or "yes" to enable. Adds ~2× overhead of Instant::now() per task poll.
75 pub const DYN_ENABLE_POLL_HISTOGRAM: &str = "DYN_ENABLE_POLL_HISTOGRAM";
76
77 /// System status server configuration
78 pub mod system {
79 /// Enable system status server for health and metrics endpoints
80 /// ⚠️ DEPRECATED: will be removed soon
81 pub const DYN_SYSTEM_ENABLED: &str = "DYN_SYSTEM_ENABLED";
82
83 /// System status server host
84 pub const DYN_SYSTEM_HOST: &str = "DYN_SYSTEM_HOST";
85
86 /// System status server port
87 pub const DYN_SYSTEM_PORT: &str = "DYN_SYSTEM_PORT";
88
89 /// Use endpoint health status for system health
90 /// ⚠️ DEPRECATED: No longer used
91 pub const DYN_SYSTEM_USE_ENDPOINT_HEALTH_STATUS: &str =
92 "DYN_SYSTEM_USE_ENDPOINT_HEALTH_STATUS";
93
94 /// Starting health status for the system
95 pub const DYN_SYSTEM_STARTING_HEALTH_STATUS: &str = "DYN_SYSTEM_STARTING_HEALTH_STATUS";
96
97 /// Health check endpoint path
98 pub const DYN_SYSTEM_HEALTH_PATH: &str = "DYN_SYSTEM_HEALTH_PATH";
99
100 /// Liveness check endpoint path
101 pub const DYN_SYSTEM_LIVE_PATH: &str = "DYN_SYSTEM_LIVE_PATH";
102 }
103
104 /// Compute configuration
105 pub mod compute {
106 /// Prefix for compute-related environment variables
107 pub const PREFIX: &str = "DYN_COMPUTE_";
108 }
109
110 /// Canary deployment configuration
111 pub mod canary {
112 /// Wait time in seconds for canary deployments
113 pub const DYN_CANARY_WAIT_TIME: &str = "DYN_CANARY_WAIT_TIME";
114 }
115}
116
117/// Worker lifecycle environment variables
118pub mod worker {
119 /// Graceful shutdown timeout in seconds
120 pub const DYN_WORKER_GRACEFUL_SHUTDOWN_TIMEOUT: &str = "DYN_WORKER_GRACEFUL_SHUTDOWN_TIMEOUT";
121}
122
123/// NATS transport environment variables
124pub mod nats {
125 /// NATS server address (e.g., "nats://localhost:4222")
126 pub const NATS_SERVER: &str = "NATS_SERVER";
127
128 /// NATS authentication environment variables (checked in priority order)
129 pub mod auth {
130 /// Username for NATS authentication (use with NATS_AUTH_PASSWORD)
131 pub const NATS_AUTH_USERNAME: &str = "NATS_AUTH_USERNAME";
132
133 /// Password for NATS authentication (use with NATS_AUTH_USERNAME)
134 pub const NATS_AUTH_PASSWORD: &str = "NATS_AUTH_PASSWORD";
135
136 /// Token for NATS authentication
137 pub const NATS_AUTH_TOKEN: &str = "NATS_AUTH_TOKEN";
138
139 /// NKey for NATS authentication
140 pub const NATS_AUTH_NKEY: &str = "NATS_AUTH_NKEY";
141
142 /// Path to NATS credentials file
143 pub const NATS_AUTH_CREDENTIALS_FILE: &str = "NATS_AUTH_CREDENTIALS_FILE";
144 }
145
146 /// NATS stream configuration
147 pub mod stream {
148 /// Maximum age for messages in NATS stream (in seconds)
149 pub const DYN_NATS_STREAM_MAX_AGE: &str = "DYN_NATS_STREAM_MAX_AGE";
150 }
151}
152
153/// ETCD transport environment variables
154pub mod etcd {
155 /// ETCD endpoints (comma-separated list of URLs)
156 pub const ETCD_ENDPOINTS: &str = "ETCD_ENDPOINTS";
157
158 /// ETCD authentication environment variables
159 pub mod auth {
160 /// Username for ETCD authentication
161 pub const ETCD_AUTH_USERNAME: &str = "ETCD_AUTH_USERNAME";
162
163 /// Password for ETCD authentication
164 pub const ETCD_AUTH_PASSWORD: &str = "ETCD_AUTH_PASSWORD";
165
166 /// Path to CA certificate for ETCD TLS
167 pub const ETCD_AUTH_CA: &str = "ETCD_AUTH_CA";
168
169 /// Path to client certificate for ETCD TLS
170 pub const ETCD_AUTH_CLIENT_CERT: &str = "ETCD_AUTH_CLIENT_CERT";
171
172 /// Path to client key for ETCD TLS
173 pub const ETCD_AUTH_CLIENT_KEY: &str = "ETCD_AUTH_CLIENT_KEY";
174 }
175}
176
177/// Key-Value Block Manager (KVBM) environment variables
178pub mod kvbm {
179 /// Enable KVBM metrics endpoint
180 pub const DYN_KVBM_METRICS: &str = "DYN_KVBM_METRICS";
181
182 /// KVBM metrics endpoint port
183 pub const DYN_KVBM_METRICS_PORT: &str = "DYN_KVBM_METRICS_PORT";
184
185 /// Enable KVBM recording for debugging.
186 pub const DYN_KVBM_ENABLE_RECORD: &str = "DYN_KVBM_ENABLE_RECORD";
187
188 /// Disable disk offload filter
189 pub const DYN_KVBM_DISABLE_DISK_OFFLOAD_FILTER: &str = "DYN_KVBM_DISABLE_DISK_OFFLOAD_FILTER";
190
191 /// CPU cache configuration
192 pub mod cpu_cache {
193 /// CPU cache size in GB
194 pub const DYN_KVBM_CPU_CACHE_GB: &str = "DYN_KVBM_CPU_CACHE_GB";
195
196 /// CPU cache size in number of blocks (override)
197 pub const DYN_KVBM_CPU_CACHE_OVERRIDE_NUM_BLOCKS: &str =
198 "DYN_KVBM_CPU_CACHE_OVERRIDE_NUM_BLOCKS";
199 }
200
201 /// Disk cache configuration
202 pub mod disk_cache {
203 /// Disk cache size in GB
204 pub const DYN_KVBM_DISK_CACHE_GB: &str = "DYN_KVBM_DISK_CACHE_GB";
205
206 /// Disk cache size in number of blocks (override)
207 pub const DYN_KVBM_DISK_CACHE_OVERRIDE_NUM_BLOCKS: &str =
208 "DYN_KVBM_DISK_CACHE_OVERRIDE_NUM_BLOCKS";
209 }
210
211 /// Object storage configuration
212 pub mod object_storage {
213 /// Enable object storage. Set to "1" to enable.
214 pub const DYN_KVBM_OBJECT_ENABLED: &str = "DYN_KVBM_OBJECT_ENABLED";
215
216 /// Bucket name for object storage cache
217 /// Supports `{worker_id}` template for per-worker buckets
218 /// Example: "kv-cache-{worker_id}"
219 pub const DYN_KVBM_OBJECT_BUCKET: &str = "DYN_KVBM_OBJECT_BUCKET";
220
221 /// Endpoint for object storage
222 pub const DYN_KVBM_OBJECT_ENDPOINT: &str = "DYN_KVBM_OBJECT_ENDPOINT";
223
224 /// Region for object storage
225 pub const DYN_KVBM_OBJECT_REGION: &str = "DYN_KVBM_OBJECT_REGION";
226
227 /// Access key for authentication
228 pub const DYN_KVBM_OBJECT_ACCESS_KEY: &str = "DYN_KVBM_OBJECT_ACCESS_KEY";
229
230 /// Secret key for authentication
231 pub const DYN_KVBM_OBJECT_SECRET_KEY: &str = "DYN_KVBM_OBJECT_SECRET_KEY";
232
233 /// Number of blocks to store in object storage
234 pub const DYN_KVBM_OBJECT_NUM_BLOCKS: &str = "DYN_KVBM_OBJECT_NUM_BLOCKS";
235 }
236 /// Transfer configuration
237 pub mod transfer {
238 /// Maximum number of blocks per transfer batch
239 pub const DYN_KVBM_TRANSFER_BATCH_SIZE: &str = "DYN_KVBM_TRANSFER_BATCH_SIZE";
240 }
241
242 /// KVBM leader (distributed mode) configuration
243 pub mod leader {
244 /// Timeout in seconds for KVBM leader and worker initialization
245 pub const DYN_KVBM_LEADER_WORKER_INIT_TIMEOUT_SECS: &str =
246 "DYN_KVBM_LEADER_WORKER_INIT_TIMEOUT_SECS";
247
248 /// ZMQ host for KVBM leader
249 pub const DYN_KVBM_LEADER_ZMQ_HOST: &str = "DYN_KVBM_LEADER_ZMQ_HOST";
250
251 /// ZMQ publish port for KVBM leader
252 pub const DYN_KVBM_LEADER_ZMQ_PUB_PORT: &str = "DYN_KVBM_LEADER_ZMQ_PUB_PORT";
253
254 /// ZMQ acknowledgment port for KVBM leader
255 pub const DYN_KVBM_LEADER_ZMQ_ACK_PORT: &str = "DYN_KVBM_LEADER_ZMQ_ACK_PORT";
256 }
257
258 /// NIXL backend configuration
259 pub mod nixl {
260 /// Prefix for NIXL backend environment variables
261 /// Pattern: DYN_KVBM_NIXL_BACKEND_<backend>=true/false
262 /// Example: DYN_KVBM_NIXL_BACKEND_UCX=true
263 pub const PREFIX: &str = "DYN_KVBM_NIXL_BACKEND_";
264 }
265}
266
267/// LLM (Language Model) inference environment variables
268pub mod llm {
269 /// HTTP body size limit in MB
270 pub const DYN_HTTP_BODY_LIMIT_MB: &str = "DYN_HTTP_BODY_LIMIT_MB";
271
272 pub const DYN_HTTP_GRACEFUL_SHUTDOWN_TIMEOUT_SECS: &str =
273 "DYN_HTTP_GRACEFUL_SHUTDOWN_TIMEOUT_SECS";
274
275 /// Enable LoRA adapter support (set to "true" to enable)
276 pub const DYN_LORA_ENABLED: &str = "DYN_LORA_ENABLED";
277
278 /// LoRA cache directory path
279 pub const DYN_LORA_PATH: &str = "DYN_LORA_PATH";
280
281 /// Enable the experimental Anthropic Messages API endpoint (/v1/messages)
282 pub const DYN_ENABLE_ANTHROPIC_API: &str = "DYN_ENABLE_ANTHROPIC_API";
283
284 /// Strip the Claude Code billing preamble (`x-anthropic-billing-header: ...`)
285 /// from the system prompt before forwarding to the target model. The preamble
286 /// varies per session and per release, wasting tokens and breaking prompt caching.
287 pub const DYN_STRIP_ANTHROPIC_PREAMBLE: &str = "DYN_STRIP_ANTHROPIC_PREAMBLE";
288
289 /// Enable streaming tool call dispatch (`event: tool_call_dispatch` SSE events)
290 pub const DYN_ENABLE_STREAMING_TOOL_DISPATCH: &str = "DYN_ENABLE_STREAMING_TOOL_DISPATCH";
291
292 /// Enable streaming reasoning dispatch (`event: reasoning_dispatch` SSE events)
293 pub const DYN_ENABLE_STREAMING_REASONING_DISPATCH: &str =
294 "DYN_ENABLE_STREAMING_REASONING_DISPATCH";
295
296 /// Backend stream inactivity timeout in seconds.
297 ///
298 /// When set to a positive integer, the frontend will kill the engine context
299 /// and drop the inflight guard if no SSE event is received from the backend
300 /// within this many seconds. Acts as a circuit breaker for zombie workers
301 /// that hold a live TCP connection but never produce output.
302 ///
303 /// Set to `0` or leave unset to disable the timeout (default: disabled).
304 pub const DYN_HTTP_BACKEND_STREAM_TIMEOUT_SECS: &str = "DYN_HTTP_BACKEND_STREAM_TIMEOUT_SECS";
305
306 /// Enable the LoRA allocation controller (set to "true" to enable)
307 pub const DYN_LORA_ALLOCATION_ENABLED: &str = "DYN_LORA_ALLOCATION_ENABLED";
308
309 /// LoRA allocation algorithm ("hrw" or "random")
310 pub const DYN_LORA_ALLOCATION_ALGORITHM: &str = "DYN_LORA_ALLOCATION_ALGORITHM";
311
312 /// LoRA allocation controller recompute interval in seconds
313 pub const DYN_LORA_ALLOCATION_TIMESTEP_SECS: &str = "DYN_LORA_ALLOCATION_TIMESTEP_SECS";
314
315 /// Ticks to wait before scaling down a LoRA's replicas
316 pub const DYN_LORA_ALLOCATION_SCALE_DOWN_COOLDOWN_TICKS: &str =
317 "DYN_LORA_ALLOCATION_SCALE_DOWN_COOLDOWN_TICKS";
318
319 /// Multiplier for the load estimator's rate window relative to the controller timestep.
320 pub const DYN_LORA_ALLOCATION_RATE_WINDOW_MULTIPLIER: &str =
321 "DYN_LORA_ALLOCATION_RATE_WINDOW_MULTIPLIER";
322
323 /// Number of counter buckets per second in the BucketedRateCounter.
324 pub const DYN_LORA_ALLOCATION_BUCKETS_PER_SECOND: &str =
325 "DYN_LORA_ALLOCATION_BUCKETS_PER_SECOND";
326
327 /// Load predictor type: "none" (raw counts) or "ema" (exponential moving average).
328 pub const DYN_LORA_ALLOCATION_PREDICTOR_TYPE: &str = "DYN_LORA_ALLOCATION_PREDICTOR_TYPE";
329
330 /// EMA smoothing factor (alpha) for the EMA predictor. Range [0.0, 1.0].
331 pub const DYN_LORA_ALLOCATION_EMA_ALPHA: &str = "DYN_LORA_ALLOCATION_EMA_ALPHA";
332
333 /// Metrics configuration
334 pub mod metrics {
335 /// Custom metrics prefix (overrides default "dynamo_frontend")
336 pub const DYN_METRICS_PREFIX: &str = "DYN_METRICS_PREFIX";
337
338 /// Histogram bucket configuration (pattern: <PREFIX>_MIN, <PREFIX>_MAX, <PREFIX>_COUNT)
339 /// Example: DYN_HISTOGRAM_TTFT_MIN, DYN_HISTOGRAM_TTFT_MAX, DYN_HISTOGRAM_TTFT_COUNT
340 pub const HISTOGRAM_PREFIX: &str = "DYN_HISTOGRAM_";
341 }
342
343 /// Audit sink configuration
344 pub mod audit {
345 /// Audit sink selection. Comma-separated values: `stderr`, `nats`,
346 /// `jsonl`, `jsonl_gz`. Setting any non-empty value enables audit
347 /// recording.
348 pub const DYN_AUDIT_SINKS: &str = "DYN_AUDIT_SINKS";
349
350 /// Force audit emission even when the request `store` flag is `false`.
351 pub const DYN_AUDIT_FORCE_LOGGING: &str = "DYN_AUDIT_FORCE_LOGGING";
352
353 /// In-process audit bus capacity.
354 pub const DYN_AUDIT_CAPACITY: &str = "DYN_AUDIT_CAPACITY";
355
356 /// NATS subject the JetStream audit sink publishes to.
357 pub const DYN_AUDIT_NATS_SUBJECT: &str = "DYN_AUDIT_NATS_SUBJECT";
358
359 /// Local output path for audit records.
360 ///
361 /// For `jsonl`, this is the literal file path. For `jsonl_gz`, this is
362 /// the segment prefix used to derive `<prefix>.<index>.jsonl.gz` files.
363 pub const DYN_AUDIT_OUTPUT_PATH: &str = "DYN_AUDIT_OUTPUT_PATH";
364
365 /// JSONL audit sink buffer size in bytes.
366 pub const DYN_AUDIT_JSONL_BUFFER_BYTES: &str = "DYN_AUDIT_JSONL_BUFFER_BYTES";
367
368 /// JSONL audit sink periodic flush interval in milliseconds.
369 pub const DYN_AUDIT_JSONL_FLUSH_INTERVAL_MS: &str = "DYN_AUDIT_JSONL_FLUSH_INTERVAL_MS";
370
371 /// Rotating gzip JSONL audit sink roll threshold in uncompressed bytes.
372 pub const DYN_AUDIT_JSONL_GZ_ROLL_BYTES: &str = "DYN_AUDIT_JSONL_GZ_ROLL_BYTES";
373
374 /// Rotating gzip JSONL audit sink roll threshold in record lines.
375 pub const DYN_AUDIT_JSONL_GZ_ROLL_LINES: &str = "DYN_AUDIT_JSONL_GZ_ROLL_LINES";
376 }
377
378 /// Agent trace configuration
379 pub mod agent_trace {
380 /// Agent trace sink selection. Comma-separated values: stderr,jsonl,jsonl_gz.
381 pub const DYN_AGENT_TRACE_SINKS: &str = "DYN_AGENT_TRACE_SINKS";
382
383 /// Local output path for normalized agent trace records.
384 ///
385 /// For `jsonl`, this is the literal file path. For `jsonl_gz`, this is the
386 /// segment prefix used to derive `<prefix>.<index>.jsonl.gz` files.
387 pub const DYN_AGENT_TRACE_OUTPUT_PATH: &str = "DYN_AGENT_TRACE_OUTPUT_PATH";
388
389 /// In-process trace bus capacity.
390 pub const DYN_AGENT_TRACE_CAPACITY: &str = "DYN_AGENT_TRACE_CAPACITY";
391
392 /// JSONL sink buffer size in bytes.
393 pub const DYN_AGENT_TRACE_JSONL_BUFFER_BYTES: &str = "DYN_AGENT_TRACE_JSONL_BUFFER_BYTES";
394
395 /// JSONL sink periodic flush interval in milliseconds.
396 pub const DYN_AGENT_TRACE_JSONL_FLUSH_INTERVAL_MS: &str =
397 "DYN_AGENT_TRACE_JSONL_FLUSH_INTERVAL_MS";
398
399 /// Rotating gzip JSONL sink roll threshold in uncompressed bytes.
400 pub const DYN_AGENT_TRACE_JSONL_GZ_ROLL_BYTES: &str = "DYN_AGENT_TRACE_JSONL_GZ_ROLL_BYTES";
401
402 /// Rotating gzip JSONL sink roll threshold in record lines.
403 pub const DYN_AGENT_TRACE_JSONL_GZ_ROLL_LINES: &str = "DYN_AGENT_TRACE_JSONL_GZ_ROLL_LINES";
404
405 /// Enable replay-oriented prompt block hashes in agent request trace records.
406 pub const DYN_AGENT_TRACE_REPLAY_HASHES: &str = "DYN_AGENT_TRACE_REPLAY_HASHES";
407
408 /// Local ZMQ PULL endpoint Dynamo binds for harness tool events.
409 pub const DYN_AGENT_TRACE_TOOL_EVENTS_ZMQ_ENDPOINT: &str =
410 "DYN_AGENT_TRACE_TOOL_EVENTS_ZMQ_ENDPOINT";
411
412 /// Optional first-frame ZMQ topic filter for harness tool events.
413 pub const DYN_AGENT_TRACE_TOOL_EVENTS_ZMQ_TOPIC: &str =
414 "DYN_AGENT_TRACE_TOOL_EVENTS_ZMQ_TOPIC";
415 }
416}
417
418/// Model loading and caching environment variables
419pub mod model {
420 /// Model Express configuration
421 pub mod model_express {
422 /// Model Express server endpoint URL
423 pub const MODEL_EXPRESS_URL: &str = "MODEL_EXPRESS_URL";
424
425 /// Model Express cache path
426 pub const MODEL_EXPRESS_CACHE_PATH: &str = "MODEL_EXPRESS_CACHE_PATH";
427 }
428
429 /// Hugging Face configuration
430 pub mod huggingface {
431 /// Hugging Face authentication token
432 pub const HF_TOKEN: &str = "HF_TOKEN";
433
434 /// Hugging Face Hub cache directory
435 pub const HF_HUB_CACHE: &str = "HF_HUB_CACHE";
436
437 /// Hugging Face home directory
438 pub const HF_HOME: &str = "HF_HOME";
439
440 /// Offline mode - skip API calls when model is cached
441 /// Set to "1" or "true" to enable
442 pub const HF_HUB_OFFLINE: &str = "HF_HUB_OFFLINE";
443 }
444}
445
446/// KV Router configuration environment variables
447pub mod router {
448 /// Scale applied to adjusted prompt-side prefill load after overlap/cache-hit credits.
449 pub const DYN_ROUTER_PREFILL_LOAD_SCALE: &str = "DYN_ROUTER_PREFILL_LOAD_SCALE";
450
451 /// Queue threshold fraction for prefill token capacity.
452 /// When set, requests are queued if all workers exceed this fraction of max_num_batched_tokens.
453 pub const DYN_ROUTER_QUEUE_THRESHOLD: &str = "DYN_ROUTER_QUEUE_THRESHOLD";
454
455 /// Scheduling policy for the router queue ("fcfs" or "wspt").
456 pub const DYN_ROUTER_QUEUE_POLICY: &str = "DYN_ROUTER_QUEUE_POLICY";
457}
458
459/// TCP response stream server (CallHome listener) environment variables
460pub mod tcp_response_stream {
461 /// Port for the TCP response stream server.
462 /// If unset or 0, the OS assigns a free ephemeral port.
463 pub const DYN_TCP_RESPONSE_STREAM_PORT: &str = "DYN_TCP_RESPONSE_STREAM_PORT";
464
465 /// Host/interface for the TCP response stream server.
466 /// If unset, the server auto-detects a routable local IP.
467 pub const DYN_TCP_RESPONSE_STREAM_HOST: &str = "DYN_TCP_RESPONSE_STREAM_HOST";
468}
469
470/// Event Plane transport environment variables
471pub mod event_plane {
472 /// Event transport selection: "zmq" or "nats".
473 ///
474 /// When unset the default depends on the discovery backend:
475 /// - `file` / `mem` backends: defaults to `zmq` (no external services required).
476 /// - `etcd` / `kubernetes` backends: defaults to `nats`.
477 ///
478 /// Set this explicitly to override the context-aware default.
479 pub const DYN_EVENT_PLANE: &str = "DYN_EVENT_PLANE";
480
481 /// Event plane codec selection: "json" or "msgpack".
482 pub const DYN_EVENT_PLANE_CODEC: &str = "DYN_EVENT_PLANE_CODEC";
483}
484
485/// ZMQ Broker environment variables
486pub mod zmq_broker {
487 /// Explicit ZMQ broker URL (takes precedence over discovery)
488 /// Format: "xsub=<url1>[;<url2>...] , xpub=<url1>[;<url2>...]"
489 /// Example: "xsub=tcp://broker:5555 , xpub=tcp://broker:5556"
490 pub const DYN_ZMQ_BROKER_URL: &str = "DYN_ZMQ_BROKER_URL";
491
492 /// Enable ZMQ broker discovery mode
493 pub const DYN_ZMQ_BROKER_ENABLED: &str = "DYN_ZMQ_BROKER_ENABLED";
494
495 /// XSUB bind address (broker binary only)
496 pub const ZMQ_BROKER_XSUB_BIND: &str = "ZMQ_BROKER_XSUB_BIND";
497
498 /// XPUB bind address (broker binary only)
499 pub const ZMQ_BROKER_XPUB_BIND: &str = "ZMQ_BROKER_XPUB_BIND";
500
501 /// Namespace for broker discovery registration
502 pub const ZMQ_BROKER_NAMESPACE: &str = "ZMQ_BROKER_NAMESPACE";
503}
504
505/// Discovery environment variables
506pub mod discovery {
507 /// Discovery backend: "kubernetes" or "etcd" (default)
508 pub const DYN_DISCOVERY_BACKEND: &str = "DYN_DISCOVERY_BACKEND";
509
510 /// Kube discovery mode: "pod" (default) or "container" (each container registers independently)
511 pub const DYN_KUBE_DISCOVERY_MODE: &str = "DYN_KUBE_DISCOVERY_MODE";
512}
513
514/// CUDA and GPU environment variables
515pub mod cuda {
516 /// Path to custom CUDA fatbin file.
517 ///
518 /// Note: build.rs files cannot import this constant at build time,
519 /// so they must define local constants with the same value.
520 pub const DYN_FATBIN_PATH: &str = "DYN_FATBIN_PATH";
521}
522
523/// Build-time environment variables
524pub mod build {
525 /// Cargo output directory for build artifacts
526 ///
527 /// Note: This constant cannot be used with the `env!()` macro,
528 /// which requires a string literal at compile time.
529 /// Build scripts (build.rs) also cannot import this constant.
530 pub const OUT_DIR: &str = "OUT_DIR";
531}
532
533/// Mocker (mock scheduler/KV manager) environment variables
534pub mod mocker {
535 /// Enable structured KV cache allocation/eviction trace logs (set to "1" or "true" to enable)
536 pub const DYN_MOCKER_KV_CACHE_TRACE: &str = "DYN_MOCKER_KV_CACHE_TRACE";
537
538 /// Use the original direct() code path in the mocker request dispatch.
539 ///
540 /// This path is race-prone during startup; prefer leaving it unset unless you are
541 /// explicitly trying to reproduce the original behavior.
542 pub const DYN_MOCKER_SYNC_DIRECT: &str = "DYN_MOCKER_SYNC_DIRECT";
543}
544
545/// Testing environment variables
546pub mod testing {
547 /// Enable queued-up request processing in tests
548 pub const DYN_QUEUED_UP_PROCESSING: &str = "DYN_QUEUED_UP_PROCESSING";
549
550 /// Soak test run duration (e.g., "3s", "5m")
551 pub const DYN_SOAK_RUN_DURATION: &str = "DYN_SOAK_RUN_DURATION";
552
553 /// Soak test batch load size
554 pub const DYN_SOAK_BATCH_LOAD: &str = "DYN_SOAK_BATCH_LOAD";
555}
556
557#[cfg(test)]
558mod tests {
559 use super::*;
560
561 #[test]
562 fn test_no_duplicate_env_var_names() {
563 use std::collections::HashSet;
564
565 let mut seen = HashSet::new();
566 let vars = [
567 // Logging
568 logging::DYN_LOG,
569 logging::DYN_LOGGING_CONFIG_PATH,
570 logging::DYN_LOGGING_JSONL,
571 logging::DYN_SDK_DISABLE_ANSI_LOGGING,
572 logging::DYN_LOG_USE_LOCAL_TZ,
573 logging::DYN_LOGGING_SPAN_EVENTS,
574 logging::otlp::OTEL_EXPORT_ENABLED,
575 logging::otlp::OTEL_EXPORTER_OTLP_TRACES_ENDPOINT,
576 logging::otlp::OTEL_SERVICE_NAME,
577 logging::otlp::OTEL_EXPORTER_OTLP_LOGS_ENDPOINT,
578 // Runtime
579 runtime::DYN_RUNTIME_NUM_WORKER_THREADS,
580 runtime::DYN_RUNTIME_MAX_BLOCKING_THREADS,
581 runtime::system::DYN_SYSTEM_ENABLED,
582 runtime::system::DYN_SYSTEM_HOST,
583 runtime::system::DYN_SYSTEM_PORT,
584 runtime::system::DYN_SYSTEM_USE_ENDPOINT_HEALTH_STATUS,
585 runtime::system::DYN_SYSTEM_STARTING_HEALTH_STATUS,
586 runtime::system::DYN_SYSTEM_HEALTH_PATH,
587 runtime::system::DYN_SYSTEM_LIVE_PATH,
588 runtime::canary::DYN_CANARY_WAIT_TIME,
589 // Worker
590 worker::DYN_WORKER_GRACEFUL_SHUTDOWN_TIMEOUT,
591 // NATS
592 nats::NATS_SERVER,
593 nats::auth::NATS_AUTH_USERNAME,
594 nats::auth::NATS_AUTH_PASSWORD,
595 nats::auth::NATS_AUTH_TOKEN,
596 nats::auth::NATS_AUTH_NKEY,
597 nats::auth::NATS_AUTH_CREDENTIALS_FILE,
598 nats::stream::DYN_NATS_STREAM_MAX_AGE,
599 // ETCD
600 etcd::ETCD_ENDPOINTS,
601 etcd::auth::ETCD_AUTH_USERNAME,
602 etcd::auth::ETCD_AUTH_PASSWORD,
603 etcd::auth::ETCD_AUTH_CA,
604 etcd::auth::ETCD_AUTH_CLIENT_CERT,
605 etcd::auth::ETCD_AUTH_CLIENT_KEY,
606 // KVBM
607 kvbm::DYN_KVBM_METRICS,
608 kvbm::DYN_KVBM_METRICS_PORT,
609 kvbm::DYN_KVBM_ENABLE_RECORD,
610 kvbm::DYN_KVBM_DISABLE_DISK_OFFLOAD_FILTER,
611 kvbm::cpu_cache::DYN_KVBM_CPU_CACHE_GB,
612 kvbm::cpu_cache::DYN_KVBM_CPU_CACHE_OVERRIDE_NUM_BLOCKS,
613 kvbm::disk_cache::DYN_KVBM_DISK_CACHE_GB,
614 kvbm::disk_cache::DYN_KVBM_DISK_CACHE_OVERRIDE_NUM_BLOCKS,
615 kvbm::leader::DYN_KVBM_LEADER_WORKER_INIT_TIMEOUT_SECS,
616 kvbm::leader::DYN_KVBM_LEADER_ZMQ_HOST,
617 kvbm::leader::DYN_KVBM_LEADER_ZMQ_PUB_PORT,
618 kvbm::leader::DYN_KVBM_LEADER_ZMQ_ACK_PORT,
619 // LLM
620 llm::DYN_HTTP_BODY_LIMIT_MB,
621 llm::DYN_HTTP_BACKEND_STREAM_TIMEOUT_SECS,
622 llm::DYN_LORA_ENABLED,
623 llm::DYN_LORA_PATH,
624 llm::DYN_ENABLE_ANTHROPIC_API,
625 llm::DYN_STRIP_ANTHROPIC_PREAMBLE,
626 llm::DYN_ENABLE_STREAMING_TOOL_DISPATCH,
627 llm::DYN_ENABLE_STREAMING_REASONING_DISPATCH,
628 llm::DYN_LORA_ALLOCATION_ENABLED,
629 llm::DYN_LORA_ALLOCATION_ALGORITHM,
630 llm::DYN_LORA_ALLOCATION_TIMESTEP_SECS,
631 llm::DYN_LORA_ALLOCATION_SCALE_DOWN_COOLDOWN_TICKS,
632 llm::DYN_LORA_ALLOCATION_RATE_WINDOW_MULTIPLIER,
633 llm::DYN_LORA_ALLOCATION_BUCKETS_PER_SECOND,
634 llm::DYN_LORA_ALLOCATION_PREDICTOR_TYPE,
635 llm::DYN_LORA_ALLOCATION_EMA_ALPHA,
636 llm::metrics::DYN_METRICS_PREFIX,
637 llm::audit::DYN_AUDIT_SINKS,
638 llm::audit::DYN_AUDIT_FORCE_LOGGING,
639 llm::audit::DYN_AUDIT_CAPACITY,
640 llm::audit::DYN_AUDIT_NATS_SUBJECT,
641 llm::audit::DYN_AUDIT_OUTPUT_PATH,
642 llm::audit::DYN_AUDIT_JSONL_BUFFER_BYTES,
643 llm::audit::DYN_AUDIT_JSONL_FLUSH_INTERVAL_MS,
644 llm::audit::DYN_AUDIT_JSONL_GZ_ROLL_BYTES,
645 llm::audit::DYN_AUDIT_JSONL_GZ_ROLL_LINES,
646 llm::agent_trace::DYN_AGENT_TRACE_SINKS,
647 llm::agent_trace::DYN_AGENT_TRACE_OUTPUT_PATH,
648 llm::agent_trace::DYN_AGENT_TRACE_CAPACITY,
649 llm::agent_trace::DYN_AGENT_TRACE_JSONL_BUFFER_BYTES,
650 llm::agent_trace::DYN_AGENT_TRACE_JSONL_FLUSH_INTERVAL_MS,
651 llm::agent_trace::DYN_AGENT_TRACE_JSONL_GZ_ROLL_BYTES,
652 llm::agent_trace::DYN_AGENT_TRACE_JSONL_GZ_ROLL_LINES,
653 llm::agent_trace::DYN_AGENT_TRACE_REPLAY_HASHES,
654 llm::agent_trace::DYN_AGENT_TRACE_TOOL_EVENTS_ZMQ_ENDPOINT,
655 llm::agent_trace::DYN_AGENT_TRACE_TOOL_EVENTS_ZMQ_TOPIC,
656 // Model
657 model::model_express::MODEL_EXPRESS_URL,
658 model::model_express::MODEL_EXPRESS_CACHE_PATH,
659 model::huggingface::HF_TOKEN,
660 model::huggingface::HF_HUB_CACHE,
661 model::huggingface::HF_HOME,
662 model::huggingface::HF_HUB_OFFLINE,
663 // Router
664 router::DYN_ROUTER_PREFILL_LOAD_SCALE,
665 router::DYN_ROUTER_QUEUE_THRESHOLD,
666 router::DYN_ROUTER_QUEUE_POLICY,
667 // TCP Response Stream
668 tcp_response_stream::DYN_TCP_RESPONSE_STREAM_PORT,
669 tcp_response_stream::DYN_TCP_RESPONSE_STREAM_HOST,
670 // Event Plane
671 event_plane::DYN_EVENT_PLANE,
672 event_plane::DYN_EVENT_PLANE_CODEC,
673 // ZMQ Broker
674 zmq_broker::DYN_ZMQ_BROKER_URL,
675 zmq_broker::DYN_ZMQ_BROKER_ENABLED,
676 zmq_broker::ZMQ_BROKER_XSUB_BIND,
677 zmq_broker::ZMQ_BROKER_XPUB_BIND,
678 zmq_broker::ZMQ_BROKER_NAMESPACE,
679 // Discovery
680 discovery::DYN_DISCOVERY_BACKEND,
681 discovery::DYN_KUBE_DISCOVERY_MODE,
682 // CUDA
683 cuda::DYN_FATBIN_PATH,
684 // Build
685 build::OUT_DIR,
686 // Mocker
687 mocker::DYN_MOCKER_KV_CACHE_TRACE,
688 mocker::DYN_MOCKER_SYNC_DIRECT,
689 // Testing
690 testing::DYN_QUEUED_UP_PROCESSING,
691 testing::DYN_SOAK_RUN_DURATION,
692 testing::DYN_SOAK_BATCH_LOAD,
693 ];
694
695 for var in &vars {
696 if !seen.insert(var) {
697 panic!("Duplicate environment variable name: {}", var);
698 }
699 }
700 }
701
702 #[test]
703 fn test_naming_conventions() {
704 // Dynamo-specific vars should start with DYN_
705 assert!(runtime::DYN_RUNTIME_NUM_WORKER_THREADS.starts_with("DYN_"));
706 assert!(runtime::system::DYN_SYSTEM_ENABLED.starts_with("DYN_"));
707 assert!(kvbm::DYN_KVBM_METRICS.starts_with("DYN_"));
708 assert!(worker::DYN_WORKER_GRACEFUL_SHUTDOWN_TIMEOUT.starts_with("DYN_"));
709
710 // NATS vars should start with NATS_
711 assert!(nats::NATS_SERVER.starts_with("NATS_"));
712 assert!(nats::auth::NATS_AUTH_USERNAME.starts_with("NATS_AUTH_"));
713
714 // ETCD vars should start with ETCD_
715 assert!(etcd::ETCD_ENDPOINTS.starts_with("ETCD_"));
716 assert!(etcd::auth::ETCD_AUTH_USERNAME.starts_with("ETCD_AUTH_"));
717
718 // OpenTelemetry vars should start with OTEL_
719 assert!(logging::otlp::OTEL_EXPORT_ENABLED.starts_with("OTEL_"));
720 assert!(logging::otlp::OTEL_SERVICE_NAME.starts_with("OTEL_"));
721 }
722}