Elasticsearch 어노테이션

어노테이션(Annotations)은 대시보드 그래프 위에 이벤트 데이터를 겹쳐 보여줘서 로그 이벤트와 메트릭을 서로 연관 지어 해석할 수 있게 도와줘요. Elasticsearch를 어노테이션 데이터 소스로 사용하면 배포(deployment), 알림, 그 밖에 의미 있는 사건을 시각화 위에 표시할 수 있어요. 어노테이션 일반 개념은 어노테이션 시각화 방법 문서를 참고하세요.

출처: Elasticsearch annotations

본문

시작하기 전에

Elasticsearch 어노테이션을 만들기 전에 다음이 준비되어 있어야 해요.

Grafana에 Elasticsearch 데이터 소스가 설정되어 있을 것
타임스탬프 필드가 포함된 이벤트 데이터가 담긴 Elasticsearch 문서가 있을 것
이벤트가 들어 있는 Elasticsearch 인덱스에 대한 읽기 권한이 있을 것

어노테이션 쿼리 만들기

대시보드에 Elasticsearch 어노테이션을 추가하려면 다음 순서대로 해요.

업데이트할 대시보드로 이동해 Edit을 클릭해요.
Add new element 아이콘(파란색 더하기)을 클릭해요.
Annotation query를 클릭해요.
어노테이션 쿼리의 이름을 입력해요.
어노테이션 쿼리를 당장 쓰지 않을 거라면 Enabled 체크박스를 해제해요.
어노테이션 이벤트 마커의 색상을 선택해요.
Show annotation controls in 드롭다운에서 어노테이션을 표시할 대시보드 위치를 선택해요.
Show in 드롭다운에서 어노테이션을 표시할 패널을 선택해요.
Open query editor를 클릭해 Annotation Query 대화 상자를 열어요.
Data source 드롭다운에서 Elasticsearch 데이터 소스를 선택해요.
어노테이션 쿼리와 필드 매핑을 구성해요.
(선택) Test annotation query를 클릭해 쿼리가 제대로 동작하는지 확인해요.
쿼리 설정을 마쳤으면 Close를 클릭해요.
Save를 클릭해요.
(선택) 변경 내용에 대한 설명을 입력해요.
Save를 클릭해요.
Exit edit을 클릭해요.

Query (쿼리)

쿼리 필드를 사용해 어떤 Elasticsearch 문서가 어노테이션으로 표시될지 필터링해요. 쿼리는 Lucene 쿼리 문법을 사용해요.

예시:

Query	Description
`*`	모든 문서를 매칭해요.
`type:deployment`	배포 이벤트만 보여줘요.
`level:error OR level:critical`	error와 critical 이벤트를 보여줘요.
`service:api AND environment:production`	특정 서비스와 환경의 이벤트를 보여줘요.
`tags:release`	release 태그가 달린 이벤트를 보여줘요.

어노테이션 쿼리에서도 템플릿 변수를 사용할 수 있어요. 예를 들어 service:$service는 선택한 service 변수에 따라 어노테이션을 필터링해요.

Field mappings (필드 매핑)

필드 매핑은 Grafana에게 어노테이션 데이터가 Elasticsearch의 어떤 필드에 들어 있는지 알려줘요.

Time

Time 필드는 어노테이션 타임스탬프가 들어 있는 필드를 지정해요.

기본값: @timestamp
형식: Elasticsearch가 인식하는 날짜 값이어야 해요.

Time End

Time End 필드는 범위(range) 어노테이션의 종료 시각이 들어 있는 필드를 지정해요. 범위 어노테이션은 그래프에서 세로 선 하나 대신 음영 처리된 영역으로 표시돼요.

기본값: 비어 있음(단일 지점 어노테이션)
용도: 유지보수 창, 장애, 기간이 있는 이벤트를 표시할 때 사용해요.

Text

Text 필드는 어노테이션 위에 마우스를 올렸을 때 표시되는 설명이 들어 있는 필드를 지정해요.

기본값: tags
팁: message, description, summary처럼 설명적인 필드를 사용해요.

예시: 배포 어노테이션

배포 이벤트를 어노테이션으로 표시하려면:

다음 설정으로 어노테이션 쿼리를 만들어요.
- Query: type:deployment
- Time: @timestamp
- Text: message
- Tags: environment

이 설정은 배포 이벤트의 message를 어노테이션 텍스트로, environment를 태그로 표시해요.

예시: 장애에 대한 범위 어노테이션

기간이 있는 장애를 표시하려면:

다음 설정으로 어노테이션 쿼리를 만들어요.
- Query: type:incident
- Time: start_time
- Time End: end_time
- Text: description
- Tags: severity

이 설정은 장애를 시작 시각부터 종료 시각까지 음영 처리된 영역으로 표시해요.

더 알아보기 (Learn more)

Annotate visualizations - 어노테이션 시각화 일반 가이드
Elasticsearch data source - Elasticsearch 데이터 소스 개요
Lucene query string syntax - Lucene 쿼리 문법
Elasticsearch annotations - 원문 문서

Elasticsearch 어노테이션