Implementation:Vllm project Vllm Logger
| Knowledge Sources | |
|---|---|
| Domains | Logging, Configuration |
| Last Updated | 2026-02-08 00:00 GMT |
Overview
Configures vLLM's logging system with colored formatters, custom log levels, deduplication methods, and a factory function for creating properly configured logger instances.
Description
logger.py is vLLM's logging infrastructure module. It provides the init_logger() factory function that creates logger instances with patched convenience methods (debug_once, info_once, warning_once) which use @lru_cache to deduplicate repeated log messages. The module configures the root "vllm" logger via dictConfig using either a default configuration or a custom JSON config file specified by VLLM_LOGGING_CONFIG_PATH.
The default configuration supports colored output (via ColoredFormatter) that auto-detects TTY availability, configurable log levels via VLLM_LOGGING_LEVEL, and output stream selection via VLLM_LOGGING_STREAM. The module also provides enable_trace_function_call() for recording every Python function call within the vLLM codebase, useful for debugging hangs and crashes. Scoped logging (LogScope) enables log deduplication across distributed ranks (global-first-rank, local-first-rank, or per-process).
Usage
Every vLLM module that needs logging calls init_logger(__name__) at module level to obtain a configured logger. The *_once methods prevent log spam from frequently called code paths (e.g., inside model forward passes). The root logger is configured once at module import time, and additional loggers (e.g., httpx) are set to WARNING to reduce noise.
Code Reference
Source Location
- Repository: vllm
- File: vllm/logger.py
- Lines: 1-316
Signature
class _VllmLogger(Logger):
def debug_once(self, msg: str, *args: Hashable, scope: LogScope = "process") -> None: ...
def info_once(self, msg: str, *args: Hashable, scope: LogScope = "process") -> None: ...
def warning_once(self, msg: str, *args: Hashable, scope: LogScope = "process") -> None: ...
def init_logger(name: str) -> _VllmLogger: ...
def suppress_logging(level: int = logging.INFO) -> Generator[None, Any, None]: ...
def current_formatter_type(lgr: Logger) -> Literal["color", "newline", None]: ...
def enable_trace_function_call(log_file_path: str, root_dir: str | None = None) -> None: ...
LogScope = Literal["process", "global", "local"]
Import
from vllm.logger import init_logger
logger = init_logger(__name__)
I/O Contract
Inputs
| Name | Type | Required | Description |
|---|---|---|---|
| name | str | Yes | Logger name, typically __name__ of the calling module
|
| VLLM_CONFIGURE_LOGGING | env var | No | Whether to apply vLLM's default logging configuration (default: True) |
| VLLM_LOGGING_CONFIG_PATH | env var | No | Path to a custom JSON logging configuration file |
| VLLM_LOGGING_LEVEL | env var | No | Log level string (e.g., "DEBUG", "INFO", "WARNING") |
| VLLM_LOGGING_STREAM | env var | No | Output stream: "ext://sys.stdout" or "ext://sys.stderr" |
| VLLM_LOGGING_COLOR | env var | No | Force color on ("1") or off ("0"); auto-detected if unset |
| VLLM_LOGGING_PREFIX | env var | No | Prefix string prepended to all vLLM log messages |
| NO_COLOR | env var | No | Standard no-color environment variable (disables colored output) |
Outputs
| Name | Type | Description |
|---|---|---|
| logger | _VllmLogger | Configured logger instance with debug_once, info_once, warning_once methods |
| log output | text | Formatted log messages written to the configured stream (stdout/stderr) |
Usage Examples
from vllm.logger import init_logger
logger = init_logger(__name__)
# Standard logging
logger.info("Model loaded with %d layers", num_layers)
# Log once to avoid spam in hot paths
logger.warning_once("Using fallback attention implementation")
# Log only on the global first rank in distributed settings
logger.info_once("Configuration loaded", scope="global")
# Suppress logging temporarily
from vllm.logger import suppress_logging
with suppress_logging():
# ... noisy operations ...
pass
# Enable function call tracing for debugging hangs
from vllm.logger import enable_trace_function_call
enable_trace_function_call("/tmp/vllm_trace.log")