Microsoft SQL Server 어노테이션

Microsoft SQL Server 어노테이션 (Annotations)

어노테이션은 대시보드 시각화 위에 이벤트 마커를 겹쳐 보여줘서 지표 동작을 배포, 장애, 구성 변경 같은 이벤트와 연관 지어 해석할 수 있게 도와줘요. Microsoft SQL Server 데이터 소스로 SQL 쿼리 결과를 어노테이션 이벤트로 표시하는 어노테이션 쿼리를 만들 수 있어요. 어노테이션 일반 개념은 Annotate visualizations를 참고하세요.

출처: Microsoft SQL Server annotations

본문

시작하기 전에

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

어노테이션 쿼리 만들기

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

  1. 대시보드로 이동해 Dashboard settings(톱니바퀴 아이콘)을 클릭해요.
  2. 왼쪽 메뉴에서 Annotations를 선택해요.
  3. Add annotation query를 클릭해요.
  4. 어노테이션의 Name을 입력해요.
  5. Data source 드롭다운에서 Microsoft SQL Server 데이터 소스를 선택해요.
  6. 필요한 열을 반환하는 SQL 쿼리를 작성해요.
  7. Save dashboard를 클릭해요.

어노테이션 쿼리 열

어노테이션 쿼리는 특정 이름의 열을 반환해야 해요. Grafana는 이 이름을 사용해 쿼리 결과를 어노테이션 필드에 매핑해요.

열 필수 설명
time 예 이벤트의 날짜/시간. 네이티브 SQL 날짜/시간 유형 또는 초 단위 Unix epoch 값일 수 있어요.
timeend 아니요 영역 어노테이션의 종료 시간. time과 같은 형식. 선 대신 음영 영역을 만들어요.
text 예 어노테이션 툴팁에 표시되는 이벤트 설명.
tags 아니요 이벤트 태그에 사용되는 쉼표로 구분된 문자열. 태그는 분류·필터링에 도움.

예시: epoch 시간이 있는 어노테이션

Unix epoch 타임스탬프로 이벤트를 저장하는 테이블이 있다고 하면:

CREATE TABLE [events] (
  time_sec bigint,
  description nvarchar(100),
  tags nvarchar(100),
)

이벤트를 어노테이션으로 표시하는 쿼리:

SELECT
  time_sec as time,
  description as [text],
  tags
FROM
  [events]
WHERE
  $__unixEpochFilter(time_sec)
ORDER BY 1

$__unixEpochFilter 매크로는 이벤트를 자동으로 대시보드의 선택된 시간 범위로 필터링해요.

예시: 시작·종료 시간이 있는 영역 어노테이션

어노테이션을 음영 영역으로 표시하려면(기간에 걸쳐) time과 timeend 열을 모두 포함해요:

SELECT
  time_sec as time,
  time_end_sec as timeend,
  description as [text],
  tags
FROM
  [events]
WHERE
  $__unixEpochFilter(time_sec)
ORDER BY 1

예시: 네이티브 datetime 열의 어노테이션

테이블이 epoch 값 대신 네이티브 SQL datetime 또는 datetime2 열을 사용한다면:

SELECT
  time,
  measurement as text,
  convert(varchar, valueOne) + ',' + convert(varchar, valueTwo) as tags
FROM
  metric_values
WHERE
  $__timeFilter(time)
ORDER BY 1

$__timeFilter 매크로는 네이티브 SQL 날짜/시간 유형과 함께 작동하며 대시보드 시간 범위로 필터링해요.

예시: 배포 어노테이션

그래프에 배포 이벤트를 표시해요:

SELECT
  deployed_at as time,
  'Deployed ' + version + ' to ' + environment as [text],
  environment as tags
FROM
  [deployments]
WHERE
  $__timeFilter(deployed_at)
ORDER BY 1

예시: 유지보수 창 어노테이션

유지보수 창을 음영 영역으로 표시해요:

SELECT
  start_time as time,
  end_time as timeend,
  'Maintenance: ' + description as [text],
  'maintenance' as tags
FROM
  [maintenance_windows]
WHERE
  $__timeFilter(start_time)
ORDER BY 1

템플릿 변수 사용

어노테이션 쿼리에서 템플릿 변수를 사용해 동적으로 만들 수 있어요. 예를 들어 선택한 서버로 이벤트를 필터링해요:

SELECT
  time_sec as time,
  description as [text],
  tags
FROM
  [events]
WHERE
  $__unixEpochFilter(time_sec)
  AND server IN ($server)
ORDER BY 1

매크로

어노테이션 쿼리에서 대시보드 시간 범위로 필터링하려면 다음 매크로를 사용해요:

매크로 설명
$__timeFilter(column) 네이티브 SQL datetime/datetime2 열로 시간 범위 필터링
$__unixEpochFilter(column) Unix epoch 타임스탬프가 있는 열로 시간 범위 필터링

사용 가능한 매크로 전체 목록은 Microsoft SQL Server 쿼리 편집기를 참고하세요.

모범 사례

Microsoft SQL Server 어노테이션을 만들 때 다음 모범 사례를 따르세요.

  • 시간 필터 사용: 결과를 대시보드 시간 범위로 제한하려면 항상 $__timeFilter() 또는 $__unixEpochFilter()를 포함해요.
  • 쿼리 효율 유지: 쿼리 성능을 높이도록 시간 열과 필터 열에 인덱스를 추가해요.
  • 의미 있는 텍스트 사용: text 열에 설명 정보를 포함해 어노테이션을 한눈에 유용하게 만들어요.
  • 태그로 정리: 일관된 태그 값을 사용해 어노테이션을 분류하고 필터링을 가능하게 해요.
  • 먼저 쿼리 테스트: 어노테이션으로 추가하기 전에 Explore에서 쿼리가 예상 결과를 반환하는지 확인해요.

도움말

어노테이션이 나타나지 않거나 예상대로 동작하지 않으면 일반적인 해결책을 위해 Troubleshoot Microsoft SQL Server data source issues를 참고하세요.

더 알아보기 (Learn more)