같은 0.42 가 420밀리초이기도 하고 0.42밀리초이기도 했다

목표

진짜 Grafana 에 패널을 올려 단위 식별자를 직접 넣고, 쿼리가 내는 값의 크기와 단위가 맞는지 질의로 확인하고, 축의 범위와 로그 축을 손으로 만진 뒤, 운영에서 걷어 온 대시보드의 단위·축 결함 넷을 고쳐 제출합니다.

왜 중요한가

대시보드의 숫자는 쿼리가 옳아도 화면에서 틀릴 수 있다. Grafana 의 단위는 표시 규칙이지 변환 규칙이 아니라서, 초로 나오는 값에 밀리초 단위를 붙이면 값은 그대로인 채 이름만 천 배 작아진다. 비율도 0..1 과 0..100 이 서로 다른 단위이고, 바이트도 1024 로 줄이는 쪽과 1000 으로 줄이는 쪽이 다른 단위다. 화면에 보이는 이름과 JSON 에 들어가는 식별자가 다르다는 것까지 알아야 이 일을 파일로 남길 수 있다. 축은 그다음 자리다 - 바닥을 0 으로 고정하지 않으면 두 배도 안 되는 변동이 절벽처럼 보이고, 천장을 박아 두면 사고가 통째로 잘린다. 이 실습의 목적은 단위 이름을 외우는 것이 아니라, 패널 하나를 보고 '이 숫자는 무엇으로 읽히는가' 를 물을 수 있게 되는 것이다.

단계

