로깅 설정

로깅 설정 (Logging Configuration)

vLLM은 Python의 logging.config.dictConfig 기능을 활용해 vLLM이 사용하는 여러 로거를 견고하고 유연하게 설정할 수 있게 합니다. 두 개의 환경변수를 제공해 단순하고 유연하지 않은 설정부터 더 복잡하고 유연한 설정까지 다양한 로깅 구성을 지원합니다.

출처: 문서

본문

소스: https://github.com/vllm-project/vllm/blob/main/examples/features/logging_configuration.md

vLLM은 다양한 vLLM 로거를 견고하고 유연하게 설정하기 위해 Python logging.config.dictConfig 기능을 활용합니다. vLLM은 단순하고 유연하지 않은 것부터 더 복잡하고 유연한 것에 이르는 다양한 로깅 구성을 수용하는 두 환경변수를 제공합니다.

• vLLM 로깅 없음 (단순·비유연) — VLLM_CONFIGURE_LOGGING=0 설정(VLLM_LOGGING_CONFIG_PATH는 비워 둠).
• vLLM 기본 로깅 구성 (단순·비유연) — VLLM_CONFIGURE_LOGGING을 비워 두거나 VLLM_CONFIGURE_LOGGING=1 설정.
• 세밀한 커스텀 로깅 구성 (더 복잡·더 유연) — VLLM_CONFIGURE_LOGGING을 비워 두거나 1로 두고, VLLM_LOGGING_CONFIG_PATH=<path-to-logging-config.json> 설정.

로깅 설정 환경변수 (Logging Configuration Environment Variables)

VLLM_CONFIGURE_LOGGING

VLLM_CONFIGURE_LOGGING은 vLLM이 사용하는 로거를 vLLM이 구성하는 작업을 수행할지 여부를 제어합니다. 이 기능은 기본적으로 활성화되어 있으며, vLLM 실행 시 VLLM_CONFIGURE_LOGGING=0으로 설정하면 비활성화할 수 있습니다.

VLLM_CONFIGURE_LOGGING이 활성화되고 VLLM_LOGGING_CONFIG_PATH 값이 없으면, vLLM은 내장 기본 구성을 사용해 루트 vLLM 로거를 구성합니다. 기본적으로 다른 vLLM 로거는 구성되지 않으며, 따라서 모든 vLLM 로거는 모든 로깅 결정을 루트 vLLM 로거에 위임합니다.

VLLM_CONFIGURE_LOGGING이 비활성화되고 VLLM_LOGGING_CONFIG_PATH 값이 주어지면 vLLM 시작 시 오류가 발생합니다.

VLLM_LOGGING_CONFIG_PATH

VLLM_LOGGING_CONFIG_PATH는 vLLM의 내장 기본 로깅 구성 대신 사용할 대체·커스텀 로깅 구성 JSON 파일 경로를 지정할 수 있게 합니다. 로깅 구성은 Python의 로깅 구성 딕셔너리 스키마에서 지정한 JSON 형식으로 제공해야 합니다.

VLLM_LOGGING_CONFIG_PATH가 지정되었는데 VLLM_CONFIGURE_LOGGING이 비활성화되어 있으면 vLLM 시작 시 오류가 발생합니다.

예제 (Examples)

예제 1: vLLM 루트 로거 커스터마이즈 (Customize vLLM root logger)

vLLM 루트 로거를 python-json-logger(컨테이너 이미지의 일부)를 사용해 콘솔 STDOUT에 INFO 로그 레벨로 JSON 형식 로깅하도록 커스터마이즈합니다.

먼저 적절한 JSON 로깅 구성 파일을 만듭니다.

/path/to/logging_config.json:

{
  "formatters": {
    "json": {
      "class": "pythonjsonlogger.jsonlogger.JsonFormatter"
    }
  },
  "handlers": {
    "console": {
      "class" : "logging.StreamHandler",
      "formatter": "json",
      "level": "INFO",
      "stream": "ext://sys.stdout"
    }
  },
  "loggers": {
    "vllm": {
      "handlers": ["console"],
      "level": "INFO",
      "propagate": false
    }
  },
  "version": 1
}

마지막으로 커스텀 로깅 구성 JSON 파일 경로로 VLLM_LOGGING_CONFIG_PATH 환경변수를 설정해 vLLM을 실행합니다.

