시각화에 주석 달기

시각화에 주석 달기 (Annotate visualizations)

주석(annotation)은 풍부한 이벤트로 시각화의 지점을 표시하는 방법을 제공해요. 모든 그래프 패널에서 세로선과 아이콘으로 시각화돼요. 주석 위에 마우스를 올리면 이벤트 설명과 이벤트 태그를 볼 수 있어요. 텍스트 필드에 더 자세한 다른 시스템으로의 링크를 포함할 수 있답니다.

출처: Annotate visualizations

본문

시각화에 주석을 다는 세 가지 방법이 있어요.

내장 주석 쿼리를 사용해 패널에서 직접
HTTP API 사용 — Annotations API 문서 참고
주석 쿼리 구성

첫 두 경우는 새 주석을 만드는 것이고, 마지막 경우는 데이터 소스에서 기존 주석을 쿼리하는 것이에요. 내장 주석 쿼리도 이를 지원해요. 이 페이지는 첫 번째와 세 번째 옵션을 설명해요.

주석은 다음 시각화 유형을 지원해요.

Time series
State timeline
Candlestick

패널에서 주석 만들기

Grafana에는 모든 대시보드에 존재하는 내장 주석 쿼리를 사용해 패널에서 직접 주석 이벤트를 추가하는 기능이 내장돼 있어요. 이렇게 만든 주석은 Grafana에 저장돼요. 패널에서 직접 주석을 추가하려면:

대시보드가 이미 저장되어 있어야 해요.
내장 쿼리가 활성화되어 있어야 해요. 자세한 내용은 Built-in query 섹션을 참고하세요.

주석 추가:

대시보드를 방금 저장했다면 페이지를 새로고침해요.
패널에서 데이터 포인트를 클릭해 툴팁을 열어요.
툴팁에서 Add annotation을 클릭해요.
주석 설명과 태그를 추가해요(선택 사항).
Save를 클릭해요.

또는 주석을 추가하려면 Ctrl/Cmd를 누른 채 패널의 아무 곳이나 클릭하면 Add annotation 툴팁이 나타나요.

영역 주석 추가 (Add a region annotation):

대시보드를 방금 저장했다면 페이지를 새로고침해요.
Ctrl/Cmd를 누른 채 패널에서 클릭·드래그해 Add annotation 대화 상자를 열어요.
주석 설명과 태그를 추가해요(선택 사항).
Save를 클릭해요.

주석 편집:

패널 하단의 주석 표시 위에 마우스를 올려 툴팁을 열어요.
연필 아이콘을 클릭해 주석 대화 상자를 열어요.
설명과 태그를 수정해요.
Save를 클릭해요.

주석 삭제:

패널 하단의 주석 표시 위에 마우스를 올려 툴팁을 열어요.
휴지통 아이콘을 클릭해 주석 대화 상자를 열어요. (주석 대화 상자에서 삭제)

주석 쿼리 (Annotation queries)

내장 데이터 주석 데이터 소스를 포함해 어떤 데이터 소스로든 주석을 가져오는 새 쿼리를 추가할 수 있어요. 주석 쿼리는 대시보드 전반의 그래프에서 이벤트 마커로 시각화될 수 있는 이벤트를 반환해요.

주석 쿼리 추가:

업데이트할 대시보드로 이동해요.
Edit을 클릭해요.
Add new element 아이콘(파란 플러스)을 클릭해요.
Annotation query를 클릭해요.
주석 쿼리 이름을 입력해요. 이 이름은 이 쿼리의 주석 이벤트 표시를 활성화/비활성화하는 토글에 부여돼요.
주석 쿼리를 바로 사용하지 않으려면 Enabled 체크박스를 해제해요.
주석 이벤트 마커의 색상을 선택해요.
Show annotation controls in 드롭다운에서 다음 옵션 중 하나를 선택해 주석이 표시되는 위치를 제어해요.
- Above dashboard: 주석 토글이 대시보드 위에 표시돼요 (기본값).
- Controls menu: 주석 토글이 대시보드 위 대신 대시보드 컨트롤 메뉴에 표시돼요. 대시보드 컨트롤 메뉴는 대시보드 도구 모음의 버튼으로 나타나요.
- Hidden: 주석 토글이 대시보드에 표시되지 않아요.
Show in 드롭다운에서 다음 옵션 중 하나를 선택해 주석이 표시되는 패널을 제어해요.
- All panels: 주석을 지원하는 모든 패널에 주석이 표시돼요.
- Selected panels: 선택한 모든 패널에 주석이 표시돼요.
- All panels except: 선택한 패널을 제외한 모든 패널에 표시돼요.
주석 필터링에 쿼리를 추가하려면:
- Open query editor를 클릭해 Annotation Query 대화 상자를 열고 Data source 드롭다운에서 옵션을 선택한 뒤 쿼리를 작성·구성해요. 주석 쿼리 옵션은 데이터 소스마다 다르며, 특정 데이터 소스 문서를 참고하세요. 다음 단계로 진행해요.
- Use saved query를 클릭해 Saved queries 서랍을 열어요. 재사용할 saved query를 선택하고 Select query를 클릭한 뒤 13단계로 진행해요.
참고: Saved queries는 Grafana Enterprise와 Grafana Cloud에서만 사용 가능해요.
(선택) Test annotation query를 클릭해 쿼리가 제대로 동작하는지 확인해요.
쿼리 설정을 완료하면 Close를 클릭해요.
Save를 클릭해요.
(선택) 변경 사항에 대한 설명을 입력해요.
Save를 클릭해요.
Exit edit을 클릭해요.

