클릭해서 만든 대시보드가 잃어버리는 대시보드다

한 줄 요약

대시보드의 진실은 파일에 있어야 한다. Grafana 의 데이터베이스는 그 파일을 그려 놓은 화면일 뿐이다.

왜 이게 필요했나

클릭으로 만든 대시보드가 사라지는 경로는 늘 같다.

1. 장애 중에 급히 패널을 몇 개 만든다. 유용하다.
2. 다음 주에도 그 대시보드를 연다. 팀에 링크를 공유한다.
3. 여섯 달 뒤 클러스터를 옮기거나 Grafana 를 다시 세운다.
4. 아무도 그 대시보드를 되살리지 못한다. 만든 사람은 이미 다른 팀이다.

여기에 조용한 손실이 하나 더 있다. 누군가 임계선을 바꾸거나 패널을 지워도 이력이 남지 않는다. "이 패널 원래 있지 않았나?" 라는 질문에 답할 방법이 없다.

어떻게 동작하나

대시보드를 파일로 두는 데는 두 개가 필요하다. 대시보드 JSON 과, 그 디렉터리를 보라고 알려 주는 제공자(provider) 파일이다. 이 둘을 헷갈리는 것이 첫 번째 관문이다.

# provisioning/dashboards/lab.yml — JSON 이 아니라 '어디를 보라' 는 지시다apiVersion: 1providers:  - name: lab    type: file    updateIntervalSeconds: 10    allowUiUpdates: false    options:      path: /root/graf/dashboards      # ← 여기 있는 *.json 이 대시보드가 된다

이렇게 제공된 대시보드는 API 응답의 meta.provisioned 가 true 로 나온다. 그 상태에서 대시보드를 API 로 덮어쓰려 하면 Grafana 가 Cannot save provisioned dashboard 로 거절한다. 화면과 파일이 어긋날 길을 막아 두는 것이다.

이미 데이터베이스에 같은 uid 의 대시보드가 있어도 괜찮다. 프로비저닝이 그것을 가져간다 — 클릭으로 만들어 둔 대시보드를 파일로 옮기는 일이 그래서 가능하다. 만들 때는 UI 로 편하게 만들고, 끝나면 JSON 을 꺼내 파일로 굳히면 된다.

uid 는 주소다

uid 를 고정하는 것이 이 작업의 핵심이다. 대시보드 링크가 /d/shop-api/... 이므로 uid 가 곧 주소이고, 알림·문서·북마크·다른 대시보드의 링크가 전부 그 값을 가리킨다. 내보낸 JSON 에서 uid 를 지우고 다시 넣으면 같은 대시보드가 두 개가 되고, 링크는 옛 것을 가리킨 채로 남는다.

흔한 착각

"export 한 JSON 을 그대로 커밋하면 끝이다." 그 JSON 안에는 데이터소스가 uid 로 박혀 있다. 환경마다 uid 가 다르면 다른 환경에서는 빈 화면이 된다. uid 를 환경마다 같은 값으로 고정하거나, 데이터소스 자체를 변수로 빼야 한다.

"id 필드도 같이 커밋해도 된다." id 는 그 Grafana 안에서만 뜻이 있는 일련번호다. 옮긴 곳에서 다른 대시보드의 id 와 부딪힐 수 있다. 옮겨 다닐 JSON 에서는 uid 만 남기고 id 는 지우는 편이 안전하다.

실무에서 진짜 중요한 것

대시보드 JSON 의 diff 는 사람이 읽기 어렵다. 좌표와 필드가 잔뜩 움직여서, 리뷰가 "LGTM" 으로 흐르기 쉽다.

그래서 팀에서 정해 두면 좋은 규칙이 하나 있다 — 바뀐 대시보드가 답하는 질문을 PR 설명에 한 문장으로 적게 하는 것. 그 문장을 못 쓰면 그 변경은 대개 패널을 하나 더 붙인 것이고, 그건 이 코스가 처음에 말한 그래프 벽으로 가는 길이다.