MySQL 어노테이션

MySQL 어노테이션 (MySQL annotations)

어노테이션은 대시보드 그래프 위에 이벤트 데이터를 겹쳐 보여줘서 이벤트와 메트릭을 상호 연결하는 데 도움을 줘요. MySQL을 어노테이션 데이터 소스로 사용해 배포·알림 같은 중요한 이벤트를 시각화에 표시할 수 있어요. time 컬럼을 필수로 반환하는 어노테이션 쿼리를 작성하는 방법을 알려드릴게요.

출처: 문서

본문

어노테이션에 대한 일반 정보는 시각화 어노테이션(Annotate visualizations) 문서를 참고하세요.

시작하기 전에

• Grafana에 MySQL 데이터 소스가 구성되어 있어야 해요.
• 타임스탬프 필드가 있는 이벤트 데이터 테이블이 있어야 해요.
• 이벤트가 포함된 테이블에 대한 읽기 권한이 있어야 해요.

어노테이션 쿼리 만들기

1. 대시보드에서 Edit 클릭 → Add new element(파란 더하기) → Annotation query 클릭
2. 어노테이션 쿼리 이름 입력
3. (선택) 바로 쓰지 않으면 Enabled 체크 해제
4. 이벤트 마커 색상 선택
5. Show annotation controls in에서 표시 위치, Show in에서 표시 패널 선택
6. Open query editor 클릭해 Annotation Query 대화상자 열기
7. Data source에서 MySQL 선택
8. 어노테이션 쿼리와 필드 매핑 구성
9. (선택) Test annotation query로 쿼리 확인
10. Close → Save → Exit edit

쿼리 컬럼

어노테이션 쿼리는 time 컬럼을 필수로 반환해야 하고, 선택적으로 timeend, text, tags 컬럼을 포함할 수 있어요.

예시 쿼리

기본 어노테이션 (epoch 시간)

SELECT
  epoch_time as time,
  description as text,
  CONCAT(tag1, ',', tag2) as tags
FROM events
WHERE $__unixEpochFilter(epoch_time)

단일 태그 어노테이션

SELECT
  epoch_time as time,
  message as text,
  category as tags
FROM event_log
WHERE $__unixEpochFilter(epoch_time)

시작·종료 시간이 있는 범위 어노테이션

SELECT
  start_time as time,
  end_time as timeend,
  description as text,
  CONCAT(type, ',', severity) as tags
FROM incidents
WHERE $__unixEpochFilter(start_time)

네이티브 SQL datetime 어노테이션

SELECT
  event_date as time,
  message as text,
  CONCAT(category, ',', priority) as tags
FROM system_events
WHERE $__timeFilter(event_date)

배포 어노테이션

SELECT
  deployed_at as time,
  CONCAT('Deployed ', version, ' to ', environment) as text,
  environment as tags
FROM deployments
WHERE $__timeFilter(deployed_at)

유지보수 창 어노테이션 (범위)

SELECT
  start_time as time,
  end_time as timeend,
  CONCAT('Maintenance: ', description) as text,
  'maintenance' as tags
FROM maintenance_windows
WHERE $__timeFilter(start_time)

매크로

대시보드 시간 범위로 필터링하는 데 쓰는 매크로:

모범 사례

• 시간 필터 사용: $__timeFilter()나 $__unixEpochFilter()를 항상 포함해 결과를 대시보드 시간 범위로 제한하세요.
• 쿼리 효율: 시간 컬럼·필터 컬럼에 인덱스를 추가해 성능을 높이세요.
• 의미 있는 텍스트: text 컬럼에 설명 정보를 포함하세요.
• 태그로 정리: 일관된 태그 값으로 어노테이션을 분류하고 필터링 가능하게 하세요.
• 먼저 테스트: Explore에서 예상 결과가 나오는지 확인한 뒤 어노테이션으로 추가하세요.

더 알아보기 (Learn more)

• MySQL 데이터 소스
• 시각화 어노테이션
• MySQL 템플릿 변수