템플릿 주석과 라벨

템플릿 주석과 라벨 (Template annotations and labels)

Grafana Alerting에서는 템플릿을 사용해 알림 규칙 쿼리의 동적 데이터를 포함해 알림 및 알림 메시지를 사용자 정의할 수 있어요. 이 문서는 알림 규칙 정의에서 주석(annotation)과 라벨(label)을 템플릿화해 쿼리 데이터의 추가 정보를 알림에 포함하는 방법을 설명합니다.

출처: Template annotations and labels

본문

Grafana Alerting에서 알림 메시지를 템플릿화하는 두 가지 방법이 있어요.

Template annotations and labels: 알림 규칙 정의에서 주석과 라벨을 템플릿화해 쿼리 데이터의 추가 정보를 알림에 포함하고, 쿼리 결과에 기반한 의미 있는 세부 정보를 추가해요.
Template notifications: 알림 내용과 모양을 제어하도록 알림을 템플릿화할 수 있어요.

템플릿화 동작 방식 (How templating works)

두 유형의 템플릿 모두 Go 템플릿 시스템으로 작성돼요. 다만 알림 템플릿에서 사용되는 변수와 함수는 주석·라벨 템플릿에서 사용되는 것과 다르다는 점을 이해하는 것이 중요해요.

Template annotations and labels: 개별 알림 인스턴스에 추가 정보를 더해요. $labels와 $values 같은 템플릿 변수는 개별 알림 인스턴스의 알림 쿼리 데이터를 나타내요.
Template notifications: 알림 그룹에 대한 알림 콘텐츠를 포맷해요. .Alerts 같은 변수는 알림에 있는 모든 firing·resolved 알림을 포함해요.

다이어그램의 자세한 설명은 Templates Introduction 문서를 참고하세요.

템플릿 주석 (Template annotations)

주석은 알림 인스턴스에 추가 정보를 더하며, 알림을 식별하고 대응자가 문제를 해결하는 방법을 안내하는 데 자주 사용돼요. 주석은 알림 규칙에 정의된 키-값 쌍이에요. 알림이 발생할 때 평가되는 일반 텍스트 또는 템플릿 코드를 포함할 수 있어요.

Grafana에는 description, summary, runbook_url 같은 여러 선택 주석이 포함되어 있고, 알림 규칙에서 편집할 수 있어요. 커스텀 주석도 만들 수 있어요. 예를 들어 알림을 트리거한 시스템의 위치를 보고하는 location이라는 새 주석을 만들 수 있어요.

다음은 왜 알림이 트리거됐는지 일반 텍스트로 설명하는 summary 주석 예시예요.

CPU usage has exceeded 80% for the last 5 minutes.

하지만 주석에서 동적 쿼리 값을 표시하려면 템플릿 코드를 사용해야 해요. 일반적인 사용 사례는 다음과 같아요.

알림을 트리거한 쿼리 값 표시.
환경, 인스턴스, 지역 같은 알림을 식별하는 라벨 정보 강조.
쿼리 값에 기반한 특정 지침 제공.
쿼리 라벨에 따라 runbook 링크 사용자 정의.
쿼리 라벨에 기반한 연락처 정보 포함.

예를 들어 앞의 예시를 템플릿화해 알림을 트리거한 특정 인스턴스와 CPU 값을 표시할 수 있어요.

CPU usage for {{ $labels.instance }} has exceeded 80% ({{ $values.A.Value }}) for the last 5 minutes.

또는 index 함수를 사용해 쿼리 값을 출력할 수도 있어요.

CPU usage for {{ index $labels "instance" }} has exceeded 80% ({{ index $values "A" }}) for the last 5 minutes.

주석 결과는 다음과 같아요.

CPU usage for Instance 1 has exceeded 80% (81.2345) for the last 5 minutes.

주석을 템플릿화하는 방법:

