[RFC] Model console logging configuration as CLI/serve configuration

Problem

This is a logging-focused offshoot of #25700. vLLM's ordinary console logging is configured primarily through environment variables, with related CLI fields spread across other configuration classes. The settings are therefore not represented by one typed configuration and cannot all be supplied, validated, or documented consistently through the CLI and --config YAML.

Proposal

Introduce a typed LoggingConfig on VllmConfig for vLLM-managed console logging. Expose the complete object as --logging-config JSON, as individual dotted CLI arguments, through --config YAML, and through Python configuration.

Start with the three existing environment-backed settings needed to establish the model:

• configure_logging, defaulting from VLLM_CONFIGURE_LOGGING
• log_level, defaulting from VLLM_LOGGING_LEVEL
• pylogging_config_file, defaulting from VLLM_LOGGING_CONFIG_PATH

For example, the following forms are equivalent:

vllm serve MODEL --logging-config '{"log_level":"DEBUG"}'
vllm serve MODEL --logging-config.log_level DEBUG
vllm serve MODEL --log-level DEBUG

and in a serve configuration file:

logging-config:
  log_level: DEBUG

--log-level should be a convenience override for log_level. The pre-existing --log-config-file should remain as a legacy override for pylogging_config_file.

Configuration precedence should be:

--log-level / --log-config-file > --logging-config CLI > --config YAML > compatibility environment variable > default

pylogging_config_file remains an advanced escape hatch for supplying a complete Python logging.config.dictConfig JSON file; it is not a vLLM configuration file mirroring CLI arguments. A custom dictConfig is authoritative over log_level for its logger, handler, and formatter settings, and requires configure_logging to be enabled. A CLI-supplied file must configure vLLM, Uvicorn, and subprocess logging consistently.

Prototype implementation: #57205.

Suggested first implementation slice

• Add LoggingConfig to VllmConfig with configure_logging, log_level, and pylogging_config_file.
• Expose the object as --logging-config JSON and dotted CLI arguments.
• Add --log-level as a convenience override and retain --log-config-file as a legacy override.
• Support the same model through --config YAML and Python configuration.
• Retain the existing environment variables as compatibility defaults with the precedence above.
• Apply the resolved configuration after argument parsing and propagate it consistently to vLLM, Uvicorn, and child processes.
• Make consumers use the effective logger configuration rather than rereading VLLM_LOGGING_LEVEL.
• Preserve the existing default text output and custom-dictConfig behavior.
• Add parsing, precedence, post-import reconfiguration, and subprocess coverage.

Follow-up checklist

• Decide whether and when to deprecate the legacy --log-config-file alias.
• VLLM_LOGGING_STREAM -> log_stream / --log-stream
• VLLM_LOGGING_PREFIX -> log_prefix / --log-prefix
• VLLM_LOGGING_COLOR and standard NO_COLOR behavior -> log_color / --log-color
• Existing enable_log_requests / --enable-log-requests
• Existing max_log_len / --max-log-len
• Existing enable_log_outputs / --enable-log-outputs
• Existing enable_log_deltas / --enable-log-deltas
• Existing log_error_stack / --log-error-stack
• Define how future built-in logging fields interact with an explicitly supplied Python dictConfig.
• Document and test CLI/YAML/environment/default precedence.
• Verify propagation to the API server, engine core, workers, Uvicorn, and offline/library entry points where applicable.

Scope

This issue covers configuration of the Python logging that normally emits to the console, plus generic request-log policy. It does not attempt to collect every setting whose name happens to contain "log".

For example, --disable-log-stats, VLLM_LOG_STATS_INTERVAL, and --aggregate-engine-logging belong with engine statistics; log_balancedness belongs in EPLBConfig; and VLLM_TRACE_FUNCTION is a separate debugging probe. Similar feature-specific controls should remain with their owning domain configuration.

Related future settings

New logging features should extend this model rather than add more standalone environment variables. Examples include:

• --log-file PATH for the file-output request in #31863
• --log-format {text,json,otel-json} for built-in structured profiles
• a process-prefix policy for #28582

---

Prepared with assistance from OpenAI Codex.