여섯 패널이 전부 다른 질문에 답하고 있었다

목표

결함이 든 대시보드 하나를 받아 계산값·널 처리·스택·계열 수·제목과 설명을 고치고, 같은 결함을 다음 대시보드에서도 잡는 검사기를 만들어 통과시킵니다.

왜 중요한가

대시보드가 조용히 틀리는 자리는 쿼리가 아니라 패널 옵션이다. 쿼리는 맞는데 숫자 하나짜리 패널이 평균을 보여 주고 있으면, 20분짜리 급증은 여섯 시간 평균 속에서 사라진다. 빠진 점을 이어 그리면 수집이 끊긴 사실 자체가 지워지고, 계열을 쌓으면 맨 위 선을 개별 값으로 읽게 된다. 셋 다 '틀린 값' 이 아니라 '묻지 않은 질문의 정확한 답' 이라서, 보는 사람은 자기가 틀리게 읽고 있다는 것을 알 수 없다. 그래서 패널마다 어떤 질문에 답하는지를 설명으로 못박고, 그 약속을 검사기로 지키게 만든다.

단계

1. lab-start-grafana 로 Grafana 를 띄우고, 결함이 든 대시보드 /opt/lab/gfd/gfd-misread/broken.json 를 고치지 말고 그대로 Grafana 에 올리세요(uid 는 파일에 적힌 gfd-misread, 패널 6개). curl 로 /api/dashboards/db 에 POST 하면 됩니다.
2. 1번 패널(요청률)은 지금 평균을 보여 줍니다. 지나간 구간을 하나 골라(1시간 이상, 끝은 지금보다 앞) 그 구간에서 sum(rate(http_requests_total{job="shop-api"}[5m])) 의 마지막 값·평균·최댓값을 직접 재고, /root/gfd-misread/02-calc.txt 에 start= end= last= mean= max= 다섯 줄로 적으세요(start·end 는 epoch 초). 그리고 1번 패널의 계산값을 lastNotNull 로 바꿔 저장하세요.
3. /root/gfd-misread/03-null.txt 에 connected= none= zero= 세 줄을 적으세요. 각 줄은 그 널 처리 선택이 보는 사람에게 무엇을 주장하는지를 40자 이상으로 설명해야 하고, 세 줄은 서로 달라야 합니다. 그리고 2번 패널(대기열)의 spanNulls 를 false 로 바꿔 저장하세요.
4. 3번 패널(핸들러별 요청률)은 계열을 쌓아 그립니다. 지나간 시각을 하나 골라 그 순간의 전체 합과 /api/orders 한 핸들러의 값을 각각 재어 /root/gfd-misread/04-stack.txt 에 at= total= orders= 세 줄로 적으세요(at 은 epoch 초). 그리고 3번 패널의 stacking.mode 를 none 으로 바꿔 저장하세요.
5. 4번 패널(핸들러 지연)의 쿼리는 핸들러마다 하나씩 계열을 돌려줍니다. 그 개수를 세어 /root/gfd-misread/05-series.txt 의 before= 에 적고, 이 패널이 '지금 가장 느린 핸들러의 p95 는 얼마인가' 하나에 답하도록 쿼리를 고쳐 저장한 뒤 고친 쿼리의 계열 수를 after= 에 적으세요.
6. 여섯 패널 모두 제목을 무엇을 보는 패널인지 알 수 있게 고치고(그래프 같은 이름 금지), 설명에는 그 패널이 답하는 질문 문장을 물음표로 끝나게 적으세요(12자 이상, 패널마다 다르게). 고친 대시보드를 저장하세요.
7. /root/gfd-misread/lint.py 를 만드세요. 대시보드 JSON 파일 경로를 인자로 받아 아래 다섯 규칙의 위반을 한 줄에 하나씩(R1~R5 로 시작) 출력하고, 위반이 하나라도 있으면 종료 코드 1 로 끝나야 합니다. R1 stat 패널의 계산값에 평균이 들어 있다 · R2 spanNulls 가 참이다 · R3 stacking.mode 가 normal 이다 · R4 설명이 물음표로 끝나지 않는다 · R5 제목이 비었거나 그래프·패널·차트 다. 원본 /opt/lab/gfd/gfd-misread/broken.json 에 돌려 다섯 규칙이 모두 잡히는지 확인하세요.
8. Grafana 에 올라간 지금의 대시보드를 그대로 내려받아 /root/gfd-misread/fixed.json 에 저장하고(.dashboard 본문만), 검사기를 돌려 위반 0 · 종료 코드 0 인 것을 확인하세요. 그리고 /root/gfd-misread/08-review.md 에 R1= 부터 R5= 까지 다섯 줄로 무엇을 왜 고쳤는지 각 30자 이상 적으세요.

참고

• Grafana 는 lab-start-grafana 로 켭니다(몇 초 걸립니다). 웹 프리뷰 3000번 포트로 눈으로도 확인해 보세요.
• 결함이 든 원본 대시보드는 /opt/lab/gfd/gfd-misread/broken.json 에 있습니다. 이 파일은 고치지 말고 읽기만 하세요 — 8단계에서 다시 씁니다.
• 대시보드를 저장하는 API 는 POST /api/dashboards/db 이고 본문은 {"dashboard": ..., "overwrite": true} 입니다.
• 구간 질의는 /api/v1/query_range, 한 순간의 값은 /api/v1/query 에 time= 을 함께 보냅니다. 두 경로 모두 /api/datasources/proxy/uid/<uid>/ 뒤에 붙여 Grafana 를 거쳐 던질 수 있습니다.
• 흔한 실수 ① 고친 뒤 저장하지 않는 것. 화면에서 바꿔도 API 로 저장하지 않으면 채점기가 보는 것은 옛 판입니다.
• 흔한 실수 ② 구간을 지금 기준으로 잡는 것. 지나간 절대 시각으로 못박아야 다시 재도 같은 값이 나옵니다.
• [패널 옵션](https://grafana.com/docs/grafana/latest/visualizations/panels-visualizations/configure-panel-options/) · [표준 옵션](https://grafana.com/docs/grafana/latest/visualizations/panels-visualizations/configure-standard-options/) · [대시보드 JSON 모델](https://grafana.com/docs/grafana/latest/visualizations/dashboards/build-dashboards/view-dashboard-json-model/) · [대시보드 HTTP API](https://grafana.com/docs/grafana/latest/developer-resources/api-reference/http-api/dashboard/) · [Prometheus 질의 API](https://prometheus.io/docs/prometheus/latest/querying/api/)

단계 8개

1. 고치기 전의 상태를 화면에 올린다
2. 숫자 하나짜리 패널은 무엇을 계산한 값인가
3. 빠진 점을 잇는 것도 주장이다
4. 쌓아 올린 맨 위 선은 어느 계열도 아니다
5. 값 하나를 묻는 패널에 계열이 넷 오면
6. 제목과 설명이 그 패널의 질문이다
7. 같은 결함을 다음 대시보드에서도 잡는다
8. 고친 대시보드가 스스로의 검사기를 통과한다