그래프는 '언제' 까지만 답한다

한 줄 요약

그래프는 '언제' 까지만 답한다. '왜' 는 지표 바깥의 사건이고, 주석은 그 사건을 같은 시간축 위에 올려 다음 사람이 혼자 답을 찾게 해 준다.

왜 이게 필요했나

새벽 세 시에 호출을 받은 사람이 대시보드를 연다. 오류율이 02:10 부터 꺾여 올라가 있다. 여기까지는 그래프가 답해 준다. 그다음 질문 — "그 시각에 무슨 일이 있었나" — 에는 그래프가 답하지 못한다. 그래서 사람은 다른 창을 연다. 배포 파이프라인의 기록, 채팅방의 스크롤, 설정 저장소의 커밋 목록. 세 곳의 시계가 서로 다르고 시간대도 다르다. 원인을 찾는 데 걸린 20분 중 15분이 이 왕복에 들어간다.

주석은 그 왕복을 없앤다. 배포가 끝날 때 파이프라인이 한 줄을 그래프에 남겨 두면, 다음 사람은 오류율이 꺾인 자리 바로 아래에서 세로줄 하나를 보게 된다. 그 줄에 버전과 사람과 되돌리는 법이 적혀 있으면 조사 대신 조치로 바로 넘어갈 수 있다.

중요한 것은 이것이 사후에 만들 수 없는 기록이라는 점이다. 배포가 언제 끝났는지는 그때 기록해야 남는다. 한 달 뒤에 "그때 배포가 있었나" 를 되짚으려면 결국 파이프라인 로그를 뒤져야 하고, 그 로그는 대개 보존 기간이 지나 있다.

어떻게 동작하나

Grafana 의 주석은 시간 위의 사건 하나다. 한 점일 수도 있고(time 만), 구간일 수도 있다(time 과 timeEnd). 만드는 길은 셋이다 — 패널 위에서 직접 달기, HTTP API 로 넣기, 그리고 다른 곳에 이미 있는 사건을 질의해서 가져오기.

API 로 만들 때 쓰는 자리는 POST /api/annotations 다. 공식 문서는 필수 필드가 text 하나이고, dashboardUID 와 panelId 는 선택이며 적지 않으면 조직 전체 주석이 된다고 적는다. 시각은 밀리초 단위의 에포크 정수이고, 구간 주석을 만들 때는 timeEnd 를 함께 넣는다. 만들고 나면 응답에 id 가 돌아오고, 그 뒤로는 GET /api/annotations 로 다시 읽을 수 있다. 읽을 때는 dashboardUID 나 tags 로 거를 수 있고, 태그를 여러 번 적으면 모두 가진 것만(AND) 걸러진다.

대시보드 쪽에는 주석 질의가 있다. 대시보드 JSON 의 annotations.list 에 항목을 두고 태그를 지정해 두면, 그 대시보드를 열 때 Grafana 가 그 태그가 붙은 주석을 가져와 패널 위에 올린다. 항목마다 이름과 색과 켜짐/꺼짐이 있어서, 화면 위쪽의 토글로 "배포만 보기" 나 "장애 구간만 보기" 를 켜고 끌 수 있다. 주석을 태그로 분류해 두는 값어치가 여기서 나온다 — 종류가 섞여 있으면 토글이 아무 쓸모가 없다.

다만 주석이 모든 패널에 그려지지는 않는다. 공식 문서는 주석을 지원하는 시각화가 Time series, State timeline, Candlestick 이라고 적는다. 통계 한 칸짜리 패널에는 올릴 자리가 없다. 주석을 쓰려고 만든 대시보드라면 적어도 하나는 시간축이 있는 패널이어야 한다.

