OpenTSDB 어노테이션

OpenTSDB 어노테이션 (OpenTSDB annotations)

어노테이션(annotations)은 그래프 위에 이벤트 정보를 겹쳐 표시해 메트릭 변화에 컨텍스트를 제공해요. OpenTSDB 데이터 소스는 메트릭 특정 어노테이션과 OpenTSDB에 저장된 전역 어노테이션을 모두 지원해요. Grafana 어노테이션에 대한 일반 정보는 "Annotate visualizations" 문서를 참고하세요.

출처: 문서

본문

어노테이션 유형

Grafana가 어노테이션을 검색하는 방식

어노테이션 쿼리를 구성하면 Grafana가 지정된 메트릭의 OpenTSDB를 쿼리해 그 메트릭의 시계열과 연결된 어노테이션을 가져와요. 쿼리에는 globalAnnotations=true 파라미터가 포함되어, 활성화 시 Grafana가 전역 어노테이션도 검색하게 해요. Grafana는 각 어노테이션의 description 필드를 어노테이션 텍스트로 표시해요.

어노테이션 쿼리 구성

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

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 드롭다운에서 OpenTSDB 데이터 소스를 선택해요.
11. 어노테이션 쿼리와 필드 매핑을 구성해요.
12. (선택) Test annotation query를 클릭해 쿼리가 제대로 동작하는지 확인해요.
13. 쿼리 설정을 마치면 Close를 클릭해요.
14. Save를 클릭해요.
15. (선택) 변경 사항 설명을 입력해요.
16. Save를 클릭하고 Exit edit을 클릭해요.

어노테이션 쿼리 필드

예제 어노테이션 쿼리

애플리케이션 배포 추적 — 특정 앱의 배포 시점 모니터링:

• Name: App Deployments, OpenTSDB metrics query: deploy.myapp, Show Global Annotations: disabled

인프라 전역 이벤트 모니터링 — 네트워크 변경이나 데이터센터 유지보수 같은 시스템 전역 이벤트 캡처:

• Name: Infrastructure Events, OpenTSDB metrics query: events.infrastructure, Show Global Annotations: enabled

인시던트·장애 추적 — 인시던트 시작·해결 시간 표시:

• Name: Incidents, OpenTSDB metrics query: events.incident, Show Global Annotations: enabled

구성 변경 모니터링 — 구성 변경 적용 시점 추적:

• Name: Configuration changes, OpenTSDB metrics query: events.config, Show Global Annotations: disabled

여러 이벤트 유형 상관관계 — 단일 대시보드에 여러 어노테이션 쿼리를 추가해 서로 다른 이벤트 유형을 상관관계로 분석할 수 있어요. 예: deploy.* 메트릭용 "Deployments" 어노테이션, events.incident용 "Incidents", 전역 어노테이션 활성화된 "Maintenance". 이렇게 하면 배포·인시던트·유지보수 창이 메트릭 데이터와 어떻게 연관되는지 볼 수 있어요.

어노테이션이 표시되는 방식

어노테이션은 이벤트가 발생한 타임스탬프의 시계열 패널에 세로선으로 나타나요. 어노테이션 마커에 마우스를 올리면 어노테이션 이름(쿼리 구성에서), 이벤트 설명(OpenTSDB 어노테이션의 description 필드에서), 타임스탬프를 볼 수 있어요. 어노테이션 설정에서 서로 다른 어노테이션 쿼리에 다른 색상을 지정해 이벤트 유형을 구분할 수 있어요.

OpenTSDB에서 어노테이션 만들기

Grafana에 어노테이션을 표시하려면 먼저 OpenTSDB에서 만들어야 해요. OpenTSDB는 어노테이션 관리를 위한 HTTP API를 제공해요.

어노테이션 데이터 구조

전역 어노테이션 만들기

curl -X POST http://<OPENTSDB_HOST>:4242/api/annotation \
  -H "Content-Type: application/json" \
  -d '{
    "startTime": 1609459200,
    "description": "Production deployment v2.5.0",
    "notes": "Deployed new feature flags and performance improvements",
    "custom": {
      "version": "2.5.0",
      "environment": "production",
      "deployer": "jenkins"
    }
  }'

메트릭 특정 어노테이션 만들기

특정 시계열에 어노테이션을 연결하려면 tsuid를 포함해요:

curl -X POST http://<OPENTSDB_HOST>:4242/api/annotation \
  -H "Content-Type: application/json" \
  -d '{
    "startTime": 1609459200,
    "endTime": 1609462800,
    "tsuid": "000001000001000001",
    "description": "Server maintenance",
    "notes": "Scheduled maintenance window for hardware upgrade"
  }'

메트릭의 TSUID를 찾으려면 OpenTSDB /api/uid/tsmeta 엔드포인트를 사용해요.

프로그래매틱 어노테이션 생성

배포 파이프라인이나 모니터링 시스템에 어노테이션 생성을 통합해요. 배포 스크립트 예제:

#!/bin/bash
VERSION=$1
TIMESTAMP=$(date +%s)

curl -X POST http://opentsdb.example.com:4242/api/annotation \
  -H "Content-Type: application/json" \
  -d "{
    \"startTime\": $TIMESTAMP,
    \"description\": \"Deployed version $VERSION\",
    \"custom\": {
      \"version\": \"$VERSION\",
      \"environment\": \"production\"
    }
  }"

어노테이션 API에 대한 자세한 내용은 OpenTSDB annotation API 문서를 참고하세요.

어노테이션 문제 해결

어노테이션이 나타나지 않음: | Cause | Solution | | --- | --- | | 시간 범위에 어노테이션이 포함되지 않음 | 어노테이션 타임스탬프를 포함하도록 대시보드 시간 범위를 확장. | | 잘못된 메트릭 이름 | 어노테이션 쿼리의 메트릭 이름이 OpenTSDB의 어노테이션과 연결된 메트릭과 일치하는지 확인. | | 전역 어노테이션이지만 토글이 꺼져 있음 | TSUID가 없는 어노테이션이면 Show Global Annotations 활성화. | | 어노테이션 없음 | API로 OpenTSDB에 어노테이션이 존재하는지 확인: curl http://<OPENTSDB_HOST>:4242/api/annotation?startTime=&endTime= |

어노테이션 텍스트가 비어 있음 — 어노테이션이 표시되지만 설명 텍스트가 없어요. OpenTSDB에서 어노테이션 생성 시 description 필드를 채워야 해요. Grafana는 description 필드를 어노테이션 텍스트로 표시해요.

다음 단계

• Build queries: 어노테이션과 함께 메트릭 시각화.
• Use template variables: 동적 대시보드 생성.
• Set up alerting: 메트릭이 임계값을 넘으면 알림.

더 알아보기 (Learn more)

• OpenTSDB data source
• Annotate visualizations
• OpenTSDB annotation API
• Grafana Alerting for OpenTSDB