InfluxDB 어노테이션

InfluxDB 어노테이션 (Annotations)

어노테이션은 대시보드 그래프 위에 이벤트 데이터를 겹쳐 보여줘서 이벤트와 지표를 연관 지어 해석할 수 있게 도와줘요. InfluxDB를 어노테이션 데이터 소스로 사용하면 배포, 알림, 기타 중요한 사건을 시각화 위에 표시할 수 있어요. 어노테이션 일반 개념은 Annotate visualizations를 참고하세요.

출처: InfluxDB annotations

본문

시작하기 전에

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

  • Grafana에 InfluxDB 데이터 소스가 구성되어 있을 것
  • 타임스탬프 필드가 있는 이벤트 정보를 담은 InfluxDB 데이터가 있을 것
  • 이벤트가 있는 InfluxDB 데이터베이스나 버킷에 대한 읽기 권한이 있을 것

어노테이션 쿼리 만들기

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

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

InfluxQL 어노테이션

InfluxQL 구성 데이터 소스에서는 InfluxQL Query 필드에 InfluxQL 쿼리를 작성해요. 쿼리 반드시 WHERE $timeFilter를 포함해 결과를 대시보드 시간 범위로 한정해야 해요.

필드 매핑

필드 매핑은 Grafana에게 어노테이션 데이터가 InfluxDB의 어떤 열에 있는지 알려줘요. 쿼리가 한 열만 반환한다면 필드 매핑 필드에 아무것도 입력할 필요가 없어요.

필드 설명
Text 어노테이션 위에 마우스를 올렸을 때 표시되는 설명이 들어 있는 열
Tags 어노테이션 태그가 들어 있는 열. 값은 쉼표로 구분된 문자열일 수 있어요. 태그는 어노테이션 분류·필터링에 도움
TimeEnd 범위 어노테이션의 종료 시각이 들어 있는 열. 범위 어노테이션은 그래프에서 세로 선 대신 음영 영역으로 표시

InfluxQL 어노테이션 쿼리 예시

다음 쿼리는 배포 이벤트를 검색해 어노테이션으로 표시해요.

SELECT title, description
FROM events
WHERE $timeFilter
ORDER BY time ASC

범위 어노테이션 예시

기간이 있는 이벤트를 음영 영역으로 표시하려면:

SELECT description, tags, end_time
FROM maintenance_windows
WHERE $timeFilter
ORDER BY time ASC

필드 매핑을 다음과 같이 구성해요.

  • Text: description
  • Tags: tags
  • TimeEnd: end_time

Flux 어노테이션

Flux 구성 데이터 소스에서는 어노테이션이 표준 Flux 쿼리 편집기를 사용해요. time, text, 선택적 tag 필드가 있는 데이터 프레임을 반환하는 Flux 쿼리를 작성해요.

Flux 어노테이션 쿼리 예시

from(bucket: "events")
  |> range(start: v.timeRangeStart, stop: v.timeRangeStop)
  |> filter(fn: (r) => r["_measurement"] == "deployments")
  |> pivot(rowKey: ["_time"], columnKey: ["_field"], valueColumn: "_value")

Grafana는 결과 데이터 프레임을 어노테이션 이벤트로 처리해요. 쿼리가 _time 열과 최소 하나의 텍스트 열을 반환하는지 확인해요.

SQL 어노테이션

SQL 구성 데이터 소스(InfluxDB 3.x)는 표준 Grafana 어노테이션 쿼리 편집기를 사용해요. 시간 열과 최소 하나의 텍스트 열을 반환하는 SQL 쿼리를 작성해요. 결과를 대시보드 시간 범위로 한정하려면 $__timeFilter(time) 매크로를 사용해요.

SQL 어노테이션 쿼리 예시

SELECT time, title, description
FROM events
WHERE $__timeFilter(time)
ORDER BY time ASC

SQL 범위 어노테이션 예시

기간이 있는 이벤트를 음영 영역으로 표시하려면 시작 시간과 종료 시간을 모두 반환해요.

SELECT time, end_time, description, tags
FROM maintenance_windows
WHERE $__timeFilter(time)
ORDER BY time ASC

필드 매핑을 구성해요.

  • Text: description
  • Tags: tags
  • TimeEnd: end_time

어노테이션에서 템플릿 변수 사용

대시보드 변수 선택에 따라 어노테이션을 필터링하려면 어노테이션 쿼리에서 템플릿 변수를 사용할 수 있어요. 예를 들어:

SELECT title, description
FROM events
WHERE $timeFilter AND environment = '$environment'
ORDER BY time ASC

어노테이션이 나타나지 않거나 오류가 발생하면 InfluxDB 데이터 소스 문제 해결을 참고하세요.

더 알아보기 (Learn more)