커스텀 패널
Sophonz가 직접 만들어 Grafana에 설치하는 6개 패널이 각각 무엇을 그리고 어떤 데이터를 요구하는지 정리합니다.
Grafana 기본 패널로는 그릴 수 없는 화면이 있습니다. 세션 하나의 스팬을 시간축에 늘어놓는 일, 트레이스가 지나간 서비스를 노드-엣지로 잇는 일, 화면 사이 이동을 그래프로 만드는 일은 모두 데이터 모양이 정해져 있어야 가능합니다. Sophonz는 그런 화면 6개를 패널 플러그인으로 만들어 Grafana에 설치합니다.
설치 방식
패널은 CDN에 버전별로 올라가 있고, Grafana가 시작할 때 GF_INSTALL_PLUGINS로 내려받습니다.
https://cdn.sophonz.com/release/grafana/plugins/<패널 id>/<버전>/<패널 id>.zip버전은 반드시 고정합니다. Grafana 스토리지가 emptyDir이라 재시작마다 플러그인을 다시 받는데, 부동 버전을 쓰면 재시작 한 번에 화면이 바뀔 수 있습니다.
서명하지 않은 플러그인이므로 GF_PLUGINS_ALLOW_LOADING_UNSIGNED_PLUGINS에도 같은 id를 넣어야 Grafana가 로드합니다.
패널 목록
아래 화면은 모두 공개 데모 조직에 실제로 배포된 패널을 찍은 것입니다. 카드를 누르면 해당 설명으로 이동합니다.
sophonz-kpi-panel값과 이전 기간 대비 증감, 배경 스파크라인.
sophonz-session-timeline-panel세션 하나의 스팬을 타입별 레인으로 나눠 시간축에 배치.
sophonz-session-timeline-graph-panel화면 이동 그래프. 에러가 난 화면은 빨갛게.
sophonz-service-flow-panel트레이스가 지나간 서비스와 호출 소요 시간.
sophonz-requestmap-panel응답 시간 히트맵. 색은 상태 코드, 진하기는 요청 수.
sophonz-dynamicxhr-panel요청 트래픽 애니메이션과 성공·실패 집계.
| 패널 | id | 쓰이는 대시보드 |
|---|---|---|
| Sophonz KPI | sophonz-kpi-panel | 서비스 |
| Session Timeline | sophonz-session-timeline-panel | 세션, 세션 상세 |
| Screen Flow | sophonz-session-timeline-graph-panel | 세션, 세션 상세 |
| Service Flow | sophonz-service-flow-panel | 세션 상세, 데모 |
| Request Map | sophonz-requestmap-panel | 서비스, Request Map |
| DynamicXHR Monitor | sophonz-dynamicxhr-panel | 서비스 |
Sophonz KPI
숫자 하나와 이전 기간 대비 증감, 그리고 스파크라인을 함께 보여주는 카드입니다.
쿼리를 3개 받습니다. 기본 stat 패널은 헤드라인 숫자·스파크라인·증감률을 모두 같은 시계열에서 뽑는데, 그러면 숫자가 기간 전체의 값이 아니게 됩니다. 실제 하루치 트래픽으로 재보면 시간 버킷별 고유 세션을 더한 값은 실제 고유 세션 수보다 31% 많고(버킷 경계를 걸친 세션이 두 번 세어집니다), 버킷 평균의 평균은 실제 평균보다 14% 큽니다.
그래서 이 패널은 값을 따로 묻습니다.
| 쿼리 | 역할 |
|---|---|
| A | 현재 기간의 값. 이 숫자가 카드에 그대로 표시됩니다 |
| B | 직전 동일 기간의 같은 값. 증감 화살표의 기준입니다 |
| C | 스파크라인용 시계열. 그리기만 하고 집계에는 쓰지 않습니다 |
B가 없으면 증감을 표시하지 않습니다. 이전 값이 0일 때도 마찬가지입니다 — 0에서 늘어난 비율은 무한대라 표시할 수 있는 숫자가 없습니다.
주요 옵션
| 옵션 | 설명 |
|---|---|
label | 카드 이름. 비우면 패널 제목을 씁니다 |
comparisonLabel | 증감 아래 설명. 예: vs 이전 24시간 |
unit / decimals | Grafana 단위 id(short, ms, percent 등)와 소수 자릿수 |
color | 카드 색. Sophonz 로고 3색은 #015AE4, #00D0CE, #FE52AF |
sentiment | 상승이 좋은 일인지. 증감 화살표 색을 정합니다. neutral이면 회색으로 두는데, 세션 수처럼 오르내림에 좋고 나쁨이 없는 지표에는 이게 정직합니다 |
showSparkline | 스파크라인 표시 여부 |
Session Timeline
세션 하나가 만든 스팬 전체를 시간축에 늘어놓습니다. render·event·xhr·fetch·error·crash 같은 스팬 타입별로 레인을 나눠서, 사용자가 무엇을 했고 그때 무엇이 느렸는지 한 화면에서 읽습니다.
Canvas로 그리기 때문에 스팬이 수천 개인 세션도 스크롤이 끊기지 않습니다.
ctrl/cmd+ 휠 — 확대·축소space+ 드래그 — 이동- 스팬 위에 올리면 이름·소요 시간·타입 툴팁
Screen Flow
세션의 화면 이동을 그래프로 만듭니다. 노드가 화면이고(방문 수 포함), 엣지가 이동입니다(횟수 포함). 에러가 난 화면은 빨갛게 표시합니다.
스팬을 선택하면 대시보드의 traceId와 spanId 변수에 값을 넣습니다. 아래쪽 간트 차트가 그 값을 보고 있으면, 그래프에서 화면을 고르는 것만으로 간트가 따라 움직입니다.
Service Flow
트레이스가 지나간 경로를 노드-엣지로 그립니다. 노드는 서비스이고, 클릭하면 그 안의 컴포넌트(Express 핸들러, Prisma, pg 클라이언트 등)로 펼쳐집니다.
엣지에는 호출 소요 시간이 붙습니다. 펼친 상태에서는 개별 스팬의 시간이, 접은 상태에서는 그 엣지가 대표하는 호출들의 평균이 표시됩니다.
노드는 세 계층으로 구분합니다.
| 계층 | 판별 기준 |
|---|---|
| Frontend | client.platform이 web/browser. 브라우저 SDK만 이 값을 붙이므로 추측이 아닙니다 |
| Infrastructure | 서비스 이름이 데이터스토어·브로커 패턴과 일치 (postgres, redis, kafka 등) |
| Backend | 나머지 |
간선은 시간 순서가 아니라 부모/자식 스팬 ID로 잇습니다. 브라우저와 서버 사이에는 시계 오차가 있어서, 시간으로 재구성하면 순서가 뒤집힐 수 있습니다.
트레이스 하나를 볼 때는 펼친 상태가, 세션 전체를 볼 때는 접은 상태가 읽기 좋습니다. expandAll 옵션으로 정합니다.
Request Map
HTTP·XHR 요청의 응답 시간을 시간축 히트맵으로 그립니다. 세로가 소요 시간, 가로가 시각이고, 셀 색은 그 구간에서 가장 많았던 상태 코드 계열(2xx/3xx/4xx/5xx), 진하기는 요청 수입니다.
드래그로 구간을 선택하면 대시보드 시간 범위가 그 구간으로 좁혀집니다.
DynamicXHR Monitor
요청 트래픽을 애니메이션으로 보여주는 패널입니다. 요청 하나가 화살 하나로 지나가고, 성공·실패 비율이 패널 양쪽에 숫자로 남습니다.
지표를 읽는 화면이라기보다 지금 트래픽이 흐르고 있는지를 한눈에 확인하는 용도입니다.
다국어
Grafana 대시보드는 다국어를 지원하지 않습니다. Grafana 11.2가 번역을 갖고 있는 건 자기 UI(메뉴, 설정 화면)뿐이고 그마저 한국어는 없습니다 — de-DE, en-US, es-ES, fr-FR, pt-BR, zh-Hans입니다.
패널 제목, 설명, 변수 이름, 텍스트 패널 내용은 모두 대시보드 JSON에 그대로 박힌 문자열이라 번역 대상이 아닙니다. 언어를 나누려면 대시보드 JSON을 언어별로 복제하는 수밖에 없고, 그러면 패널을 고칠 때마다 양쪽을 고쳐야 합니다.