Alerts & IRM > Alert rules로 이동해 알림 규칙을 만들거나 편집해요.
Configure notification message 섹션으로 스크롤해요.
해당 주석 필드(summary, description, runbook_url, custom)에 템플릿을 붙여 넣어요.

주석 템플릿 미리보기 (Preview annotation templates):

알림 규칙을 만들거나 편집할 때 주석을 템플릿화할 수 있어요. 주석 템플릿을 테스트·미리보는 두 가지 일반적인 방법이 있어요.

알림을 트리거하고 Grafana UI에서 알림 인스턴스 상태를 보면 알림 인스턴스의 모든 주석이 표시돼요.
모든 주석을 표시하는 알림 템플릿을 사용한 뒤, 알림 인스턴스로 알림 템플릿을 미리봐요.

템플릿 라벨 (Template labels)

알림 인스턴스의 라벨 집합은 다른 모든 알림 인스턴스 중에서 그 알림을 고유하게 식별하는 데 사용돼요. 라벨은 알림이 어떻게 라우팅·관리되는지 결정하므로, 그 설계가 알림 시스템의 효과에 핵심이에요.

라벨은 알림 규칙 쿼리에서 반환될 수 있어요. 예를 들어 Kubernetes Prometheus 쿼리의 pod 라벨이 그래요. 알림 처리에 추가 정보를 제공하기 위해 알림 규칙에서 추가 라벨을 정의할 수도 있어요. 주석과 마찬가지로 라벨은 키-값 쌍이며 알림 발생 시 평가되는 일반 텍스트 또는 템플릿 코드를 포함할 수 있어요.

쿼리가 반환하는 라벨이 부족할 때 라벨을 템플릿화해요. 예를 들어:

쿼리 값에 기반한 새 라벨이 알림 하위 집합을 다르게 그룹화해 알림이 전송되는 방식을 변경할 수 있어요.
쿼리 값에 기반한 새 라벨을 알림 정책에서 사용해 알림 연락 지점을 변경할 수 있어요.

다음은 쿼리 값에 기반해 severity 라벨을 템플릿화하는 예시예요.

{{ if (gt $values.A.Value 90.0) -}}
critical
{{ else if (gt $values.A.Value 80.0) -}}
high
{{ else if (gt $values.A.Value 60.0) -}}
medium
{{ else -}}
low
{{- end }}

이 예시에서 severity 라벨의 값은 쿼리 값으로 결정되며, 가능한 옵션은 critical, high, medium, low예요. 그런 다음 severity 라벨을 사용해 알림을 변경할 수 있어요. 예를 들어 critical 알림은 즉시 보내거나 low 알림은 특정 팀으로 라우팅해 추가 검토하게 할 수 있어요.

참고: 알림 인스턴스는 그 라벨 집합으로 고유하게 식별돼요. 라벨에 쿼리 값을 표시하는 것은 피하세요. 각각의 고유한 라벨 집합마다 하나의 알림 인스턴스가 생성되어 수많은 인스턴스가 생길 수 있어요. 대신 쿼리 값에는 주석을 사용하세요.

템플릿화된 라벨의 값이 변경되면 다른 알림 인스턴스에 매핑되며, 이전 인스턴스는 stale로 간주돼요. 동적 라벨 예시에서 자세한 내용을 확인하세요.

라벨을 템플릿화하는 방법:

Alerts & IRM > Alert rules로 이동해 알림 규칙을 만들거나 편집해요.
Configure labels and notifications 섹션으로 스크롤해요.
+ Add labels를 클릭해요.
라벨을 식별하는 키를 입력해요.
값 필드에 템플릿을 붙여 넣어요.

라벨 템플릿 미리보기 (Preview label templates):

라벨 값을 미리보려면 Use notification policy를 선택한 뒤 Preview routing을 클릭해요.

추가 정보 (More information)

팁: 템플릿화의 실용 예시는 Getting Started with Templating 자습서를 참고하세요.

템플릿 주석과 라벨