Grafana 메트릭 차팅하기
개요
Grafana 데이터소스 프록시를 통해 PromQL 쿼리를 가져와 다크 테마의 Grafana 스타일 PNG 라인 차트를 렌더링합니다. (직접 Prometheus 네트워크 접근이 필요 없으며, Grafana SA 토큰만으로 충분합니다.) 수동 스크린샷과 달리 재현 가능하고 스크립트화할 수 있습니다. 결과를 Jira 이슈에 바로 첨부할 수 있습니다.
패널이 이미 보여주는 내용은 먼저 스냅샷을 찍으세요. Grafana Cloud 스택은 서버 사이드 렌더링을 제공하므로, gcx dashboards snapshot은 실제 패널을 PNG로 반환합니다. 이 스킬은 스냅샷이 제공할 수 없는 것, 즉 단일 패널에 인코딩되지 않은 쿼리 또는 시간 범위 간의 나란히 비교, 그리고 Image Renderer 플러그인이 없어 스냅샷이 오류를 내는 자체 호스팅 인스턴스를 위한 것입니다.
사전 점검
여기서 모든 Grafana 호출은 gcx를 통해 이루어집니다. 세션당 한 번 확인하세요:
command -v gcx >/dev/null || { echo "설치: brew install gcx"; exit 1; }
gcx config check || { echo "준비되지 않음: gcx login"; exit 1; }
그리기 전에 쿼리를 올바르게 작성하세요. 이 스킬은 전달받은 모든 PromQL을 렌더링하며, 잘못된 쿼리는 대시보드에서보다 더 나쁩니다: PNG는 아무도 재생하지 않는 고정된 증거로 티켓에 남고, 공식적으로 보입니다. 쿼리 자체에 대한 필수 배경 지식: grafana-dashboards 스킬의 PromQL 필수, 집계 함정, 분포 및 꼬리 읽기 섹션을 사용하세요. 비교 차트에서 문제가 되는 것들: rate 이후에 집계하고 절대 그 전에 하지 말 것, 롤아웃이 포드당 두 개의 시리즈를 남길 때 양쪽을 max by (...)로 감쌀 것, base-2 지수 히스토그램에 histogram_quantile을 절대 사용하지 말 것, 모든 하위 쿼리에 명시적인 step을 지정할 것.
사용 시기
- 2개 이상의 시리즈 비교: 버전 A vs B, 카나리 vs 컨트롤, 변경 전/후.
- Jira 티켓, MR 또는 인시던트 보고서에 증거 첨부.
- Grafana 패널 렌더링 실패 (
gcx dashboards snapshot오류: 해당 자체 호스팅 컨텍스트에 Image Renderer 없음).
사용하지 말아야 할 경우: 상호작용형 탐색(Grafana 사용), 단일 값/테이블 데이터, Grafana Cloud의 기존 패널 스크린샷 (gcx dashboards snapshot 사용).
설정 (한 번만)
matplotlib이 필요합니다. 없으면 격리된 venv를 사용하세요 (시스템 Python을 오염시키지 마십시오):
python3 -m venv ${CLAUDE_SKILL_DIR}/.venv
${CLAUDE_SKILL_DIR}/.venv/bin/pip install -q matplotlib
빠른 참조
| 필요 사항 | 플래그 |
|---|---|
| 어떤 데이터소스 | --datasource-uid (gcx datasources list 또는 패널 쿼리로 찾기) |
| 쿼리 | --expr 'PromQL' |
| 시간 창 | --start now-6h --end now --step 60 |
| 시리즈 레이블 소스 | --legend-key instance (기본값; 모든 메트릭 레이블) |
| 더 예쁜 이름 | --rename '{"raw-value":"Nice Name"}' |
| 시리즈별 평균/최소/최대 | 저장 후 stdout에 출력 (추가 쿼리 불필요) |
| 최고점에 콜아웃 | --annotate-max "text" |
| 어떤 Grafana | --grafana-url https://<host>: 해당 호스트를 가진 gcx 컨텍스트를 사용 (기본값: gcx의 현재 컨텍스트) |
| 어떤 gcx 컨텍스트 | --gcx-context <name> (기본값 $GCX_CONTEXT); URL 없이 이름으로 지정된 인스턴스의 경우 gcx config list-contexts에서 선택 |
| Jira에 첨부 | --attach-jira ABC-123 (아래 환경 변수 및 워크플로의 승인 게이트 참조) |
환경
하드코딩된 것은 없습니다: 호스트도, 주소도 없습니다. 셸 프로파일에 설정하세요.
| 변수 | 필요 용도 | 참고 |
|---|---|---|
GRAFANA_URL + GRAFANA_TOKEN | 정적 토큰 | 토큰은 GRAFANA_URL의 호스트로만 전송됨 (그 다음 GRAFANA_SERVICE_ACCOUNT_TOKEN, GTOK) |
GCX_CONTEXT | gcx | 강제할 gcx 컨텍스트, --gcx-context와 동일 |
JIRA_API_TOKEN JIRA_EMAIL JIRA_BASE | --attach-jira 전용 | 세 개 모두 필요, 기본값 없음 |
해결 순서는 모든 Grafana 스킬에서 동일합니다: --token; --gcx-context / $GCX_CONTEXT; --grafana-url ($GRAFANA_URL 호스트에 대한 환경 토큰, 해당 호스트를 제공하는 gcx 컨텍스트가 없으면 gcx login 실행하라는 메시지와 함께 종료); gcx의 현재 컨텍스트; gcx가 없을 때 환경 토큰. gcx를 통해 자체 OAuth 갱신이 적용되며, 이 스크립트는 자격 증명을 직접 읽거나 캐시하지 않습니다. 해결자는 각 스킬에 의도적으로 중복되어 있어, 어느 하나만 설치되어도 작동합니다.
워크플로
- 대시보드에서 데이터소스 UID와 PromQL을 가져옵니다 (
gcx api /api/dashboards/uid/<uid>,panels[*].targets[*].expr읽기) 또는 직접 쿼리를 작성합니다. - 스크립트를 실행합니다 (venv python을 통해). 색상은 시리즈 순서대로 Grafana 팔레트에서 자동 할당됩니다. 범례는 시리즈별 평균/최대값을 보여줍니다.
- 공유하기 전에 PNG를 눈으로 확인합니다.
- 선택적으로
--attach-jira로 Jira에 첨부합니다. 이는 전체 팀이 볼 수 있는 트래커 쓰기 작업입니다. 먼저ticket-conventions스킬의 승인 게이트를 따르십시오 (티켓 ID와 PNG를 보여주고 명시적인 승인을 기다리십시오). 업로드 실패는 0이 아닌 값으로 종료됩니다.
예제 (표준 예제: HAProxy 3.2 vs 2.7 노드 메모리)
VENV=${CLAUDE_SKILL_DIR}/.venv/bin/python
SKILL=${CLAUDE_SKILL_DIR}
export JIRA_API_TOKEN=$(zsh -l -c 'echo $JIRA_API_TOKEN') # 첨부하는 경우에만
export [email protected] JIRA_BASE=https://example.atlassian.net
DS_UID=abc123XYZ # `gcx datasources list`에서
$VENV $SKILL/plot_grafana.py \
--datasource-uid $DS_UID \
--expr '(1 - (node_memory_MemAvailable_bytes{instance=~"lb-edge-dc1-(1|4)"} / node_memory_MemTotal_bytes{instance=~"lb-edge-dc1-(1|4)"})) * 100' \
--start now-6h --step 60 \
--title "lb-edge - 노드 메모리 사용 % · 3.2 vs 2.7 (dc1, 마지막 6h)" \
--ylabel "메모리 사용 %" --ymin 0 --ymax 45 \
--rename '{"lb-edge-dc1-1":"HAProxy 3.2.20 (dc1-1)","lb-edge-dc1-4":"HAProxy 2.7.11 (dc1-4, control)"}' \
--annotate-max "reload: old+new worker coexist → node mem ~2x" \
--grafana-url https://grafana.example.com \
--out ./mem-3.2-vs-2.7.png \
--attach-jira ABC-123
일반적인 실수
- 확인되지 않은 쿼리로 차트를 그림 → 위의 PromQL 포인터를 참조하세요; 그럴듯한 잘못된 숫자가 오류가 아닌 실패 모드입니다.
- 프록시에서 401 → 정적 토큰의 경우 해당 호스트에 속하지 않습니다; gcx를 통한 경우 갱신 토큰이 만료되었습니다(약 한 달),
gcx login <context>를 실행하세요. - 시스템
python3사용 →ModuleNotFoundError: matplotlib. venv python을 사용하세요. - 여러 개를 예상했는데 빈 평평한 선 하나 →
--expr정규식이 단일 시리즈와 일치했습니다; 레이블 매처를 넓히세요. - 시리즈 이름이 없거나 모두 "series" →
--legend-key가 메트릭에 없는 레이블을 가리키고 있습니다; 있는 레이블을 선택하세요 (원시 쿼리 결과 확인). - 범례 이름에
:9100(또는:port) → 파생된 시리즈 이름에서 자동으로 제거되므로--rename은 깨끗한 호스트를 대상으로 합니다 (예:lb-edge-dc1-1,lb-edge-dc1-1:9100아님). 두 형식을 모두 나열할 필요가 없습니다. - 상대 시간은 숫자 하나와 단위 하나를 사용합니다 (s/m/h/d) (
now-90m,now-6h,now-2d). 복합 (now-1h30m), 주 (now-1w) 및 반올림 (now/d)은 지원되지 않습니다: 변환하세요 (now-90m,now-7d).