저장된 쿼리 (Saved queries)

참고: Saved queries는 Grafana Enterprise와 Grafana Cloud에서만 사용 가능해요.

조직의 다른 사용자(및 자신)가 주석에 저장한 쿼리를 재사용할 수 있어요. 이는 조직 전체의 사용자가 자신의 쿼리를 만들거나 쿼리 언어를 알 필요 없이 주석을 만들 수 있게 도와줘요. 또한 여러 사용자가 같은 데이터 소스에 대해 동일한 쿼리를 여러 번 만들지 않게 해 줘요. Saved queries는 다음에서 지원돼요.

Dashboards
Explore
Annotations

자세한 내용은 Saved queries 문서를 참고하세요.

Saved queries 대화 상자:

주석 구성에서 Use saved query를 클릭해 조직의 모든 saved query에 접근할 수 있어요.

참고: saved query를 검토하려면 Ctrl + K 또는 Cmd + K로 명령 팔레트를 열고 "Saved queries"를 검색해요. 이 보기에서 Explore로 열 쿼리를 선택할 수도 있어요.

Saved queries 대화 상자에서 다음을 할 수 있어요.

데이터 소스 이름, 쿼리 내용, 제목 또는 설명으로 쿼리를 검색.
알파벳순 또는 생성일로 쿼리를 정렬.
데이터 소스 이름, 작성자 이름, 태그로 필터링. 태그 필터는 OR 연산자를, 나머지는 AND 연산자를 사용해요. Remember filters 스위치를 사용해 로컬 저장소의 세션 간에 필터 선택을 유지할 수 있어요.
Starred queries 필터 보기에 나타나도록 쿼리에 별표 표시.
saved query를 복제하거나 삭제.
쿼리 제목, 설명 또는 태그 편집.
Starred queries 필터 보기에서도 동일한 모든 검색·필터·정렬 옵션을 적용할 수 있어요.

팁: Loki, Mimir, Tempo, Pyroscope 데이터 소스가 있는 쿼리를 선택하면 Saved queries 대화 상자에 Drilldown 버튼이 표시돼요. 버튼을 클릭하면 쿼리의 컨텍스트를 유지하면서 관련 Drilldown 앱이 열려요.

역할, 권한, RBAC:

Saved queries는 역할 기반 접근 제어를 지원해요. 기본적으로 saved query에는 두 개의 RBAC 역할이 있어요.

Writer: 모든 saved query를 생성·업데이트·삭제.
Reader: saved query 재사용.

Grafana v12.4에서 RBAC 지원이 추가되기 전에 saved query를 사용했다면 Grafana 사용자 역할은 다음과 같이 매핑돼요. Admin > Writer, Editor > Writer, Viewer > Reader.

Saved queries의 변수:

saved query에 변수가 포함되면 쿼리를 수정하지 않고도 쿼리에서 변수를 대체할 수 있어요. 이는 대시보드 간에 변수 이름이나 사용 가능한 값이 다른 환경에서 유용해요. 원래 변수를 대시보드의 변수 또는 입력한 커스텀 값에 매핑할 수 있어요. Grafana는 쿼리를 대시보드에 삽입하기 전에 선택 사항을 쿼리에 적용해요. 다만 대체는 쿼리가 재사용될 때만 적용되며, 원래 saved query는 변경되지 않아요.

코드로 saved query 관리:

Grafana Terraform provider로 saved query를 코드로 관리할 수 있어요. 이렇게 하면 쿼리 라이브러리를 버전 관리하고 인스턴스 간에 일관성을 유지할 수 있어요. 자세한 내용은 Terraform으로 saved query 관리 문서를 참고하세요.

알려진 제한:

