Prometheus 어노테이션

Prometheus 어노테이션 (Annotations)

어노테이션은 대시보드 그래프 위에 이벤트 데이터를 겹쳐 보여줘서 이벤트와 지표를 연관 지어 해석할 수 있게 도와줘요. Prometheus를 어노테이션 데이터 소스로 사용하면 배포, 알림, 임계값 초과 같은 이벤트를 시각화 위에 표시할 수 있어요. 어노테이션 일반 개념은 Annotate visualizations를 참고하세요.

출처: Prometheus annotations

본문

시작하기 전에

Prometheus 어노테이션을 만들기 전에 다음을 확인해요.

• Grafana에 Prometheus 데이터 소스가 구성되어 있을 것
• 어노테이션할 이벤트를 나타내는 Prometheus 지표가 있을 것
• Prometheus 인스턴스에 대한 읽기 권한이 있을 것

어노테이션 쿼리 만들기

대시보드에 Prometheus 어노테이션을 추가하려면:

1. 업데이트할 대시보드로 이동해 Edit을 클릭해요.
2. Add new element 아이콘(파란색 더하기)을 클릭해요.
3. Annotation query를 클릭해요.
4. 어노테이션 쿼리의 이름을 입력해요.
5. 어노테이션 쿼리를 당장 쓰지 않을 거라면 Enabled 체크박스를 해제해요.
6. 어노테이션 이벤트 마커의 색상을 선택해요.
7. Show annotation controls in 드롭다운에서 어노테이션을 표시할 대시보드 위치를 선택해요.
8. Show in 드롭다운에서 어노테이션을 표시할 패널을 선택해요.
9. Open query editor를 클릭해 Annotation Query 대화 상자를 열어요.
10. Data source 드롭다운에서 Prometheus 데이터 소스를 선택해요.
11. 쿼리 필드에 PromQL 표현식을 입력해요.
12. Min step을 설정해 어노테이션 밀도를 제어해요(큰 step = 어노테이션 수 감소).
13. 어노테이션 툴팁에 무엇이 나타날지 필드 매핑을 구성해요.
14. (선택) Test annotation query를 클릭해 쿼리가 제대로 동작하는지 확인해요.
15. 쿼리 설정을 마쳤으면 Close를 클릭해요.
16. Save를 클릭해요.
17. (선택) 변경 내용에 대한 설명을 입력해요.
18. Save를 클릭해요.
19. Exit edit을 클릭해요.

Prometheus 어노테이션 동작 방식

Prometheus 어노테이션은 SQL 기반 어노테이션과 다르게 동작해요. 이벤트 테이블을 질의하는 대신 시계열 데이터를 반환하는 PromQL 표현식을 작성해요. Grafana는 다음 규칙으로 쿼리 결과를 어노테이션 이벤트로 변환해요.

• Grafana가 PromQL 쿼리를 대시보드 시간 창에 대한 범위 쿼리로 실행해요.
• 반환된 모든 데이터 포인트가 어노테이션을 만들어요. 0 값의 자동 필터링은 없어요. 특정 순간에만 어노테이션을 원한다면 PromQL 표현식이 결과를 필터링해야 해요(예: > 0 또는 ALERTS 지표 사용).
• Grafana는 필드 매핑 구성을 사용해 각 어노테이션에 표시할 텍스트, 제목, 태그를 결정해요.
• 쿼리가 여러 시계열을 반환하면 각 시리즈가 자체 어노테이션 집합을 만들어요.

참고: 반환된 모든 데이터 포인트가 어노테이션을 만들기 때문에 node_cpu_seconds_total 같은 연속 데이터를 반환하는 쿼리는 모든 간격에서 어노테이션을 만들어 대시보드를 범람시켜요. 항상 어노테이션하려는 순간에만 데이터를 반환하는 표현식을 사용하세요.

필드 매핑

PromQL 표현식을 입력한 후 필드 매핑 드롭다운을 사용해 쿼리 결과가 어노테이션으로 어떻게 표시될지 제어해요. Grafana는 다음에 대한 매핑 옵션을 보여줘요.

필드	설명	기본 동작
Time	어노테이션 타임스탬프	첫 번째 시간 유형 필드 사용(항상 존재)
TimeEnd	범위 어노테이션의 종료 타임스탬프. 음영 영역으로 표시	설정 안 함(점 어노테이션 생성)
Title	어노테이션 마커에 표시되는 짧은 라벨	설정 안 함
Text	마우스를 올렸을 때 표시되는 어노테이션 설명	첫 번째 문자열 유형 필드, 또는 구성된 경우 지표/라벨 표시 이름 사용
Tags	어노테이션의 쉼표로 구분된 태그. 분류·필터링에 도움	설정 안 함

필드 매핑을 구성하려면 각 드롭다운에서 적절한 필드 이름을 선택하거나 고정 텍스트 값을 입력해요.

예시 어노테이션 쿼리

다음 예시는 Prometheus의 일반적인 어노테이션 패턴을 보여줘요.

ALERTS를 사용하는 알림 기반 어노테이션

Prometheus 어노테이션을 만드는 가장 일반적이고 안정적인 방법이에요. Prometheus는 구성된 모든 알림 규칙에 대해 ALERTS 지표를 자동 생성해요.

