주석(Annotations) API

주석은 Grafana 데이터베이스(sqlite, mysql 또는 postgres)에 저장돼요. 주석은 조직 주석이 될 수 있으며, 주석 데이터 소스를 구성해 어떤 대시보드에서든 표시할 수 있어요 — 태그로 필터링돼요. 또는 대시보드의 패널에 연결되어 해당 패널에서만 표시될 수도 있어요.

⚠️ Grafana 13부터 /api 엔드포인트가 /apis 라우트로 대체되어 더 이상 사용되지 않게(deprecated) 되고 있어요. Grafana가 기존 API를 마이그레이션하는 동안 현재 사용 중인 레거시 API와 정확히 일치하지 않을 수 있어요. 이 변경으로 현재 설정이 중단되거나 깨지지는 않아요. 레거시 API는 비활성화되지 않으며 완전히 접근·사용 가능하지만, /api 라우트는 더 이상 업데이트되지 않아요. 자세한 내용은 "Grafana의 새 API 구조" 문서를 참조해요.

출처: 문서

본문

요구 사항

Grafana Enterprise를 사용 중이라면 일부 엔드포인트에 특정 권한이 필요해요. 자세한 내용은 "Role-based access control permissions" 문서를 참조해요.

주석 찾기

GET /api/annotations?from=1506676478816&to=1507281278816&tags=tag1&tags=tag2&limit=100

필요한 권한 — 서문의 참고를 참조해요.

Action	Scope
annotations:read	annotations:annotations:type:dashboards:dashboards:uid:folders:folders:uid:

예제 요청:

GET /api/annotations?from=1506676478816&to=1507281278816&tags=tag1&tags=tag2&limit=100 HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Basic YWRtaW...=

쿼리 매개변수:

from: epoch datetime (밀리초). 선택 사항.
to: epoch datetime (밀리초). 선택 사항.
limit: 숫자. 선택 사항 - 기본값은 100. 반환되는 결과의 최대 한도.
alertId: 숫자. 선택 사항. 지정된 경고에 대한 주석을 찾음.
dashboardId: 더 이상 사용되지 않음(deprecated). dashboardUID를 사용해요.
dashboardUID: 문자열. 선택 사항. 특정 대시보드에 범위가 지정된 주석을 찾음. dashboardUID가 있으면 dashboardId는 무시돼요.
panelId: 숫자. 선택 사항. 특정 패널에 범위가 지정된 주석을 찾음.
userId: 숫자. 선택 사항. 특정 사용자가 만든 주석을 찾음.
type: 문자열. 선택 사항. alert 또는 annotation. 경고 또는 사용자가 만든 주석을 반환함.
tags: 문자열. 선택 사항. 조직 주석을 필터링하는 데 사용. 조직 주석은 특정 대시보드나 패널에 연결되지 않은 주석 데이터 소스의 주석이에요. 여러 태그로 "AND" 필터링하려면 tags 매개변수를 여러 번 지정해요. 예: tags=tag1&tags=tag2.

예제 응답:

HTTP/1.1 200
Content-Type: application/json
[
    {
        "id": 1124,
        "alertId": 0,
        "dashboardUID": "uGlb_lG7z",
        "panelId": 2,
        "userId": 1,
        "userName": "",
        "newState": "",
        "prevState": "",
        "time": 1507266395000,
        "timeEnd": 1507266395000,
        "text": "test",
        "tags": [
            "tag1",
            "tag2"
        ],
        "data": {}
    },
    {
        "id": 1123,
        "alertId": 0,
        "dashboardUID": "jcIIG-07z",
        "panelId": 2,
        "userId": 1,
        "userName": "",
        "newState": "",
        "prevState": "",
        "time": 1507265111000,
        "text": "test",
        "tags": [
            "tag1",
            "tag2"
        ],
        "data": {}
    }
]

Grafana v6.4부터 지역(region) 주석은 이제 timeEnd 속성을 포함하는 하나의 엔터티로 반환돼요.

주석 생성

Grafana 데이터베이스에 주석을 생성해요. dashboardUid와 panelId 필드는 선택 사항이에요. 지정하지 않으면 조직 주석이 생성되며, Grafana 주석 데이터 소스를 추가한 어떤 대시보드에서든 조회할 수 있어요. 지역 주석을 만들 때는 timeEnd 속성을 포함해요.

time과 timeEnd의 형식은 밀리초 단위의 epoch 숫자여야 해요.

POST /api/annotations

필요한 권한 — 서문의 참고를 참조해요.

Action	Scope
annotations:create	annotations:annotations:type:dashboards:dashboards:uid:folders:folders:uid:

필수 JSON body 필드:

text: 주석 설명.

예제 요청:

