기록 규칙 정의하기

기록 규칙 정의하기 (Defining recording rules)

기록 규칙(recording rule)은 자주 필요하거나 계산 비용이 큰 표현식을 미리 계산해 그 결과를 새로운 타임시리즈 집합으로 저장해 두는 기능이에요. 미리 계산된 결과를 쿼리하는 것이 원래 표현식을 매번 실행하는 것보다 훨씬 빠르기 때문이죠. 특히 새로고침할 때마다 같은 표현식을 반복 쿼리해야 하는 대시보드에서 아주 유용해요. 이 문서는 규칙 파일을 어떻게 구성하고, 문법을 검사하며, 기록 규칙과 알림 규칙을 정의하는 방법을 설명해 드려요.

규칙 파일은 YAML로 작성하고 rule_files 필드로 Prometheus에 로드해요. 규칙 그룹 안의 규칙들은 같은 평가 시간으로 일정 간격마다 순차적으로 실행돼요.

출처: 문서

본문

규칙 구성하기 (Configuring rules)

Prometheus는 구성 후 정기적으로 평가될 수 있는 두 가지 유형의 규칙을 지원해요: 기록 규칙과 알림 규칙이에요. Prometheus에 규칙을 포함하려면 필요한 규칙 문장을 포함하는 파일을 만들고, Prometheus 구성의 rule_files 필드로 파일을 로드하게 하세요. 규칙 파일은 YAML을 사용해요.

규칙 파일은 Prometheus 프로세스에 SIGHUP을 보내면 런타임에 리로드할 수 있어요. 모든 규칙 파일이 잘 포맷된 경우에만 변경이 적용돼요.

규칙 문법 검사 (Syntax-checking rules)

Prometheus 서버를 시작하지 않고 규칙 파일이 문법적으로 올바른지 빠르게 확인하려면 Prometheus의 promtool 커맨드라인 유틸리티 도구를 사용할 수 있어요:

promtool check rules /path/to/example.rules.yml

promtool 바이너리는 프로젝트의 다운로드 페이지에서 제공하는 prometheus 아카이브의 일부예요.

파일이 문법적으로 유효하면 체커는 파싱된 규칙의 텍스트 표현을 표준 출력으로 출력하고 0 반환 상태로 종료해요.

문법 오류나 잘못된 입력 인자가 있으면 표준 오류에 오류 메시지를 출력하고 1 반환 상태로 종료해요.

기록 규칙 (Recording rules)

기록 규칙을 사용하면 자주 필요하거나 계산 비용이 큰 표현식을 미리 계산해 그 결과를 새로운 타임시리즈 집합으로 저장할 수 있어요. 미리 계산된 결과를 쿼리하는 것은 원래 표현식이 필요할 때마다 실행하는 것보다 종종 훨씬 빨라요. 이것은 새로고침할 때마다 같은 표현식을 반복해서 쿼리해야 하는 대시보드에 특히 유용해요.

기록 규칙과 알림 규칙은 규칙 그룹(rule group)에 존재해요. 그룹 안의 규칙은 같은 평가 시간으로 일정 간격마다 순차적으로 실행돼요. 기록 규칙의 이름은 유효한 메트릭 이름이어야 해요. 알림 규칙의 이름은 유효한 라벨 값이어야 해요.

규칙 파일의 문법은 다음과 같아요:

groups:
  [ -  ]

간단한 예제 규칙 파일:

groups:
  - name: example
    rules:
    - record: code:prometheus_http_requests_total:sum
      expr: sum by (code) (prometheus_http_requests_total)

그룹 (Group)

# 그룹의 이름. 파일 내에서 고유해야 함.
name:

# 그룹의 규칙이 평가되는 빈도.
[ interval:  | default = global.evaluation_interval ]

# 알림 규칙이 만들 수 있는 알림 수와 기록 규칙이 만들 수 있는 시리즈 수 제한. 0은 무제한.
[ limit:  | default = 0 ]

# 이 특정 그룹의 규칙 평가 타임스탬프를 지정된 기간만큼 과거로 오프셋.
[ query_offset:  | default = global.rule_query_offset ]

# 규칙의 결과를 저장하기 전에 추가하거나 덮어쓸 라벨.
# 에 정의된 라벨은 충돌이 있으면 키를 덮어씀.
labels:
  [ :  ]

rules:
  [ -  ... ]

규칙 (Rule)

기록 규칙의 문법은 다음과 같아요:

# 출력할 타임시리즈의 이름. 유효한 메트릭 이름이어야 함.
record:

# 평가할 PromQL 표현식. 각 평가 주기마다 현재 시간에 평가되고,
# 결과가 'record'가 주는 메트릭 이름으로 새로운 타임시리즈 집합으로 기록됨.
expr:

# 결과를 저장하기 전에 추가하거나 덮어쓸 라벨.
labels:
  [ :  ]

알림 규칙의 문법은 다음과 같아요:

# 알림의 이름. 유효한 라벨 값이어야 함.
alert:

# 평가할 PromQL 표현식. 각 평가 주기마다 현재 시간에 평가되고,
# 결과 타임시리즈는 모두 pending/firing 알림이 됨.
expr:

# 알림이 이 시간만큼 반환된 뒤에 발화(firing)로 간주됨.
# 아직 충분히 오래 발화되지 않은 알림은 pending으로 간주됨.
[ for:  | default = 0s ]

# 알림을 트리거한 조건이 해제된 후에도 알림이 얼마나 오래 계속 발화할지.
[ keep_firing_for:  | default = 0s ]

# 각 알림에 추가하거나 덮어쓸 라벨.
labels:
  [ :  ]

# 각 알림에 추가할 어노테이션.
annotations:
  [ :  ]

기록 규칙으로 만든 메트릭 이름 짓기에 대한 모범 사례도 참고하세요.

알림과 시리즈 제한 (Limiting alerts and series)

알림 규칙이 만드는 알림 수와 기록 규칙이 만드는 시리즈 수에 대한 제한을 그룹별로 구성할 수 있어요. 제한을 초과하면 규칙이 만든 모든 시리즈가 버려지고, 알림 규칙이라면 그 규칙에 대한 모든 알림(active, pending, inactive)도 함께 지워져요. 이 이벤트는 평가의 오류로 기록되며, 따라서 stale 마커는 작성되지 않아요.

규칙 쿼리 오프셋 (Rule query offset)

이것은 기본 메트릭이 Prometheus에 수신되고 저장됐는지 보장하는 데 유용해요. 메트릭 가용성 지연은 분산 시스템의 특성상 Prometheus가 remote write 타깃으로 실행될 때 더 발생할 가능성이 높지만, 스크래핑의 이상이나 짧은 평가 간격이 있을 때도 발생할 수 있어요.

느린 평가로 인한 실패한 규칙 평가 (Failed rule evaluations due to slow evaluation)

규칙 그룹이 다음 평가가 시작되어야 하는 시간(evaluation_interval로 정의) 전에 평가를 끝내지 못하면, 다음 평가는 건너뛰어져요. 규칙 그룹의 후속 평가는 초기 평가가 완료되거나 타임아웃될 때까지 계속 건너뛰어져요. 이때 기록 규칙이 만드는 메트릭에 공백(gap)이 생겨요. 규칙 그룹의 건너뛰어진 각 반복마다 rule_group_iterations_missed_total 메트릭이 증가해요.

더 알아보기 (Learn more)