ALERTS{alertstate="firing"}

이 쿼리는 알림이 발화 중인 모든 step 간격마다 어노테이션을 만들어요. ALERTS 지표에는 다음 라벨이 포함돼요.

• alertname: 알림 규칙의 이름
• alertstate: firing 또는 pending
• 알림 규칙에 정의된 모든 라벨

특정 알림이나 심각도 수준으로 제한하려면:

ALERTS{alertname="HighCPUUsage", severity="critical"}

필드 매핑을 구성해요.

• Text: alertname (호버 시 알림 이름 표시)
• Tags: severity (심각도로 필터링 가능)

서비스 재시작 어노테이션

프로세스가 재시작될 때 어노테이션을 표시해요. changes() 함수는 값이 변경될 때 감지하고, > 0은 변경 순간에만 어노테이션이 나타나게 해요.

changes(process_start_time_seconds{job="myservice"}[5m]) > 0

배포 어노테이션

Pushgateway를 통해 타임스탬프 지표를 푸시하거나 기록 규칙으로 배포를 추적한다면:

changes(deployment_timestamp_seconds{environment="production"}[10m]) > 0

필드 매핑을 구성해요.

• Text: environment (어떤 환경이 배포됐는지 표시)
• Tags: environment

임계값 초과 어노테이션

사용 가능한 메모리가 10% 아래로 떨어질 때 어노테이션을 표시해요:

node_memory_MemAvailable_bytes / node_memory_MemTotal_bytes < 0.1

참고: PromQL의 비교 연산자는 필터 역할을 해요. 조건이 참인 데이터 포인트만 반환해요. 즉 위 표현식은 메모리가 10% 미만일 때만 데이터를 반환하고, 그때만 어노테이션이 나타나요. 외부 > 0 래퍼를 추가할 필요가 없어요.

스케일링 이벤트 어노테이션

실행 중인 파드 수가 변경될 때 어노테이션을 표시해요:

changes(kube_deployment_status_replicas{deployment="my-app"}[5m]) > 0

오류 급증 어노테이션

오류율이 임계값을 초과할 때 어노테이션을 표시해요:

sum(rate(http_requests_total{status=~"5.."}[5m])) by (job) / sum(rate(http_requests_total[5m])) by (job) > 0.05

이 쿼리는 오류율이 5%를 초과할 때 어노테이션을 만들어요.

버전 또는 빌드 변경 어노테이션

build_info 같은 지표로 빌드 메타데이터를 노출한다면(Go 서비스에서 일반적) 버전이 변경될 때 어노테이션을 표시해요:

changes(build_info{job="myservice"}[10m]) > 0

필드 매핑을 구성해요.

• Text: version (어노테이션 툴팁에 새 버전 표시)
• Tags: job

빌드 정보 지표가 version 라벨(예: build_info{version="1.2.3"})을 사용한다면 어노테이션 툴팁에 배포된 버전이 표시돼요.

어노테이션 밀도 제어

Min step 설정은 쿼리가 반환하는 데이터 포인트 수를 제어하며, 이는 표시되는 어노테이션 수에 직접 영향을 줘요. step이 클수록 어노테이션이 줄어요.

• Min step 1m: 분당 최대 1개 어노테이션(짧은 시간 범위에 적합)
• Min step 5m: 5분당 최대 1개 어노테이션(하루 범위 대시보드에 적합)
• Min step 1h: 시간당 최대 1개 어노테이션(주간 범위 대시보드에 적합)

대시보드에 어노테이션 마커가 너무 많다면 Min step을 늘리거나 쿼리에 더 구체적인 필터를 추가해요.

어노테이션에서 템플릿 변수 사용

대시보드 변수 선택에 따라 어노테이션을 필터링하려면 어노테이션 쿼리에서 템플릿 변수를 사용할 수 있어요.

ALERTS{alertstate="firing", instance=~"$instance"}

changes(process_start_time_seconds{job="$job"}[5m]) > 0

어노테이션의 템플릿 변수는 현재 대시보드 변수 값을 사용해 쿼리 시점에 해석돼요.

범위 어노테이션

범위 어노테이션은 세로 선 대신 음영 영역으로 표시되며 기간이 있는 이벤트를 나타내요. 범위 어노테이션을 만들려면 쿼리 결과에 TimeEnd 필드 매핑이 포함돼야 해요.

PromQL은 시작/종료 시간 쌍을 네이티브로 반환하지 않으므로, Prometheus의 범위 어노테이션은 시작·종료 시간에 대한 별도 지표가 있는 시나리오(예: 기록 규칙이나 Pushgateway로 푸시된 커스텀 지표)로 제한돼요. 대부분의 사용 사례에서는 점 어노테이션(이 페이지의 예시 사용)이 실용적인 접근이에요.

어노테이션이 나타나지 않거나 오류가 발생하면 Prometheus 데이터 소스 문제 해결을 참고하세요.

더 알아보기 (Learn more)

• Annotate visualizations - 어노테이션 시각화
• Prometheus query editor - 쿼리 편집기
• Prometheus data source - 데이터 소스 개요
• Troubleshoot Prometheus data source - 문제 해결
• Prometheus annotations - 원문 문서