쿼리를 저장할 때 검증이 수행되지 않아 유효하지 않은 쿼리를 저장할 수 있어요. 저장 전에 쿼리가 제대로 동작하는지 확인해야 해요.
최대 1000개의 쿼리를 저장할 수 있어요.

내장 쿼리 (Built-in query)

주석을 추가한 후에도 여전히 표시되는 것은 모든 대시보드에 존재하는 내장 주석 쿼리 때문이에요. 이 주석 쿼리는 현재 대시보드에서 시작된 모든 주석 이벤트를 가져와서 그것들이 생성된 패널에 표시해요. 여기에는 알림 상태 이력 주석도 포함돼요.

기본적으로 내장 주석 쿼리는 -- Grafana -- 특수 데이터 소스를 사용하며, 수동 주석은 이 데이터 소스에서만 지원돼요. 내장 주석 쿼리에 다른 데이터 소스를 사용할 수 있지만, 해당 데이터 소스의 쿼리 편집기로 자동 주석만 만들 수 있어요. 대시보드에 주석을 직접 추가하려면 이 쿼리가 활성화되어 있어야 해요.

내장 쿼리가 활성화되었는지 확인하려면:

대시보드 오른쪽 상단에서 Edit을 클릭해요.
도구 모음에서 Dashboard options 아이콘을 클릭해요.
사이드바에서 Annotations 섹션을 펼쳐요.
주석의 Hidden 섹션을 펼쳐요.
**Annotations & Alerts (Built-in query)**를 선택해요.
Enabled 체크박스가 선택되었는지 확인해요. 주석을 가져오고 그리지 않으려면 체크박스를 해제해요.
Save를 클릭해요.
변경 사항에 대한 선택적 설명을 입력하고 Save를 클릭해요.
Exit edit을 클릭해요.

Save As 기능으로 대시보드를 복사하면 새 대시보드 ID가 생겨 원본 대시보드에서 만든 주석이 복사본에 더 이상 표시되지 않아요. 새 Annotation Query를 추가하고 태그로 필터링하면 여전히 표시할 수 있어요. 다만 원본 대시보드의 주석에 필터링할 태그가 있을 때만 동작해요.

다음은 내장 주석 쿼리 특유의 몇 가지 쿼리 옵션이에요.

태그로 쿼리 필터링:

-- Grafana -- 데이터 소스를 사용해 Filter by를 Tags로 설정하면 내장 주석 쿼리에서 주석을 가져오는 새 쿼리를 만들 수 있어요. Grafana는 기존 태그의 타입어헤드(typeahead)도 지원하므로 하나 이상의 태그를 제공하세요.

예를 들어 이름이 outages인 주석 쿼리를 만들고 outage 태그를 지정해요. 이 쿼리는 outage 태그가 있는 모든 주석(어떤 대시보드 또는 API에서든)을 표시해요. 주석 쿼리에 여러 태그가 정의되면 Grafana는 모든 태그와 일치하는 주석만 표시해요. 이 동작을 수정하려면 Match any를 활성화하면 제공한 태그 중 하나라도 포함하는 주석을 표시해요.

⚠️ 경고: 태그 기반 주석 쿼리를 사용하는 외부 공유 대시보드에서 Display annotations을 활성화하면, 해당 쿼리는 조직의 모든 대시보드에서 일치하는 주석을 반환해요. 즉 외부로 공유되지 않는 대시보드의 주석도 공유된 대시보드에 접근할 수 있는 누구에게나 표시될 수 있어요. 이는 의도된 동작이에요. 공유 대시보드에서 이 옵션을 활성화하기 전에 어떤 주석이 태그와 일치할 수 있는지 검토하세요.

태그 쿼리에 템플릿 변수를 사용할 수도 있어요. 즉 서로 다른 서비스의 통계를 보여 주는 대시보드와 표시할 서비스를 결정하는 템플릿 변수가 있다면, 주석 쿼리에서 같은 템플릿 변수를 사용해 해당 서비스에 대한 주석만 표시할 수 있어요.

시간 영역 추가 (Add time regions):

주석을 추가하거나 편집할 때 Query type을 Time regions으로 설정하면 반복 시간 영역을 정의할 수 있어요. 그런 다음 선호하는 요일과 시간으로 From과 To 섹션을 정의해요. 기본적으로 대시보드 시간대로 설정된 시간대를 변경할 수도 있어요. 위 구성은 Time series 패널에서 특정 결과를 만들어요. Advanced 스위치를 켜고 Cron 문법을 사용하면 더 세분화된 시간 영역 컨트롤을 설정할 수 있어요. 다음 예시는 월요일~금요일 9:00 AM의 시간 영역을 설정하는 예시예요.

시각화에 주석 달기