사람이 손으로 다는 주석과 파이프라인이 자동으로 다는 주석은 성격이 다르다. 손으로 다는 것은 조사 중에 알아낸 것을 그 자리에 붙여 두는 용도라 문장이 자유롭다. 자동으로 다는 것은 빠짐없이 남는다는 것이 전부라 형식이 고정되어야 한다. 자동 기록을 사람 손에 맡기면 바쁜 날 빠지고, 하필 그날이 원인을 찾아야 하는 날이다.

그래서 자동 기록기를 만들 때는 두 가지를 정해 둔다. 하나는 무엇을 적을 것인가 — 버전, 배포한 사람(또는 파이프라인), 되돌리는 명령 한 줄. 이 셋이 없으면 주석을 본 사람이 결국 다른 창을 열어야 한다. 다른 하나는 쏘기 전에 찍어 볼 수 있는가 — 파이프라인 안에서만 도는 스크립트는 고장 났을 때 확인하기가 어렵다. 보낼 본문을 그대로 출력하는 모드를 두면 사람이 눈으로 검사할 수 있고, 시험도 부작용 없이 돌릴 수 있다.

이 환경에서 확인할 수 있는 것과 없는 것을 적어 둔다. 확인할 수 있는 것 — 주석이 실제로 기록됐는가(POST 의 응답 id 를 GET 으로 다시 읽어 대조), 시각과 구간이 맞는가, 태그가 붙었는가, 대시보드의 annotations.list 에 그 태그를 가져오는 질의가 선언됐는가, 자동 기록기가 보내려는 본문이 어떤 모양인가. 확인할 수 없는 것 — 주석이 화면에 정말 세로줄로 그려지는가. 패널은 브라우저가 그리고 이 파드에는 이미지 렌더러 플러그인이 없다. 그래서 이 실습의 채점은 전부 API 와 대시보드 모델로만 하고, 그림 자체는 웹 미리보기로 열어 눈으로 확인해야 한다. 질의가 선언돼 있고 그 태그로 주석이 실제로 조회된다면 그려질 조건은 갖춘 것이지만, 그것과 '그려졌다' 는 같은 말이 아니다.

현장에서 만나는 모습

배포 주석을 켜 둔 팀에서 가장 자주 듣는 말은 "세로줄 바로 뒤에 꺾였네" 다. 그 한 문장이 조사의 첫 30분을 없앤다. 반대로 주석을 켜지 않은 팀에서는 같은 장애를 두고 "배포 때문 아니냐" 와 "그때 배포 없었다" 가 20분 동안 오간다.

주석을 켜 놓고도 못 쓰는 경우도 있다. 어떤 팀은 배포 주석의 본문이 커밋 해시 하나뿐이었다. 새벽에 그 해시를 받은 사람이 할 수 있는 일은 저장소를 여는 것뿐이었고, 되돌리는 명령은 결국 다른 사람을 깨워서 물었다. 주석은 다음 사람이 그 자리에서 행동할 수 있는가 로 내용을 정해야 한다.

구간 주석이 특히 값어치가 있는 자리는 사후 회고다. 장애의 시작과 끝을 구간으로 남겨 두면 그 구간을 기준으로 에러 버짓 소모를 다시 계산할 수 있고, 다음 달에 "그 장애가 몇 분이었지" 를 놓고 다투지 않아도 된다.

다음 실습에서 할 것

먼저 오류율 패널 하나짜리 대시보드를 만들어 그래프만으로는 원인을 알 수 없다는 것을 확인한다. 그다음 배포를 주석으로 남기고 API 로 다시 읽어 대조하고, 시작과 끝이 있는 구간 주석으로 장애 시간을 표시한다. 태그로 둘을 갈라 대시보드의 주석 질의가 각각을 가져오게 하고, 배포 파이프라인이 부를 자동 기록기를 만든다(보낼 본문을 찍어 보는 모드를 포함한다). 마지막으로 주석에 무엇을 적어야 다음 사람이 쓸 수 있는지를 형식으로 정해 지키고, 남은 주석을 시간순으로 다시 읽어 조사 기록과 결론을 남긴다.