1. lab-start-grafana 로 Grafana 를 띄우고, /root/gfd-units/dash.json 에 uid 가 gfd-units 인 대시보드를 만들어 Grafana 에 올리세요. 패널은 하나이고 id 는 1, 타입은 timeseries, 제목은 p99 응답 시간 (단위 없음 - 비교용), 쿼리는 histogram_quantile(0.99, sum by (le) (rate(http_request_duration_seconds_bucket{job="shop-api"}[6h]))) 입니다. 이 패널에는 단위를 적지 마세요(뒤 단계에서도 그대로 둡니다 - 비교용입니다). 그리고 /root/gfd-units/01-readings.tsv 에 머리글 없이 세 줄, 각 줄은 탭으로 나눈 두 칸 <가정한 단위 식별자> <그 가정대로면 실제로 몇 초인가> 를 적으세요. 가정할 단위는 순서대로 s(초)·ms(밀리초)·m(분) 이고, 초로 환산한 값은 소수 여섯 자리까지 적습니다.
2. 같은 대시보드에 패널 셋을 더하세요. id 2 는 제목 p99 응답 시간, 쿼리 histogram_quantile(0.99, sum by (le) (rate(http_request_duration_seconds_bucket{job="shop-api"}[6h]))), id 3 은 제목 5xx 비율, 쿼리 sum(rate(http_requests_total{job="shop-api",status=~"5.."}[1h])) / sum(rate(http_requests_total{job="shop-api"}[1h])), id 4 는 제목 남은 디스크, 쿼리 node_filesystem_avail_bytes{job="node",mountpoint="/data"} 입니다. 셋 다 타입은 timeseries 이고, 각 패널의 fieldConfig.defaults.unit 에 그 값에 맞는 Grafana 단위 식별자를 적습니다. 지연은 초 단위로, 비율은 0 과 1 사이로, 디스크는 바이트로 나옵니다. 바이트는 1024 로 줄이는 쪽(IEC)을 쓰세요. 그리고 /root/gfd-units/02-units.tsv 에 머리글 없이 세 줄, 각 줄은 탭으로 나눈 세 칸 <패널 id> <단위 식별자> <이 단위를 고른 이유 15자 이상> 을 적으세요.
3. 같은 대시보드에 id 가 5 인 timeseries 패널을 더하세요. 제목은 p99 응답 시간 (ms) 이고, 같은 p99 를 밀리초 숫자로 내는 쿼리를 쓰고 단위 식별자는 밀리초 쪽을 씁니다. 그리고 /root/gfd-units/03-scale.tsv 에 머리글 없이 두 줄, 각 줄은 탭으로 나눈 두 칸 <단위 식별자> <그 패널의 쿼리가 실제로 내는 값> 을 적으세요. 첫 줄은 2단계의 초 패널, 둘째 줄은 이번 패널이고, 값은 소수 여섯 자리까지 적습니다.
4. 같은 대시보드에 id 가 6 인 timeseries 패널을 더하세요. 제목은 초당 요청 수, 쿼리는 sum(rate(http_requests_total{job="shop-api"}[5m])), 단위 식별자는 처리량 갈래의 requests/sec (rps) 이고, fieldConfig.defaults.min 을 0 으로 고정합니다. 반대로 2단계에서 만든 id 2 패널에는 max 를 넣지 마세요(넣었다면 지웁니다). 그리고 /root/gfd-units/04-axis.tsv 에 머리글 없이 세 줄, 각 줄은 탭으로 나눈 두 칸으로 rps_min·rps_max·swing_pct 를 차례로 적으세요. 앞의 둘은 최근 12시간 동안 이 쿼리가 낸 가장 작은 값과 가장 큰 값(소수 세 자리), swing_pct 는 (최댓값 빼기 최솟값) 나누기 최댓값 곱하기 100 입니다(소수 두 자리).
5. 같은 대시보드에 id 가 7 인 timeseries 패널을 더하세요. 제목은 지연과 오류 비율, 쿼리는 둘입니다 - refId 가 A 인 histogram_quantile(0.99, sum by (le) (rate(http_request_duration_seconds_bucket{job="shop-api"}[6h]))) (범례 이름 p99)와 refId 가 B 인 sum(rate(http_requests_total{job="shop-api",status=~"5.."}[1h])) / sum(rate(http_requests_total{job="shop-api"}[1h])) (범례 이름 5xx). 패널 전체의 단위는 초로 두고, fieldConfig.overrides 에 이름이 5xx 인 계열만 골라 단위를 0..1 비율로, custom.axisPlacement 를 right 로 지정하세요. 그리고 /root/gfd-units/05-override.tsv 에 머리글 없이 두 줄, 각 줄은 탭으로 나눈 세 칸 <범례 이름> <그 계열에 적용되는 단위 식별자> <축 위치> 를 적으세요. 축 위치는 left 또는 right 입니다.
6. 같은 대시보드에 id 가 8 인 timeseries 패널을 더하세요. 제목은 핸들러별 초당 요청 수, 쿼리는 sum by (handler) (rate(http_requests_total{job="shop-api"}[1h])), 단위는 처리량 갈래의 requests/sec (rps) 이고, fieldConfig.defaults.custom.scaleDistribution 을 {"type": "log", "log": 10} 으로 지정합니다. 이 패널에는 최솟값을 0 으로 고정하지 마세요. 그리고 /root/gfd-units/06-log.txt 에 네 줄을 적으세요 - top=<가장 큰 핸들러의 값>, bottom=<가장 작은 핸들러의 값>(둘 다 소수 세 자리), ratio=<top 나누기 bottom, 소수 두 자리>, loss=<로그 축으로 바꾸면서 잃는 것, 40자 이상>.
7. 같은 대시보드에 패널 둘을 더하세요. id 9 는 제목 디스크가 줄어드는 속도, 쿼리 - deriv(node_filesystem_avail_bytes{job="node",mountpoint="/data"}[1h]), 단위는 1024 로 줄이는 쪽의 초당 바이트입니다. id 10 은 제목 디스크가 바닥날 때까지, 쿼리는 남은 바이트를 줄어드는 속도로 나눈 것이고 단위는 초입니다. 둘 다 타입은 timeseries 입니다. 그리고 /root/gfd-units/07-derived.tsv 에 머리글 없이 세 줄, 각 줄은 탭으로 나눈 두 칸 <단위 식별자> <그 쿼리가 내는 값> 을 적으세요. 차례로 남은 바이트, 줄어드는 속도, 남은 시간이고 값은 소수 세 자리까지 적습니다.
8. /opt/lab/gfd/gfd-units/broken.json 은 운영에서 걷어 온 대시보드입니다(uid gfd-units-fix). 패널 넷 모두 단위나 축에 결함이 있습니다. 쿼리는 그대로 두어도 되고 바꿔도 되지만, 화면에 나오는 값과 단위가 서로 맞아야 합니다. 고친 대시보드를 uid gfd-units-fix 로 Grafana 에 올리세요. 4번 패널(초당 요청 수)의 축은 최솟값을 0 으로 고정하고 천장은 걷어 냅니다. 그리고 /root/gfd-units/08-report.tsv 에 머리글 없이 네 줄, 각 줄은 탭으로 나눈 세 칸 <패널 id> <결함 코드> <무엇이 틀렸었나, 20자 이상이고 숫자를 하나 이상 포함> 을 적으세요. 결함 코드는 scale(값의 크기와 단위가 어긋남)·category(단위 갈래가 틀림)·axis(축 때문에 잘림) 셋 중 하나이고, 줄은 패널 id 순서입니다.

