규칙 유닛 테스트

규칙 유닛 테스트 (Unit testing for rules)

규칙을 처음 접한다면, 실제 규칙을 작성하기 전에 규칙 파일의 문법을 테스트해 보는 것이 좋아요. Prometheus에서는 유닛 테스트를 작성해 샘플 데이터 집합에 대해 규칙 파일을 시험해 볼 수 있어요. 이 문서는 규칙 유닛 테스트의 형식과 각 필드의 의미를 설명해 드려요. promtool로 유닛 테스트를 실행할 수 있어요.

테스트 파일에서 규칙의 expr은 테스트 파일의 샘플 데이터에 대해 평가되고, 반환된 결과는 규칙 테스트에 사용된 차트와 비교돼요. YAML 키와 코드는 그대로 두고 설명을 한국어로 풀어드릴게요.

출처: 문서

본문

유닛 테스트로 규칙 문법 배우기 (Learning the rules syntax with unit testing)

규칙이 처음이라면, 실제 규칙을 작성하기 전에 작성하는 동안 규칙 파일의 문법을 시험해 보아야 해요. Prometheus에서 유닛 테스트를 작성해 샘플 데이터 집합에 대해 규칙 파일을 시험해 볼 수 있어요. 테스트에서 규칙의 expr은 테스트 파일에 나열된 샘플 데이터에 대해 평가되고, 반환된 결과는 규칙 테스트에 사용된 차트와 비교돼요.

또 다른 유용한 기능은 유닛 테스트 파일에서 규칙이 쓸 수 없는 특정 PromQL 기능을 사용할 수 있는 능력이에요(규칙은 YAML로 저장되므로). 즉, 쿼리에서 실제 메트릭 이름(Counter, Histogram 등)을 사용할 수 있다는 거예요. 예를 들어 테스트의 input_series에서 no-op 함수와 함께 Counter 타입 메트릭을 사용하고, no-op 없이 실제 함수와 비교할 수 있어요. 이 기능은 계속 평가 중이에요.

유닛 테스트 규칙 형식 (Unit testing rules format)

유닛 테스트 파일은 아래 설명된 형식을 따르는 YAML 파일이에요. 이 형식은 이러한 유닛 테스트에 특화된 것이며 표준 Prometheus 규칙 형식이 아니라는 점에 유의하세요.

tsdb:
  # tsdb 경로, 선택 사항.
  [ path:     ]

evaluation_interval:

# 테스트할 규칙 목록.
group_eval_order:
  [ -  ]

# 규칙 그룹과 그 규칙 목록.
rule_files:
  -  ...

# 다음 섹션은 규칙을 평가하는 데 사용되는 프레임워크를 정의.
# 데이터의 쿼리와 규칙의 확장은 이 파일의 범위 밖.

# 하나 이상의 입력 시리즈 목록.
input_series:
  - series:
      [ <series> | ... ]
    # 값은 다음 형식을 사용하는 목록/배열이어야 함
    #
    #   0000000000 1        # 시작 후 10m
    #   0000123456 1.5      # 시작 후 12.3456s
    #
    values:  ...
  [ - <series> ]

# 실행할 하나 이상의 테스트 목록.
tests:
  # 평가할 하나 이상의 표현식 목록.
  - expr:  ...
    # 표현식의 시간 범위.
    [ eval_time:  ]
    # 표현식의 기대 출력.
    [ expected:  ]
    [ eval_interval:  ]

다음 발췌:

series: 'http_requests_total{job="api-server", instance="localhost:9090", handler="/api/v2/query"}'
values: '0 0
    60 100
    120 200
    180 300
    240 400
    300 500
    360 600
    420 700
    480 800'

는 시작 시간에서 시작해 values 필드의 시간(시작 후 초)에 따른 메트릭 이름 값을 가진 입력 시리즈를 보여 줘요.

규칙 평가하기 (Evaluating the rules)

규칙 파일의 expr 표현식은 각 평가 간격에서 평가돼요. 시간에 따른 평가 출력은 테스트의 expected 차트와 비교되는 차트를 형성해요.

입력 시리즈 (Input series)

input_series는 규칙 평가에 필요한 입력이거나, 여러분이 단언(assert)하고 싶은 샘플 시리즈를 정의할 수 있게 해 줘요. values 필드에서 타임스탬프 값은 평가 시작부터의 초 단위 오프셋으로 표현된다는 점에 유의하세요.

평가 간격 (Evaluation interval)

평가 간격은 파일 최상위에 설정돼요. 테스트에 eval_interval이 있으면 최상위 evaluation_interval을 재정의해요.

테스트의 기대 출력 (Expected output of the test)

eval_time

eval_time은 규칙의 평가 시간이에요. 규칙 표현식이 평가되는 시점을 지정해요. float64 초로 설정돼요. 소수 값도 사용할 수 있어요.

expected

expected는 eval_time에서 평가되는 표현식의 기대 값이에요. 시리즈 또는 [...] 대괄호로 표시되는 여러 시리즈, 또는 스칼라 값(float64)일 수 있어요.

그룹 평가 순서 (Group eval order)

group_eval_order는 규칙 그룹이 평가되는 순서를 지정해요. 한 규칙 그룹이 다른 규칙 그룹의 출력에 의존할 수 있는 경우를 처리하기 위한 것이에요. 순서는 오름차순(낮은 것에서 높은 것으로)이에요.

제한사항 (Limitations)

input_series는 테스트 파일에서 시리즈를 정의하는 방법을 제공해요. 하지만 규칙 엔진은 이러한 테스트 파일을 수집(ingest)할 방법이 없으므로, 규칙을 평가할 때 그 필드를 무시해요.

eval_time은 0보다 크거나 같아야 해요.

네이티브 히스토그램을 다룰 때 series 이름은 (이전처럼) 메트릭 이름에서 오지만, 전체 시리즈 객체는 series 필드에 설명돼요.

도구 (Tooling)

promtool에는 유닛 테스트를 실행하는 하위 명령이 있어요: promtool test rules.

예제 테스트 파일 (Example test file)

tsdb:
  path: /path/to/tsdb
evaluation_interval: 1m

group_eval_order:
  - group_1

rule_files:
  - rules.yml

input_series:
  - series: 'http_requests_total{job="api-server", instance="localhost:9090", handler="/api/v2/query"}'
    values: '0 0
      60 100
      120 200
      180 300
      240 400
      300 500
      360 600
      420 700
      480 800'

tests:
  - expr: sum(rate(http_requests_total[5m]))
    eval_time: 5m
    eval_interval: 1m
    expected: 1

이 예제에서 TSDB 경로가 설정되고, 평가 간격 1m, group_1을 포함하는 그룹 평가 순서, rules.yml을 포함하는 규칙 파일이 있어요. 입력 시리즈는 매분 100씩 증가하는 http_requests_total이에요. 테스트는 sum(rate(http_requests_total[5m]))을 평가하고 출력이 1이기를 기대해요.

더 알아보기 (Learn more)