기록 규칙

기록 규칙 (Recording rules)

기록 규칙(recording rule)은 자주 쓰이거나 계산 비용이 큰 표현식을 미리 계산해 새 타임시리즈로 저장해 두는 기능이에요. 이 문서는 기록 규칙에 일관된 이름 짓기 체계와 집계(aggregation) 규칙을 적용하는 모범 사례를 다뤄요. 이름이 일관되면 규칙의 의미를 한눈에 해석하기 쉬워지고, 틀리거나 의미 없는 계산이 눈에 띄어 실수를 피할 수 있어요.

핵심은 level:metric:operations 형태의 이름 짓기와, 비율(ratio)을 집계할 때 분자와 분모를 따로 집계한 뒤 나누는 원칙, 그리고 without 절의 올바른 사용이에요. 예제와 함께 차근차근 살펴볼게요.

출처: 문서

본문

기록 규칙에 대한 일관된 이름 짓기 체계는 규칙의 의미를 한눈에 해석하기 쉽게 만들어 줘요. 또한 잘못되었거나 의미 없는 계산이 눈에 띄게 함으로써 실수를 피하게 해 줘요.

이 페이지는 기록 규칙의 적절한 명명 규칙과 집계를 문서화해요.

이름 짓기 (Naming)

  • 기록 규칙은 일반적으로 level:metric:operations 형태여야 해요.

  • level은 규칙 출력의 집계 수준과 라벨을 나타내요.

  • metric은 메트릭 이름이며, rate()나 irate()를 사용할 때 카운터에서 _total을 떼는 것 외에는 변경되지 않은 채로 있어야 해요.

  • operations는 메트릭에 적용된 연산 목록으로, 가장 새로운 연산이 먼저 와요.

메트릭 이름을 변경하지 않고 유지하면 메트릭이 무엇인지 쉽게 알 수 있고 코드베이스에서 쉽게 찾을 수 있어요.

연산을 깔끔하게 유지하기 위해, sum()처럼 다른 연산이 있으면 _sum은 생략돼요. 결합 법칙이 성립하는 연산은 병합될 수 있어요(예: min_min은 min과 같아요).

사용할 명백한 연산이 없으면 sum을 사용하세요. 나눗셈으로 비율을 취할 때는 _per_로 메트릭을 구분하고 연산을 ratio라고 부르세요.

집계 (Aggregation)

비율을 집계할 때는 분자와 분모를 따로 집계한 다음 나누세요.

비율의 평균이나 평균의 평균을 취하지 마세요. 통계적으로 유효하지 않기 때문이에요.

Summary의 _count와 _sum을 집계해 나눠 평균 관측 크기를 계산할 때, 그것을 비율로 취급하는 것은 다루기 어려워요. 대신 _count나 _sum 접미사 없이 메트릭 이름을 유지하고 연산의 rate를 mean으로 바꾸세요. 이것은 그 시간 기간 동안의 평균 관측 크기를 나타내요.

집계해버릴 라벨과 함께 항상 without 절을 지정하세요. 이는 job 같은 다른 모든 라벨을 보존하기 위한 것이며, 충돌을 피하고 더 유용한 메트릭과 알림을 얻게 해 줘요.

예제 (Examples)

두 벡터 사이에 들여쓰기 되지 않은 연산자를 자체 줄에 두는 들여쓰기 스타일에 주의하세요. 이 스타일을 YAML에서 가능하게 하기 위해 들여쓰기 표시가 있는 블록 인용(예: |2)이 사용돼요.

path 라벨이 있는 초당 요청 수를 집계하기:

- record: instance_path:requests:rate5m
  expr: rate(requests_total{job="myjob"}[5m])

- record: path:requests:rate5m
  expr: sum without (instance)(instance_path:requests:rate5m{job="myjob"})

요청 실패 비율을 계산하고 잡 수준 실패 비율로 집계하기:

- record: instance_path:request_failures:rate5m
  expr: rate(request_failures_total{job="myjob"}[5m])

- record: instance_path:request_failures_per_requests:ratio_rate5m
  expr: |2
      instance_path:request_failures:rate5m{job="myjob"}
    /
      instance_path:requests:rate5m{job="myjob"}

# 분자와 분모를 집계한 다음, 나눠서 경로 수준 비율을 얻는다.
- record: path:request_failures_per_requests:ratio_rate5m
  expr: |2
      sum without (instance)(instance_path:request_failures:rate5m{job="myjob"})
    /
      sum without (instance)(instance_path:requests:rate5m{job="myjob"})

# 계측이나 인스턴스 구분에서 남은 라벨이 없으므로 'job'을 수준으로 사용한다.
- record: job:request_failures_per_requests:ratio_rate5m
  expr: |2
      sum without (instance, path)(instance_path:request_failures:rate5m{job="myjob"})
    /
      sum without (instance, path)(instance_path:requests:rate5m{job="myjob"})

Summary에서 시간 기간 동안의 평균 지연시간 계산하기:

- record: instance_path:request_latency_seconds_count:rate5m
  expr: rate(request_latency_seconds_count{job="myjob"}[5m])

- record: instance_path:request_latency_seconds_sum:rate5m
  expr: rate(request_latency_seconds_sum{job="myjob"}[5m])

- record: instance_path:request_latency_seconds:mean5m
  expr: |2
      instance_path:request_latency_seconds_sum:rate5m{job="myjob"}
    /
      instance_path:request_latency_seconds_count:rate5m{job="myjob"}

# 분자와 분모를 집계한 다음 나눈다.
- record: path:request_latency_seconds:mean5m
  expr: |2
      sum without (instance)(instance_path:request_latency_seconds_sum:rate5m{job="myjob"})
    /
      sum without (instance)(instance_path:request_latency_seconds_count:rate5m{job="myjob"})

인스턴스와 경로에 걸친 평균 쿼리 속도를 계산하는 것은 avg() 함수로 해요:

- record: job:request_latency_seconds_count:avg_rate5m
  expr: avg without (instance, path)(instance_path:request_latency_seconds_count:rate5m{job="myjob"})

집계할 때 without 절의 라벨이 입력 메트릭 이름과 비교해 출력 메트릭 이름의 수준에서 제거된다는 점에 주목하세요. 집계가 없으면 수준은 항상 일치해요. 그렇지 않다면 규칙에서 실수가 있기 쉬워요.

더 알아보기 (Learn more)