Prometheus 템플릿 변수

Prometheus 템플릿 변수 (Template variables)

템플릿 변수는 하드코딩된 값(서버 이름, 네임스페이스, job 라벨 등)을 선택 가능한 변수로 바꿔 동적이고 재사용 가능한 대시보드를 만들 수 있게 해줘요. Grafana는 이 변수를 대시보드 상단의 드롭다운 메뉴로 표시해 뷰어가 쿼리를 편집하지 않고도 표시되는 데이터를 바꿀 수 있게 해요.

출처: Prometheus template variables

본문

템플릿과 템플릿 변수 소개는 Templating과 Add and manage variables를 참고하세요.

쿼리 변수 유형

쿼리 변수는 Prometheus를 질의해 드롭다운 값을 채워요. 쿼리 변수를 만들 때 Prometheus 데이터 소스를 선택하고 쿼리 유형을 골라요.

쿼리 유형 필수 입력 설명 예시
Label names metric (선택) 모든 라벨 이름 반환, 선택적으로 metric 정규식으로 필터 Metric: http_requests_total → job, instance, method, status 등 반환
Label values label (필수), metric (선택) 특정 라벨의 값 반환, 선택적으로 metric으로 필터 Label: job, Metric: http_requests_total → api-server, web, worker 반환
Metrics metric (선택) 지정된 정규식과 일치하는 메트릭 이름 반환 Metric: node_.* → node_cpu_seconds_total, node_memory_MemFree_bytes 등 반환
Query result query (필수) PromQL 쿼리를 실행해 결과를 변수 값으로 반환 query_result(up{job="prometheus"})
Series query metric, label 또는 둘 다 지정된 metric 및/또는 label 셀렉터와 일치하는 시계열 반환 Metric: http_requests_total, Label: job="api"
Classic query 쿼리 문자열 비권장. label_values(metric, label) 같은 함수를 사용하는 레거시 문법 label_values(http_requests_total, job)

메트릭 이름, 라벨 이름, 라벨 값에 대한 자세한 내용은 Prometheus data model을 참고하세요.

쿼리 유형 예시

Label values (모든 job으로 드롭다운 채우기):

  1. Type: Query로 새 변수를 만들어요.
  2. Prometheus 데이터 소스를 선택해요.
  3. Query type을 Label values로 설정해요.
  4. Label을 job으로 설정해요.
  5. Metric은 전체 지표에 걸쳐 질의하도록 비워둬요.

이제 변수 드롭다운에 모든 고유 job 라벨 값이 표시돼요.

Label values (metric으로 필터):

Label을 instance로, Metric을 node_cpu_seconds_total로 설정하면 CPU 지표를 보고하는 인스턴스만 표시해요.

Metrics (패턴으로 사용 가능한 지표 찾기):

Query type을 Metrics로 설정하고 Metric 필드에 http_.*_total을 입력하면 모든 HTTP 카운터 지표로 드롭다운을 채워요.

Query result (동적 top-N 필터링):

Query type을 Query result로 설정하고 다음을 입력해요.

query_result(topk(5, sum(rate(http_requests_total[$__range])) by (instance)))

Regex를 /\"([^\"]+)\"/로 설정해 결과에서 인스턴스 값을 추출해요. Refresh를 On time range change로 설정해 대시보드 시간 범위를 바꾸면 top 5 인스턴스가 업데이트되게 해요.

쿼리 옵션

옵션 설명
Data source 질의할 Prometheus 데이터 소스
Regex 반환된 값의 일부를 추출하는 선택 정규식. 캡처 그룹 사용. 예: /.*instance=\"([^\"]+)\".*/는 시리즈 문자열에서 instance 라벨 값 추출
Sort 드롭다운 값 정렬 순서: Disabled, Alphabetical (asc), Alphabetical (desc), Numerical (asc), Numerical (desc), Alphabetical (case-insensitive, asc), Alphabetical (case-insensitive, desc)
Refresh 값 업데이트 시점: On dashboard load 또는 On time range change. $__range에 의존하는 변수에는 On time range change 사용

선택 옵션

  • Multi-value: 여러 값을 동시에 선택할 수 있어요. Grafana는 정규식 일치를 위해 이들을 파이프(|)로 연결해요.
  • Include All option: 모든 값을 선택하는 "All" 옵션을 추가해요. multi-value와 결합하면 value1|value2|value3 같은 정규식을 생성해요.

참고: Multi-value 또는 Include All이 활성화되면 변수 값이 정규식 패턴이 되므로 쿼리에서 =(정확히 일치) 대신 =~(정규식 일치)를 사용하세요.

Multi-value 예시:

rate(http_requests_total{job=~"$job"}[$__rate_interval])

간격 및 범위 변수 사용

쿼리 변수 정의에서 전역 내장 변수를 사용할 수 있어요.

변수 설명
$__interval 시간 범위와 패널 너비를 기반으로 계산된 간격
$__interval_ms $__interval을 밀리초로 표시
$__range 현재 대시보드 시간 범위의 기간(예: 1h)
$__range_s 초 단위 기간
$__range_ms 밀리초 단위 기간

자세한 내용은 Global built-in variables를 참고하세요.

label_values 함수(Classic 쿼리 유형)는 이러한 변수를 지원하지 않아요. 대신 query_result()와 함께 Query result 유형을 사용해요.

query_result(max_over_time(up{job="$job"}[${__range_s}s]) == 1)