VLLM_LOGGING_CONFIG_PATH=/path/to/logging_config.json \
    vllm serve mistralai/Mistral-7B-v0.1 --max-model-len 2048

예제 2: 특정 vLLM 로거 끄기 (Silence a particular vLLM logger)

특정 vLLM 로거를 끄려면 해당 로거에 대해 루트 vLLM 로거로 로그 메시지를 전파(propagate)하지 않도록 구성하는 커스텀 로깅 구성을 제공해야 합니다. 어떤 로거에든 커스텀 구성이 주어지면, 커스텀 로거 구성이 vLLM이 사용하는 내장 기본 로깅 구성을 덮어쓰기 때문에 루트 vLLM 로거 구성도 함께 제공해야 합니다.

먼저 루트 vLLM 로거와 끄려는 로거 구성이 포함된 JSON 구성 파일을 만듭니다.

/path/to/logging_config.json:

{
  "formatters": {
    "vllm": {
      "class": "vllm.logging_utils.NewLineFormatter",
      "datefmt": "%m-%d %H:%M:%S",
      "format": "%(levelname)s %(asctime)s %(filename)s:%(lineno)d] %(message)s"
    }
  },
  "handlers": {
    "vllm": {
      "class" : "logging.StreamHandler",
      "formatter": "vllm",
      "level": "INFO",
      "stream": "ext://sys.stdout"
    }
  },
  "loggers": {
    "vllm": {
      "handlers": ["vllm"],
      "level": "DEBUG",
      "propagate": false
    },
    "vllm.example_noisy_logger": {
      "propagate": false
    }
  },
  "version": 1
}

마지막으로 VLLM_LOGGING_CONFIG_PATH 환경변수를 설정해 실행합니다.

VLLM_LOGGING_CONFIG_PATH=/path/to/logging_config.json \
    vllm serve mistralai/Mistral-7B-v0.1 --max-model-len 2048

예제 3: vLLM 기본 로깅 구성 비활성화 (Disable vLLM default logging configuration)

vLLM의 기본 로깅 구성을 비활성화하고 모든 vLLM 로거를 끄려면, vLLM 실행 시 VLLM_CONFIGURE_LOGGING=0을 설정하면 됩니다. 이렇게 하면 vLLM이 루트 vLLM 로거를 구성하지 못하게 되어, 결과적으로 다른 모든 vLLM 로거도 조용해집니다.

VLLM_CONFIGURE_LOGGING=0 \
    vllm serve mistralai/Mistral-7B-v0.1 --max-model-len 2048

예제 4: 헬스체크 엔드포인트 접근 로그 비활성화 (Disable access logs for health check endpoints)

프로덕션 환경에서 /health, /metrics, /ping 같은 헬스체크 엔드포인트는 로드 밸런서와 모니터링 시스템이 자주 호출해, 반복적인 접근 로그가 대량 생성됩니다. 다른 엔드포인트의 로그를 유지하면서 로그 노이즈를 줄이려면 --disable-access-log-for-endpoints 옵션을 사용합니다.

헬스·메트릭 엔드포인트의 접근 로그를 끕니다:

vllm serve mistralai/Mistral-7B-v0.1 --max-model-len 2048 \
    --disable-access-log-for-endpoints /health,/metrics,/ping

필터링을 고려할 만한 일반적인 엔드포인트:

참고:

• 이 옵션은 uvicorn 접근 로그에만 영향을 주며, vLLM 애플리케이션 로그에는 영향이 없습니다.
• 여러 엔드포인트는 쉼표로 구분해 지정합니다(공백 없이).
• 필터는 정확한 경로 매칭을 사용하며, 쿼리 파라미터는 무시됩니다(예: /health?verbose=true는 /health와 매칭).
• 모든 접근 로그를 완전히 끄려면 대신 --disable-uvicorn-access-log를 사용하세요.

추가 자료 (Additional resources)

• logging.configDictionary 스키마 세부 사항

더 알아보기 (Learn more)

• 환경 변수 VLLM_CONFIGURE_LOGGING, VLLM_LOGGING_CONFIG_PATH
• CLI 옵션 --disable-access-log-for-endpoints, --disable-uvicorn-access-log
• Python logging.config.dictConfig 문서