PostgreSQL 어노테이션

PostgreSQL 어노테이션 (PostgreSQL annotations)

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

출처: 문서

본문

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

시작하기 전에

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

어노테이션 쿼리 만들기

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

쿼리 컬럼

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

예시 쿼리

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

SELECT
  epoch_time as time,
  metric1 as text,
  concat_ws(', ', metric1::text, metric2::text) as tags
FROM public.test_data
WHERE $__unixEpochFilter(epoch_time)

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

SELECT
  epoch_time as time,
  epoch_time_end as timeend,
  metric1 as text,
  concat_ws(', ', metric1::text, metric2::text) as tags
FROM public.test_data
WHERE $__unixEpochFilter(epoch_time)

네이티브 SQL date/time 어노테이션

SELECT
  native_date_time as time,
  metric1 as text,
  concat_ws(', ', metric1::text, metric2::text) as tags
FROM public.test_data
WHERE $__timeFilter(native_date_time)

배포 어노테이션

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)

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