feat: add flag for dumping dynamo engine config and environment (#3286)

Signed-off-by: William Arnold <[email protected]>

Author: Aphoh

.gitignore

@@ -100,4 +100,7 @@ TensorRT-LLM
 /CLAUDE.md.bak
 
 # Benchmarks
-benchmarks/results
+benchmarks/results
+
+# Direnv
+.envrc

components/src/dynamo/common/__init__.py

@@ -0,0 +1,17 @@
+# SPDX-FileCopyrightText: Copyright (c) 2025 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+"""
+Dynamo Common Module
+
+This module contains shared utilities and components used across multiple
+Dynamo backends and components.
+
+Main submodules:
+    - config_dump: Configuration dumping and system diagnostics utilities
+"""
+
+from dynamo.common import config_dump
+from dynamo.common._version import __version__
+
+__all__ = ["__version__", "config_dump"]

components/src/dynamo/common/config_dump/__init__.py

@@ -0,0 +1,33 @@
+# SPDX-FileCopyrightText: Copyright (c) 2025 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+"""
+Configuration Dumping Utilities
+
+This module provides utilities for dumping configuration and system information
+for debugging and diagnostics purposes.
+"""
+
+from dynamo.common.config_dump.config_dumper import (
+    add_config_dump_args,
+    dump_config,
+    get_config_dump,
+    register_encoder,
+)
+from dynamo.common.config_dump.environment import get_environment_vars
+from dynamo.common.config_dump.system_info import (
+    get_gpu_info,
+    get_runtime_info,
+    get_system_info,
+)
+
+__all__ = [
+    "add_config_dump_args",
+    "dump_config",
+    "get_config_dump",
+    "get_environment_vars",
+    "get_gpu_info",
+    "get_runtime_info",
+    "get_system_info",
+    "register_encoder",
+]

components/src/dynamo/common/config_dump/config_dumper.py

@@ -0,0 +1,229 @@
+# SPDX-FileCopyrightText: Copyright (c) 2025 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+import argparse
+import dataclasses
+import functools
+import json
+import logging
+import pathlib
+from enum import Enum
+from typing import Any, Dict, Optional
+
+from dynamo.common._version import __version__
+
+from .environment import get_environment_vars
+from .system_info import (
+    get_gpu_info,
+    get_package_info,
+    get_runtime_info,
+    get_system_info,
+)
+
+logger = logging.getLogger(__name__)
+
+
+def _get_sglang_version() -> Optional[str]:
+    """Get SGLang version if available.
+
+    Returns:
+        Version string if SGLang is installed, None otherwise.
+    """
+    try:
+        import sglang as sgl
+
+        return sgl.__version__
+    except ImportError:
+        logger.debug("SGLang not available")
+        return None
+    except AttributeError:
+        logger.warning("SGLang installed but version not available")
+        return None
+
+
+def _get_trtllm_version() -> Optional[str]:
+    """Get TensorRT-LLM version if available.
+
+    Returns:
+        Version string if TensorRT-LLM is installed, None otherwise.
+    """
+    try:
+        import tensorrt_llm
+
+        return tensorrt_llm.__version__
+    except ImportError:
+        logger.debug("TensorRT-LLM not available")
+        return None
+    except AttributeError:
+        logger.warning("TensorRT-LLM installed but version not available")
+        return None
+
+
+def _get_vllm_version() -> Optional[str]:
+    """Get vLLM version if available.
+
+    Returns:
+        Version string if vLLM is installed, None otherwise.
+    """
+    try:
+        import vllm
+
+        return vllm.__version__
+    except ImportError:
+        logger.debug("vLLM not available")
+        return None
+    except AttributeError:
+        logger.warning("vLLM installed but version not available")
+        return None
+
+
+def dump_config(dump_config_to: Optional[str], config: Any) -> None:
+    """
+    Dump the configuration to a file or stdout.
+
+    If dump_config_to is not provided, the config will be logged to stdout at VERBOSE level.
+
+    Args:
+        dump_config_to: Optional path to dump the config to. If None, logs to stdout.
+        config: The configuration object to dump (must be JSON-serializable).
+
+    Raises:
+        Logs errors but does not raise exceptions to ensure graceful degradation.
+    """
+    config_dump_payload = get_config_dump(config)
+
+    if dump_config_to:
+        try:
+            dump_path = pathlib.Path(dump_config_to)
+            dump_path.parent.mkdir(parents=True, exist_ok=True)
+            with open(dump_path.resolve(), "w", encoding="utf-8") as f:
+                f.write(config_dump_payload)
+            logger.info(f"Dumped config to {dump_path.resolve()}")
+        except (OSError, IOError):
+            logger.exception(f"Failed to dump config to {dump_config_to}")
+            logger.info(f"CONFIG_DUMP: {config_dump_payload}")
+        except Exception:
+            logger.exception("Unexpected error dumping config")
+            logger.info(f"CONFIG_DUMP: {config_dump_payload}")
+    else:
+        logger.info(f"CONFIG_DUMP: {config_dump_payload}")
+
+
+def get_config_dump(config: Any, extra_info: Optional[Dict[str, Any]] = None) -> str:
+    """
+    Collect comprehensive config information about a backend instance.
+
+    Args:
+        config: Any JSON-serializable object containing the backend configuration.
+        extra_info: Optional dict of additional information to include in the dump.
+
+    Returns:
+        JSON string containing comprehensive information.
+
+    Note:
+        Returns error information if collection fails, ensuring some diagnostic data is always available.
+    """
+    if extra_info is None:
+        extra_info = {}
+    try:
+        config_dump = {
+            "system_info": get_system_info(),
+            "environment": get_environment_vars(),
+            "config": config,
+            "runtime_info": get_runtime_info(),
+            "dynamo_version": __version__,
+            "gpu_info": get_gpu_info(),
+            "installed_packages": get_package_info(),
+        }
+
+        # Add common versions
+        if ver := _get_sglang_version():
+            config_dump["sglang_version"] = ver
+        if ver := _get_trtllm_version():
+            config_dump["trtllm_version"] = ver
+        if ver := _get_vllm_version():
+            config_dump["vllm_version"] = ver
+
+        # Add any extra information provided by the caller
+        if extra_info:
+            config_dump.update(extra_info)
+
+        return canonical_json_encoder.encode(config_dump)
+
+    except Exception as e:
+        logger.error(f"Error collecting config dump: {e}")
+        # Return a basic error response with at least system info
+        error_info = {
+            "error": f"Failed to collect config dump: {str(e)}",
+            "system_info": get_system_info(),  # Always try to include basic system info
+        }
+        return canonical_json_encoder.encode(error_info)
+
+
+def add_config_dump_args(parser: argparse.ArgumentParser):
+    """
+    Add arguments to the parser to dump the config to a file.
+
+    Args:
+        parser: The parser to add the arguments to
+    """
+    parser.add_argument(
+        "--dump-config-to",
+        type=str,
+        default=None,
+        help="Dump config to the specified file path. If not specified, the config will be dumped to stdout at INFO level.",
+    )
+
+
+@functools.singledispatch
+def _preprocess_for_encode(obj: object) -> object:
+    """
+    Single dispatch function for preprocessing objects before JSON encoding.
+
+    This function should be extended using @register_encoder decorator
+    for backend-specific types.
+    """
+    if dataclasses.is_dataclass(obj) and not isinstance(obj, type):
+        return dataclasses.asdict(obj)
+    logger.warning(f"Unknown type {type(obj)}, using __dict__ or str(obj)")
+    if hasattr(obj, "__dict__"):
+        return obj.__dict__
+    return str(obj)
+
+
+def register_encoder(type_class):
+    """
+    Decorator to register custom encoders for specific types.
+
+    Usage:
+        @register_encoder(MyClass)
+        def encode_my_class(obj: MyClass):
+            return {"field": obj.field}
+    """
+    logger.debug(f"Registering encoder for {type_class}")
+    return _preprocess_for_encode.register(type_class)
+
+
+@register_encoder(set)
+def _preprocess_for_encode_set(
+    obj: set,
+) -> list:  # pyright: ignore[reportUnusedFunction]
+    return sorted(list(obj))
+
+
+@register_encoder(Enum)
+def _preprocess_for_encode_enum(
+    obj: Enum,
+) -> str:  # pyright: ignore[reportUnusedFunction]
+    return str(obj)
+
+
+# Create a canonical JSON encoder with consistent formatting
+canonical_json_encoder = json.JSONEncoder(
+    ensure_ascii=False,
+    separators=(",", ":"),
+    allow_nan=False,
+    sort_keys=True,
+    indent=None,
+    default=_preprocess_for_encode,
+)

components/src/dynamo/common/config_dump/environment.py

@@ -0,0 +1,92 @@
+# SPDX-FileCopyrightText: Copyright (c) 2025 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+import os
+from typing import Dict, List, Optional, Set
+
+# Default environment variable prefixes to capture
+# These cover common ML/GPU/Dynamo-related configurations
+DEFAULT_ENV_PREFIXES = [
+    "DYN_",  # Dynamo-specific variables
+    "CUDA_",  # CUDA configuration
+    "NCCL_",  # NVIDIA Collective Communications Library
+    "HF_",  # HuggingFace
+    "TRANSFORMERS_",  # Transformers library
+    "SGLANG_",  # SGLang
+    "SGL_",  # SGLang (short prefix)
+    "MC_",  # Mooncake
+    "VLLM_",  # vLLM
+    "TENSORRT_",  # TensorRT
+    "TORCH_",  # PyTorch
+    "UCX_",  # UCX
+    "NIXL_",  # NIXL
+    "OMPI_",  # OpenMPI
+]
+
+# Sensitive variable patterns to redact (case-insensitive)
+SENSITIVE_PATTERNS = [
+    "TOKEN",
+    "API_KEY",
+    "SECRET",
+    "PASSWORD",
+    "CREDENTIAL",
+    "AUTH",
+]
+
+
+def get_environment_vars(
+    prefixes: Optional[List[str]] = None,
+    include_sensitive: bool = False,
+    additional_vars: Optional[Set[str]] = None,
+) -> Dict[str, str]:
+    """
+    Get relevant environment variables based on prefixes.
+
+    Args:
+        prefixes: List of environment variable prefixes to capture.
+                  If None, uses DEFAULT_ENV_PREFIXES.
+        include_sensitive: If False, redacts values of potentially sensitive variables.
+                          Default is False for security.
+        additional_vars: Set of specific variable names to include regardless of prefix.
+
+    Returns:
+        Dictionary of environment variable names to values.
+        Sensitive values are replaced with "<REDACTED>" unless include_sensitive is True.
+
+    Examples:
+        >>> get_environment_vars()  # Uses default prefixes
+        >>> get_environment_vars(prefixes=["MY_APP_"])  # Custom prefixes only
+        >>> get_environment_vars(additional_vars={"PATH", "HOME"})  # Include specific vars
+    """
+    if prefixes is None:
+        prefixes = DEFAULT_ENV_PREFIXES
+
+    if additional_vars is None:
+        additional_vars = set()
+
+    relevant_env_vars = {}
+
+    for key, value in os.environ.items():
+        # Check if matches prefix or is in additional_vars
+        if any(key.startswith(prefix) for prefix in prefixes) or key in additional_vars:
+            # Redact sensitive values unless explicitly requested
+            if not include_sensitive and _is_sensitive(key):
+                relevant_env_vars[key] = "<REDACTED>"
+            else:
+                relevant_env_vars[key] = value
+
+    return relevant_env_vars
+
+
+def _is_sensitive(var_name: str) -> bool:
+    """
+    Check if an environment variable name suggests it contains sensitive data.
+
+    Args:
+        var_name: The environment variable name to check.
+
+    Returns:
+        True if the variable name matches sensitive patterns.
+    """
+    var_name_upper = var_name.upper()
+    return any(pattern in var_name_upper for pattern in SENSITIVE_PATTERNS)