프로덕션 메트릭

프로덕션 메트릭 (Production Metrics)

vLLM은 시스템 상태를 모니터링하는 데 사용할 수 있는 여러 메트릭을 노출합니다. 이 메트릭들은 vLLM OpenAI 호환 API 서버의 /metrics 엔드포인트를 통해 제공되며, Prometheus 같은 외부 모니터링 시스템과 연동해 실시간으로 서빙 상태를 추적할 수 있습니다.

출처: 문서

본문

vLLM은 시스템 상태를 모니터링하는 데 쓸 수 있는 여러 메트릭을 노출합니다. 이 메트릭들은 vLLM OpenAI 호환 API 서버의 /metrics 엔드포인트에서 제공됩니다.

서버를 Python으로 또는 Docker로 시작할 수 있습니다:

vllm serve unsloth/Llama-3.2-1B-Instruct

그런 다음 엔드포인트를 질의해 서버의 최신 메트릭을 얻습니다:

$ curl http://0.0.0.0:8000/metrics

# HELP vllm:iteration_tokens_total Histogram of number of tokens per engine_step.
# TYPE vllm:iteration_tokens_total histogram
vllm:iteration_tokens_total_sum{model_name="unsloth/Llama-3.2-1B-Instruct"} 0.0
vllm:iteration_tokens_total_bucket{le="1.0",model_name="unsloth/Llama-3.2-1B-Instruct"} 3.0
vllm:iteration_tokens_total_bucket{le="8.0",model_name="unsloth/Llama-3.2-1B-Instruct"} 3.0
vllm:iteration_tokens_total_bucket{le="16.0",model_name="unsloth/Llama-3.2-1B-Instruct"} 3.0
vllm:iteration_tokens_total_bucket{le="32.0",model_name="unsloth/Llama-3.2-1B-Instruct"} 3.0
vllm:iteration_tokens_total_bucket{le="64.0",model_name="unsloth/Llama-3.2-1B-Instruct"} 3.0
vllm:iteration_tokens_total_bucket{le="128.0",model_name="unsloth/Llama-3.2-1B-Instruct"} 3.0
vllm:iteration_tokens_total_bucket{le="256.0",model_name="unsloth/Llama-3.2-1B-Instruct"} 3.0
vllm:iteration_tokens_total_bucket{le="512.0",model_name="unsloth/Llama-3.2-1B-Instruct"} 3.0
...

다음 메트릭들이 노출됩니다:

일반 메트릭 (General Metrics)