참고

작업 디렉터리는 /root/gfd-units 입니다. Grafana 는 lab-start-grafana 로 띄우고, 웹 미리보기 3000번 포트로 눈으로도 볼 수 있습니다.
대시보드는 화면에서 만들어도 되고 API 로 올려도 됩니다. 채점기는 어느 쪽으로 만들었는지 묻지 않고 Grafana 에 올라간 결과만 봅니다. 올린 결과는 curl -s http://127.0.0.1:3000/api/dashboards/uid/gfd-units | jq '.dashboard.panels' 로 확인합니다.
패널의 datasource 는 비워 두세요. 데이터소스 uid 는 파드마다 다르게 만들어지고, 비워 두면 기본 데이터소스(Prometheus)를 씁니다. 굳이 적어야 한다면 curl -s localhost:3000/api/datasources | jq -r '.[0].uid' 로 얻습니다.
단위 식별자 표는 /opt/lab/gfd/gfd-units/unit-picker.md 에 있습니다 - 이 파드의 Grafana 에서 그대로 뽑은 것이라 화면 드롭다운과 같은 목록입니다. 8단계에서 고칠 대시보드는 /opt/lab/gfd/gfd-units/broken.json 입니다.
이 환경은 패널이 실제로 그려진 그림을 판정하지 못합니다(이미지 렌더러가 없습니다). 채점기는 대시보드 JSON 모델과 쿼리 결과만 봅니다. 눈으로 볼 것은 웹 미리보기로 직접 여세요.
흔한 실수: 단위만 바꾸고 쿼리를 그대로 두는 것. 단위는 값을 변환하지 않습니다.
흔한 실수: 축의 최댓값을 '보기 좋으라고' 박아 두는 것. 사고는 언제나 그 천장 위에서 일어납니다.
[Configure standard options](https://grafana.com/docs/grafana/latest/visualizations/panels-visualizations/configure-standard-options/) · [Configure overrides](https://grafana.com/docs/grafana/latest/visualizations/panels-visualizations/configure-overrides/) · [Time series - Axis options](https://grafana.com/docs/grafana/latest/visualizations/panels-visualizations/visualizations/time-series/) · [Dashboard JSON model](https://grafana.com/docs/grafana/latest/visualizations/dashboards/build-dashboards/view-dashboard-json-model/) · [Prometheus - Query functions](https://prometheus.io/docs/prometheus/latest/querying/functions/)

단계 8개

단위를 적지 않은 패널을 올리고, 같은 숫자를 세 가지로 읽어 본다
단위 식별자를 실제로 넣는다
단위는 값을 바꾸지 않는다 - 밀리초로 보이려면 무엇을 곱해야 하나
0 에서 시작해야 하는 축과, 천장을 씌우면 안 되는 축
한 패널에 단위가 다른 둘을 올린다
로그 축을 쓰는 자리와, 그때 잃는 것
응용 ① - 나눗셈의 결과에는 어떤 단위가 붙나
응용 ② - 운영 대시보드의 단위·축 결함을 전부 고쳐 제출한다