변수의 Refresh를 On time range change로 설정해 시간 범위가 바뀌면 값을 업데이트해요.

$__rate_interval 사용

$__rate_interval은 rate()와 increase()와 함께 사용하도록 설계된 Grafana 특정 변수예요. 최소 4개의 스크래이프 샘플을 포착할 만큼 큰 범위 창을 보장해 결과의 공백이나 부정확성을 방지해요.

항상 고정 간격이나 $__interval 대신 $__rate_interval을 사용하세요:

rate(http_requests_total[$__rate_interval])

아니면:

rate(http_requests_total[5m])       # breaks at different zoom levels
rate(http_requests_total[$__interval])  # can be too small for rate()

$__rate_interval 계산 방식

max($__interval + scrape_interval, 4 * scrape_interval)

여기서 scrape_interval은:

  1. 설정된 경우 쿼리별 Min step 설정
  2. 그렇지 않으면 데이터 소스의 Scrape interval 설정(데이터 소스 구성의 Interval behavior 아래)

패널 레벨 min interval은 해상도 설정의 영향을 받으며 이 계산에는 포함되지 않아요.

$__rate_interval 올바르게 구성

$__rate_interval이 안정적인 결과를 내려면 스크래이프 간격이 실제 Prometheus 스크래이프 구성과 일치해야 해요.

  1. Prometheus 데이터 소스 구성을 열어요.
  2. Interval behavior 아래에서 Scrape interval을 Prometheus 구성 파일의 scrape_interval과 일치하도록 설정해요(예: 30s 또는 1m).
  3. 다른 대상이 다른 스크래이프 간격을 가지면 데이터 소스 스크래이프 간격을 사용 중인 가장 긴 간격으로 설정하거나, 쿼리별 Min step으로 특정 패널에서 재정의해요.

일반적인 함정

  • 누락되거나 잘못된 스크래이프 간격 설정: 데이터 소스 스크래이프 간격을 기본 15s로 두지만 실제 Prometheus 스크래이프 간격이 60s라면 $__rate_interval이 너무 작은 창을 계산해요. 이로 인해 창에 데이터 포인트가 충분하지 않아 rate()가 데이터를 반환하지 못해요.
  • 편집 모드와 대시보드의 값 차이: 쿼리를 편집할 때 패널이 전체 너비로 표시돼요. 대시보드에서는 패널이 더 좁아 $__interval이 커지고 따라서 $__rate_interval도 커져요. 편집 모드에서 작동하는 쿼리가 대시보드에서는 다른 결과(또는 공백)를 낼 수 있어요.
  • LBAC 활성화 데이터 소스: Label-Based Access Control(LBAC)을 사용하는 데이터 소스는 부모 데이터 소스의 스크래이프 간격 설정을 상속하지 못할 수 있어요. 각 쿼리 패널에서 Min step을 명시적으로 설정해 올바른 $__rate_interval 계산을 보장하세요.
  • 고정 간격의 기록 규칙: 기록 규칙 쿼리에서 $__rate_interval을 사용하면 간격이 평가 컨텍스트에 의존해요. 기록 규칙에서는 $__rate_interval 대신 고정 간격(예: [5m])을 사용하세요.

$__rate_interval 문제 해결은 Rate interval returns no data or incorrect values를 참고하세요. 추가 배경은 $__rate_interval for Prometheus rate queries that just work 블로그를 참고하세요.

변수 문법

Prometheus 데이터 소스는 세 가지 변수 문법을 지원해요.

문법 예시 용도
$varname rate(http_requests_total{job=~"$job"}[$__rate_interval]) 단순하고 읽기 쉬움. 단어 중간에 사용 불가
${varname} rate(http_requests_total{job=~"${job}"}[$__rate_interval]) 변수가 다른 텍스트와 인접할 때 사용(예: ${env}-cluster)
[[varname]] rate(http_requests_total{job=~"[[job]]"}[$__rate_interval]) 레거시 문법. 역호환용으로 지원

참고: Multi-value 또는 Include All이 활성화되면 변수 값이 정규식 패턴(예: value1|value2)이 돼요. 라벨 매처에서 = 대신 =~를 사용하세요.

필터 변수

Prometheus는 Filters 변수 유형(이전에는 "ad hoc filters"라고 불림)을 지원해요. 대시보드 뷰어가 쿼리를 편집하지 않고 라벨 필터를 동적으로 추가할 수 있게 해줘요.

참고: Filter and Group by 기능은 Prometheus와 Loki 데이터 소스에 그룹화 지원을 추가해 Filters 변수를 확장해요. 자세한 내용은 Filter and Group by 참고.

Filters 변수를 설정하려면:

  1. Type: Filters로 새 변수를 만들어요.
  2. Prometheus 데이터 소스를 선택해요.
  3. 대시보드를 저장해요.

변수를 추가한 후 대시보드 상단에 필터 막대가 나타나요. 뷰어는 라벨, 연산자(=, !=, =~, !~), 값을 선택해 필터를 추가할 수 있어요. Grafana는 이 필터를 대시보드의 모든 Prometheus 쿼리에 자동으로 적용해요.

예시: 뷰어가 namespace = production 필터를 추가하면 대시보드의 모든 쿼리에 쿼리 수정 없이 {namespace="production"}이 포함돼요.

참고: 필터는 선택한 데이터 소스를 사용하는 모든 쿼리에 적용돼요. 특정 패널에만 선택적으로 적용할 수 없어요.

관련 리소스

더 알아보기 (Learn more)