메트릭 이름 타입 설명
vllm:corrupted_requests Counter logits에 NaN이 있는 요청 수 기준 손상된 요청
vllm:external_prefix_cache_hits Counter KV 커넥터 인스턴스 간 캐시 공유에서 온 외부 prefix cache 히트, 캐시된 토큰 수 기준
vllm:external_prefix_cache_queries Counter KV 커넥터 인스턴스 간 캐시 공유에서 온 외부 prefix cache 질의, 질의된 토큰 수 기준
vllm:generation_tokens Counter 처리된 생성 토큰 수
vllm:mm_cache_hits Counter 멀티모달 캐시 히트, 캐시된 항목 수 기준
vllm:mm_cache_queries Counter 멀티모달 캐시 질의, 질의된 항목 수 기준
vllm:num_preemptions Counter 엔진의 누적 선점(preemption) 수
vllm:prefix_cache_hits Counter prefix cache 히트, 캐시된 토큰 수 기준
vllm:prefix_cache_queries Counter prefix cache 질의, 질의된 토큰 수 기준
vllm:prompt_tokens Counter 처리된 prefill 토큰 수
vllm:prompt_tokens_by_source Counter 소스별 프롬프트 토큰 수
vllm:prompt_tokens_cached Counter 캐시된 프롬프트 토큰 수(로컬 + 외부)
vllm:request_success Counter 성공적으로 처리된 요청 수
vllm:engine_sleep_state Gauge 엔진 슬립 상태; awake=0이면 엔진 슬립 중, awake=1이면 깨어있음, weights_offloaded=1이면 슬립 레벨 1, discard_all=1이면 슬립 레벨 2
vllm:kv_cache_usage_perc Gauge KV-cache 사용률. 1이면 100% 사용
vllm:lora_requests_info Gauge lora 요청의 실행 통계
vllm:num_requests_running Gauge 모델 실행 배치의 요청 수
vllm:num_requests_waiting Gauge 처리 대기 중인 요청 수
vllm:num_requests_waiting_by_reason Gauge 사유별 대기 중인 요청 수. 사유 레이블: 'capacity' = 스케줄링 용량 대기; 'deferred' = 일시적 제약(LoRA 예산, KV 전송, blocked 상태)으로 지연. 모든 사유의 합은 vllm:num_requests_waiting과 같음
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 cache 블록 eviction 전 유휴 시간 히스토그램. 샘플 메트릭(--kv-cache-metrics-sample로 제어)
vllm:kv_block_lifetime_seconds Histogram 할당부터 eviction까지 KV cache 블록 수명 히스토그램. 샘플 메트릭(--kv-cache-metrics-sample로 제어)
vllm:kv_block_reuse_gap_seconds Histogram 연속 KV cache 블록 접근 사이 시간 간격 히스토그램. 가장 최근 접근만 기록(링 버퍼). 샘플 메트릭(--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_num_preemptions Histogram 요청이 선점된 횟수 히스토그램
vllm:request_params_max_tokens Histogram max_tokens 요청 파라미터 히스토그램
vllm:request_params_n Histogram n 요청 파라미터 히스토그램
vllm:request_prefill_kv_computed_tokens Histogram prefill 중 계산된 새 KV 토큰 히스토그램(캐시된 토큰 제외)
vllm:request_prefill_time_seconds Histogram 요청의 PREFILL 단계에서 소요된 시간 히스토그램
vllm:request_prompt_tokens Histogram 처리된 prefill 토큰 수
vllm:request_queue_time_seconds Histogram 요청의 WAITING 단계에서 소요된 시간 히스토그램
vllm:request_time_per_output_token_seconds Histogram 요청별 time_per_output_token_seconds 히스토그램
vllm:time_to_first_token_seconds Histogram 첫 토큰까지 시간(초) 히스토그램

Spulative Decoding 메트릭 (Speculative Decoding Metrics)

메트릭 이름 타입 설명
vllm:spec_decode_num_accepted_tokens_per_pos Counter 초안(draft) 위치별 수용된 토큰 수

NIXL KV 커넥터 메트릭 (NIXL KV Connector Metrics)

메트릭 이름 타입 설명
vllm:nixl_num_failed_notifications Counter 실패한 NIXL KV Cache 알림 수. 호환성 위해 유지; 이 실패는 vllm:nixl_num_failed_transfers에도 포함됨
vllm:nixl_num_failed_transfers Counter 실패한 NIXL KV Cache 전송 수(handshake·알림 실패 포함). 참고: KV 만료는 vllm:nixl_num_kv_expired_reqs에 별도 추적
vllm:nixl_num_kv_expired_reqs Counter KV가 만료된 요청 수. 참고: 이 메트릭은 P 인스턴스에서 추적됨
vllm:nixl_bytes_transferred Histogram NIXL KV Cache 전송당 전송 바이트 히스토그램
vllm:nixl_num_descriptors Histogram NIXL KV Cache 전송당 디스크립터 수 히스토그램
vllm:nixl_post_time_seconds Histogram NIXL KV Cache 전송의 전송 게시(post) 시간 히스토그램
vllm:nixl_xfer_time_seconds Histogram NIXL KV Cache 전송 지속 시간 히스토그램

모델 FLOPs 활용 (MFU) 성능 메트릭 (Model Flops Utilization (MFU) Performance Metrics)

이 메트릭들은 --enable-mfu-metrics로 제공됩니다:

메트릭 이름 타입 설명
vllm:estimated_flops_per_gpu_total Counter GPU당 추정 부동소수점 연산 수(Model Flops Utilization 계산용)
vllm:estimated_read_bytes_per_gpu_total Counter GPU당 메모리에서 읽은 추정 바이트 수(Model Flops Utilization 계산용)
vllm:estimated_write_bytes_per_gpu_total Counter GPU당 메모리에 쓴 추정 바이트 수(Model Flops Utilization 계산용)

폐기 정책 (Deprecation Policy)

참고: 메트릭이 버전 X.Y에서 폐기되면 버전 X.Y+1에서 숨겨지지만 --show-hidden-metrics-for-version=X.Y 이스케이프 해치로 다시 활성화할 수 있으며, 버전 X.Y+2에서 제거됩니다.

더 알아보기 (Learn more)