프로덕션 메트릭

프로덕션 메트릭 (Production Metrics)

프로덕션에서 vLLM을 운영하다 보면 "지금 얼마나 바쁜지", "KV 캐시가 얼마나 찼는지", "요청 지연이 어떤지"를 수치로 알고 싶어져요. vLLM은 Prometheus로 노출되는 다양한 메트릭을 제공합니다. 이 문서는 그 메트릭들을 유형별(Counter, Gauge, Histogram)로 정리해요.

출처: vLLM 공식 문서 — metrics

일반 메트릭 (General Metrics)

Counter

메트릭	타입	설명
`vllm:external_prefix_cache_queries`	Counter	KV 커넥터의 교차 인스턴스 캐시 공유에서 외부 프리픽스 캐시 쿼리 (쿼리된 토큰 수)
`vllm:generation_tokens`	Counter	처리된 생성 토큰 수
`vllm:mm_cache_hits`	Counter	멀티모달 캐시 히트 (캐시된 항목 수)
`vllm:mm_cache_queries`	Counter	멀티모달 캐시 쿼리 (쿼리된 항목 수)
`vllm:num_preemptions`	Counter	엔진의 누적 선점(preemption) 수
`vllm:prefix_cache_hits`	Counter	프리픽스 캐시 히트 (캐시된 토큰 수)
`vllm:prefix_cache_queries`	Counter	프리픽스 캐시 쿼리 (쿼리된 토큰 수)
`vllm:prompt_tokens`	Counter	처리된 prefill 토큰 수
`vllm:prompt_tokens_by_source`	Counter	소스별 프롬프트 토큰 수
`vllm:prompt_tokens_cached`	Counter	캐시된 프롬프트 토큰 수 (로컬 + 외부)
`vllm:request_success`	Counter	성공적으로 처리된 요청 수

Gauge

메트릭	타입	설명
`vllm:engine_sleep_state`	Gauge	엔진 슬립 상태; awake = 0은 엔진이 잠자는 중, awake = 1은 깨어 있음; weights_offloaded = 1은 슬립 레벨 1, discard_all = 1은 슬립 레벨 2
`vllm:kv_cache_usage_perc`	Gauge	KV 캐시 사용률. 1이면 100% 사용
`vllm:lora_requests_info`	Gauge	LoRA 요청에 대한 실행 통계
`vllm:num_requests_running`	Gauge	모델 실행 배치에 있는 요청 수
`vllm:num_requests_waiting`	Gauge	처리 대기 중인 요청 수

Histogram

메트릭	타입	설명
`vllm:e2e_request_latency_seconds`	Histogram	e2e 요청 지연(초) 히스토그램
`vllm:inter_token_latency_seconds`	Histogram	토큰 간 지연(초) 히스토그램
`vllm:iteration_tokens_total`	Histogram	engine_step당 토큰 수 히스토그램
`vllm:kv_block_idle_before_evict_seconds`	Histogram	KV 캐시 블록 축출 전 유휴 시간 히스토그램. 샘플링 메트릭 (`--kv-cache-metrics-sample`로 제어)
`vllm:kv_block_reuse_gap_seconds`	Histogram	연속 KV 캐시 블록 접근 사이의 시간 간격 히스토그램. 가장 최근 접근만 기록 (링 버퍼). 샘플링 메트릭 (`--kv-cache-metrics-sample`로 제어)
`vllm:request_decode_time_seconds`	Histogram	요청의 DECODE 단계에 소요된 시간 히스토그램
`vllm:request_generation_tokens`	Histogram	처리된 생성 토큰 수
`vllm:request_inference_time_seconds`	Histogram	요청의 RUNNING 단계에 소요된 시간 히스토그램
`vllm:request_max_num_generation_tokens`	Histogram	요청된 최대 생성 토큰 수 히스토그램
`vllm:request_prompt_tokens`	Histogram	처리된 prefill 토큰 수
`vllm:request_queue_time_seconds`	Histogram	요청의 WAITING 단계에 소요된 시간 히스토그램
`vllm:request_time_per_output_token_seconds`	Histogram	요청별 output 토큰당 시간 히스토그램
`vllm:time_to_first_token_seconds`	Histogram	첫 토큰까지의 시간(초) 히스토그램

NIXL KV 커넥터 메트릭

메트릭	타입	설명
`vllm:nixl_num_failed_notifications`	Counter	실패한 NIXL KV Cache 알림 수
`vllm:nixl_bytes_transferred`	Histogram	NIXL KV Cache 전송당 전송된 바이트 히스토그램

더 알아보기 (Learn more)