POST /api/annotations HTTP/1.1
Accept: application/json
Content-Type: application/json

{
  "dashboardUID":"jcIIG-07z",
  "time":1507037197339,
  "timeEnd":1507180805056,
  "tags":["tag1","tag2"],
  "text":"Annotation Description"
}

예제 응답:

HTTP/1.1 200
Content-Type: application/json

{
    "message":"Annotation added",
    "id": 1,
}

v6.4 이전 버전에서는 이 HTTP 요청의 응답이 약간 달라요. 이전 버전에서는 지역을 생성할 때 endId도 함께 얻었지만, 6.4에서는 지역이 time과 timeEnd 속성을 가진 단일 이벤트로 표현돼요.

Graphite 형식으로 주석 생성

Graphite 호환 이벤트 형식을 사용해 주석을 생성해요. when과 data 필드는 선택 사항이에요. when을 지정하지 않으면 현재 시간이 주석 타임스탬프로 사용돼요. tags 필드는 Graphite 0.10.0 이전 형식(여러 태그를 공백으로 구분한 문자열)일 수도 있어요.

POST /api/annotations/graphite

필요한 권한 — 서문의 참고를 참조해요.

Action	Scope
annotations:create	annotations:type:organization

예제 요청:

POST /api/annotations/graphite HTTP/1.1
Accept: application/json
Content-Type: application/json

{
  "what": "Event - deploy",
  "tags": ["deploy", "production"],
  "when": 1467844481,
  "data": "deploy of main branch happened at Wed Jul 6 22:34:41 UTC 2016"
}

예제 응답:

HTTP/1.1 200
Content-Type: application/json

{
    "message":"Graphite annotation added",
    "id": 1
}

주석 업데이트

PUT /api/annotations/:id

지정된 id와 일치하는 주석의 모든 속성을 업데이트해요. 특정 속성만 업데이트하려면 Patch Annotation 작업을 고려해요.

필요한 권한 — 서문의 참고를 참조해요.

Action	Scope
annotations:write	annotations:annotations:type:dashboards:dashboards:uid:folders:folders:uid:

예제 요청:

PUT /api/annotations/1141 HTTP/1.1
Accept: application/json
Authorization: Bearer <SERVI...KEN>
Content-Type: application/json

{
  "time":1507037197339,
  "timeEnd":1507180805056,
  "text":"Annotation Description",
  "tags":["tag3","tag4","tag5"]
}

예제 응답:

HTTP/1.1 200
Content-Type: application/json

{
    "message":"Annotation updated"
}

주석 부분 업데이트 (Patch)

PATCH /api/annotations/:id

지정된 id와 일치하는 주석의 하나 이상의 속성을 업데이트해요.

이 작업은 현재 text, tags, time, timeEnd 속성 업데이트를 지원해요.

필요한 권한 — 서문의 참고를 참조해요.

Action	Scope
annotations:write	annotations:annotations:type:dashboards:dashboards:uid:folders:folders:uid:

예제 요청:

PATCH /api/annotations/1145 HTTP/1.1
Accept: application/json
Authorization: Bearer <SERVI...KEN>
Content-Type: application/json

{
  "text":"New Annotation Description",
  "tags":["tag6","tag7","tag8"]
}

예제 응답:

HTTP/1.1 200
Content-Type: application/json

{
    "message":"Annotation patched"
}

ID로 주석 삭제

DELETE /api/annotations/:id

지정된 id와 일치하는 주석을 삭제해요.

필요한 권한 — 서문의 참고를 참조해요.

Action	Scope
annotations:delete	annotations:annotations:type:dashboards:dashboards:uid:folders:folders:uid:

예제 요청:

DELETE /api/annotations/1 HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer <SERVI...>

예제 응답:

HTTP/1.1 200
Content-Type: application/json

{
    "message":"Annotation deleted"
}

주석 태그 찾기

GET /api/annotations/tags

주석에서 생성된 모든 이벤트 태그를 찾아요.

필요한 권한 — 서문의 참고를 참조해요.

Action	Scope
annotations:read	N/A

예제 요청:

GET /api/annotations/tags?tag=out HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Basic YWRtaW...=

쿼리 매개변수:

tag: 선택 사항. 태그를 필터링하는 데 사용할 수 있는 문자열.
limit: 선택 사항. 기본값은 100인 숫자. 반환되는 결과의 최대 한도.

예제 응답:

HTTP/1.1 200
Content-Type: application/json

{
    "result": {
        "tags": [
            {
                "tag": "outage",
                "count": 1
            }
        ]
    }
}

더 알아보기 (Learn more)

대시보드에 주석 추가하고 관리하기
주석 데이터 소스 구성
Grafana의 새 API 구조