모니터링¶

목표: 배포한 서빙 스택의 메트릭과 트레이스를 수집하고, 수집한 메트릭과 트레이스를 올바르게 해석합니다.

신호	출처	수집 및 조회
메트릭	modelserver(P/D role별), llm-d Endpoint Picker(EPP), 게이트웨이	VictoriaMetrics Operator(기본) 또는 Prometheus Operator의 모니터링 커스텀 리소스(CR) 및 Grafana
트레이스	EPP, 라우팅 사이드카, vLLM	OpenTelemetry(OTel) collector 및 트레이스 백엔드

메트릭 수집 대상¶

이 절은 차트의 모니터링 CR이 수집하는 대상과 대상별 인증 방식을 설명합니다.

모니터링 CR은 modelserver 메트릭을 P/D role별로 수집합니다. 셀렉터는 llm-d.ai/role: decode|prefill 레이블입니다. 차트는 prefill과 decode에 VMPodScrape(Prometheus Operator에서는 PodMonitor)를 하나씩 만들므로 job 레이블(<namespace>/<name>)이 prefill과 decode에서 다릅니다.
EPP의 /metrics(포트 9090)에는 bearer 토큰이 필요합니다. modelserver의 /metrics에는 인증이 없습니다.
모니터링 CR은 게이트웨이 메트릭도 수집합니다. 기본 Istio 데이터 플레인에서는 모니터링 CR이 Envoy 메트릭(포트 15090, /stats/prometheus)을 수집합니다. agentgateway에서는 같은 CR이 포트 15020을 수집합니다.
LMCache 메트릭은 별도의 수집 대상이 아닙니다. modelserver가 LMCache 메트릭을 자신의 /metrics에 함께 노출합니다.

기본값인 VictoriaMetrics Operator에서는 다음 values로 모니터링을 활성화하세요. monitoring.scraper.serviceAccount.{name,namespace}는 메트릭을 수집하는 VictoriaMetrics 에이전트인 VMAgent의 ServiceAccount를 가리킵니다. monitoring.scraper.serviceAccount를 지정하지 않으면 렌더링에 실패합니다.

helm upgrade <release-name> ./coding-assistant-stack -n <ns> \
  --set monitoring.enabled=true \
  --set monitoring.scraper.serviceAccount.name=<vmagent-sa> \
  --set monitoring.scraper.serviceAccount.namespace=<vmagent-sa-namespace> \
  <values given at install>

차트는 EPP의 /metrics를 읽는 권한을 VMAgent의 ServiceAccount에 바인딩합니다. 차트는 bearer 토큰 Secret을 생성하지 않습니다. VMAgent는 자신의 Pod에 마운트된 projected 토큰으로 인증합니다. kubelet이 projected 토큰을 갱신합니다.

차트에 포함된 examples/observability.yaml은 메트릭 수집과 트레이스 수집을 모두 활성화합니다. 따라서 examples/observability.yaml로 설치하려면 클러스터에 OTel collector도 있어야 합니다. examples/observability.yaml의 <...> 부분을 채운 뒤 파일을 -f로 전달하세요. 메트릭만 수집하려면 파일에서 tracing과 llm-d-router-gateway 블록을 제거하세요.

Prometheus Operator를 사용하는 클러스터에서는 monitoring.backend=prometheus를 지정하세요. 이때 차트는 PodMonitor와 ServiceMonitor를 생성합니다. EPP의 /metrics용 ServiceAccount와 토큰 Secret도 차트가 생성하므로 monitoring.scraper.serviceAccount는 필요하지 않습니다. monitoring.labels에는 사용하는 Prometheus의 셀렉터가 요구하는 레이블을 지정하세요(예: release: <prometheus-release>). 이 옵션은 Target Configuration에서 Unverified입니다.

prefix 캐시 hit 메트릭¶

이 스택의 캐시 계층은 high-bandwidth memory(HBM)를 쓰는 tier 1과 Rebellions Direct Storage(RDS)를 쓰는 tier 2입니다. 이 절은 두 계층을 구분하는 메트릭만 다룹니다. 전체 메트릭 목록은 vLLM Production Metrics를 참고하세요.

확인할 항목	메트릭	해석 방법
Automatic Prefix Caching의 tier 1(HBM) 재사용	`vllm:prefix_cache_hits_total`	HBM에서 재사용한 프롬프트 토큰 수를 집계합니다. sub-block 재사용분도 포함합니다
HBM 밖에서 가져온 key-value(KV) 캐시(P/D 전송, tier 2 재사용)	`vllm:external_prefix_cache_hits_total`	KV connector가 KV를 가져온 토큰 수를 집계합니다. 레퍼런스 구성에서 decode는 KV connector로 NIXL만 등록하므로 decode의 `vllm:external_prefix_cache_hits_total` 값은 모두 P/D 전송분입니다. LMCache가 RDS에서 재사용한 KV는 prefill의 `vllm:external_prefix_cache_hits_total` 값으로 확인합니다
출처별 프롬프트 토큰 수	`vllm:prompt_tokens_by_source_total`	`source` 레이블이 `local_cache_hit`(HBM prefix 캐시), `external_kv_transfer`(KV connector), `local_compute`로 나뉩니다. 세 `source` 값의 토큰 수를 더하면 프롬프트 토큰 수가 됩니다
RDS 읽기 및 쓰기	`lmcache_rbln_rds_io_total`	읽기와 쓰기를 `operation` 레이블(`read`, `write`)로 나누어 확인합니다. `lmcache_rbln_rds_io_total`이 없으면 RDS 백엔드가 생성되지 않은 것입니다

