라벨과 주석

라벨과 주석 (Labels and annotations)

라벨과 주석은 키/값 쌍으로 알림에 추가 정보를 더해줘요. **라벨(Labels)**은 알림을 다른 알림과 구분하고 관리 방법을 결정하는 데 사용되고, **주석(Annotations)**은 대응자가 잠재적 문제를 이해하고 해결하도록 도와주는 추가 세부정보를 제공해요.

출처: 문서

본문

라벨과 주석은 키/값 쌍으로 알림에 추가 정보를 더합니다. 라벨은 알림을 다른 알림과 구분하고 관리 방법을 결정하며, 주석은 대응자가 잠재적 문제를 이해·해결하도록 추가 세부정보를 제공합니다.

라벨 (Labels)

라벨은 알림 인스턴스의 고유 식별자입니다. 검색, 침묵, 알림 라우팅에 사용할 수 있습니다. 라벨 예시는 server=server1 또는 team=backend입니다. 각 알림 규칙은 여러 라벨을 가질 수 있으며, 규칙의 전체 라벨 집합을 label set이라고 부르고 이 집합이 알림을 식별합니다.

예를 들어 한 인스턴스는 {alertname="High CPU usage",server="server1"}, 다른 인스턴스는 {alertname="High CPU usage",server="server2"} 라벨 집합을 가질 수 있습니다. alertname은 같지만 server가 다르므로 둘은 별개의 알림 인스턴스입니다.

라벨은 알림의 기본 구성 요소입니다.

알림의 전체 라벨 집합이 알림 인스턴스를 고유하게 식별합니다.
알림 UI는 규칙 평가 중 생성된 모든 인스턴스의 라벨을 보여줍니다.
알림 정책과 침묵은 라벨로 인스턴스를 일치시켜 연락 지점으로 라우팅하거나 알림을 중지합니다.
연락 지점은 알림 메시지에 라벨 정보를 포함할 수 있습니다.

라벨 유형

알림의 라벨 집합은 세 가지 유형의 라벨을 포함할 수 있습니다.

사용자 구성 라벨 (User-configured labels)

알림 규칙에서 수동으로 구성해 생성된 인스턴스를 식별하고 알림을 관리합니다. 사용 사례에 따른 공통 커스텀 라벨은 severity, priority, team, service입니다. 또한 템플릿으로 라벨 값을 커스터마이즈하고 쿼리 데이터에서 동적 값을 생성할 수 있습니다.

쿼리 라벨 (Query labels)

데이터 소스 쿼리가 반환하는 라벨입니다. 쿼리 라벨은 같은 알림 규칙에서 여러 인스턴스를 생성해 서로 다른 데이터의 알림을 구분하는 데 도움을 줍니다. 예를 들어 instance 라벨은 각 서버마다 알림 인스턴스를 생성합니다.

예약 라벨 (Reserved labels)

Grafana가 자동으로 추가하는 라벨입니다.

alertname: 알림 규칙의 이름
grafana_folder: 알림이 포함된 폴더의 제목

grafana_ 접두사가 붙은 라벨은 Grafana가 특별한 용도로 예약합니다. 예약 라벨은 unified_alerting.reserved_labels 옵션으로 비활성화할 수 있습니다.

참고: 두 알림 규칙이 같은 라벨을 가진 인스턴스를 생성할 수는 없습니다. 두 규칙이 foo=bar,bar=baz와 같은 같은 라벨을 가지면 생성된 인스턴스 중 하나가 폐기됩니다. 알림의 라벨 집합에 같은 이름의 라벨이 두 개 이상 없도록 하세요. 구성된 라벨이 데이터 소스 쿼리 라벨과 같은 이름이면 데이터 소스 라벨을 대체하고, 예약 라벨과 같은 이름이면 생략됩니다.

라벨 키 형식

Grafana의 내장 Alertmanager는 유니코드 라벨 키와 값을 지원합니다. 외부 Prometheus Alertmanager를 사용한다면 라벨 키가 데이터 모델과 호환되어야 합니다. 즉 라벨 키는 ASCII 문자, 숫자, 밑줄만 포함해야 하며 정규식 [a-zA-Z_][a-zA-Z0-9_]*와 일치해야 합니다. 잘못된 문자는 Grafana 알림 엔진이 외부 Alertmanager로 보내기 전에 제거·대체합니다.

공백(whitespace)은 제거됩니다.
ASCII 문자는 _로 대체됩니다.
기타 문자는 소문자 16진수 표현으로 대체됩니다. 첫 문자가 이 경우 _가 접두사로 붙습니다.

예: 라벨 키/값 쌍 Alert! 🔔="🔥"는 Alert_0x1f514="🔥"가 됩니다. 여러 라벨 키가 같은 값으로 정화(sanitize)되면 중복 항목에 원래 라벨의 짧은 해시가 접미사로 붙습니다.

주석 (Annotations)

주석은 인스턴스에 추가 정보를 더해 대응자가 잠재적 문제를 식별·해결하도록 돕습니다. 첫 대응자가 알림 설정에 대한 깊은 지식 없이도 조사할 수 있도록 명확하고 자명한 주석을 만드세요. 주석은 Grafana에 표시되며 기본적으로 알림에 포함됩니다. Grafana가 제공하는 편집 가능한 선택적 주석:

summary: 알림이 감지한 내용과 이유의 짧은 요약
description: 일어난 일과 알림이 하는 일의 상세 설명
runbook_url: 잠재적 사고를 관리하는 운영자를 안내하는 런북 페이지
__dashboardUid__와 __panelId__: 알림을 대시보드·패널에 연결해 알림 조사를 용이하게 함

예를 들어 summary 주석에 알림이 트리거된 이유를 설명할 수 있습니다.

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

description 주석으로 더 많은 컨텍스트와 대응 방법을 제공할 수도 있습니다.

The web server's CPU has exceeded 80% for more than 5 minutes.

This indicates that the system is under heavy load and may result in an outage.

Consider scaling the server's resources and investigating bottlenecks.

라벨과 마찬가지로 주석도 템플릿을 사용해 쿼리의 동적 데이터를 포함할 수 있습니다.

라벨과 주석