메트릭 값은 다음 기준으로 읽으세요.

tier 1 hit 비율: vllm:prefix_cache_hits_total을 vllm:prefix_cache_queries_total로 나눠 구합니다. vllm:prefix_cache_queries_total은 조회한 프롬프트 토큰 수입니다.
DP rank의 합산: DP로 실행한 Pod는 rank마다 다른 포트로 vLLM 카운터를 노출합니다. decode는 8200번부터 rank마다 포트 하나를 씁니다. Pod 전체 값은 모든 rank의 값을 더해 구하세요.
LMCache의 worker별 값: LMCache는 PP worker(worker_id)마다 메트릭을 따로 기록합니다. 모두 더하면 PP 병렬도만큼 값이 커지므로 worker 하나의 값만 읽으세요.
lmcache:num_hit_tokens_total: LMCache가 동작하지 않아도 0으로 노출됩니다. 재사용 판단에는 쓰지 말고 진단에만 사용하세요.

sub-block 재사용만 확인하려면 --block-size보다 짧은 프롬프트를 두 번 보내세요. 그다음 vllm:prompt_tokens_by_source_total에서 source가 local_cache_hit인 값의 증가분을 확인하세요.

Warning

응답의 prompt_tokens_details.cached_tokens로 계층별 재사용을 판단하지 마세요. 차트가 설정하는 --enable-prompt-tokens-details를 사용하면 cached_tokens는 요청 전체의 재사용 토큰 수를 보고합니다. cached_tokens는 재사용 토큰을 어느 계층이나 경로에서 가져왔는지 알려 주지 않습니다.

KV가 P/D 전송으로 decode에 도착했는지는 decode 로그의 External prefix cache hit rate: <n>% 줄로 확인하세요. External prefix cache hit rate가 0%보다 크면 KV가 decode 엔진 밖, 즉 P/D 전송으로 도착했다는 뜻입니다. 같은 프롬프트를 다시 보냈을 때 첫 토큰까지의 시간(TTFT)이 줄어도 캐시 재사용의 증거는 아닙니다. prefix-based-pd-decider는 decode에 이미 캐시된 요청을 prefill 없이 decode로 보내므로, TTFT 감소는 prefill을 건너뛴 결과일 수 있습니다.

NPU 디바이스 메트릭¶

NPU 디바이스 계층 메트릭(온도, 사용률)은 RBLN 메트릭 익스포터가 제공합니다. RBLN 메트릭 익스포터는 서빙 스택 차트에 포함되지 않는 SDK 구성 요소입니다.

엔진 단계별 계측¶

VLLM_RBLN_METRICS=True로 설정하면 RBLN vLLM 워커가 step 지연 시간을 device, host, collective, prepare 단계로 나눠 수집합니다. 엔진은 종료할 때 성능 리포트를 출력합니다(설정 가이드).

차트에는 VLLM_RBLN_METRICS를 위한 전용 values 키가 없습니다. 다음 키로 지정하세요.

prefill과 decode에 같은 값을 지정할 때: modelserver.serveEnv
prefill과 decode에 다른 값을 지정할 때: modelserver.extraServeEnv

트레이스¶

EPP, 라우팅 사이드카, vLLM은 같은 OTel collector로 span을 보냅니다. 그래서 요청 하나를 EPP, 라우팅 사이드카, vLLM이 차례로 처리하는 과정이 하나의 트레이스로 표시됩니다. 트레이스 수집은 차트 기본값에서 비활성 상태입니다(tracing.enabled: false).

트레이스 수집을 활성화하려면 tracing.enabled와 EPP 서브차트의 llm-d-router-gateway.router.tracing.enabled를 같은 값으로 설정하세요. 두 키의 값이 다르면 렌더링에 실패합니다.

helm upgrade <release-name> ./coding-assistant-stack -n <ns> \
  --set tracing.enabled=true \
  --set llm-d-router-gateway.router.tracing.enabled=true \
  <values given at install>

OTel collector 주소는 다음 두 키에 모두 지정하세요. 트레이스 수집을 활성화한 상태에서 두 주소가 다르면 렌더링에 실패합니다. 차트는 두 주소를 문자열로 비교하므로 두 키에 같은 주소를 같은 형식으로 적으세요.

키	설명
`tracing.collector.{name,namespace,port}`	collector의 Service 이름, 네임스페이스, 포트를 지정합니다. vLLM과 라우팅 사이드카는 `tracing.collector`로 collector를 찾습니다. agentgateway에서는 게이트웨이 계층도 `tracing.collector`를 사용합니다
`llm-d-router-gateway.router.tracing.otelExporterEndpoint`	EPP 서브차트가 사용할 collector 주소를 지정합니다

Note

tracing.enabled는 vLLM, EPP, 라우팅 사이드카의 span을 활성화합니다. 기본 Istio 데이터 플레인에서는 Istio Telemetry API로 게이트웨이 span을 별도로 구성하세요. Configure tracing with Telemetry API를 참고하세요. gateway.gatewayClassName이 agentgateway이고 트레이스 수집을 활성화하면 차트가 게이트웨이 계층용 AgentgatewayPolicy를 생성합니다. agentgateway 전용 트레이스 설정(randomSampling, serviceName)은 gateway.agentgateway.tracingPolicy로 지정합니다.