Grafana 대시보드 개요

Sophonz가 수집한 OpenTelemetry 원격 측정 데이터를 Grafana에서 시각화하는 방법을 설명합니다.

Sophonz는 OpenTelemetry 기반으로 트레이스, 메트릭, 로그를 수집합니다. 수집된 데이터는 ClickHouse와 Prometheus에 저장되고, Grafana 대시보드를 통해 실시간으로 시각화할 수 있습니다. 세션 대시보드에서는 사용자 한 명의 화면 이동과 요청을 따라가다 그 요청이 지나간 서버와 로그까지 한 흐름으로 이어서 볼 수 있습니다.

데이터 흐름

앱에서 보낸 텔레메트리는 ClickHouse에 저장되고, Grafana 대시보드는 저장된 데이터를 조회해 보여 줍니다.

grafana-pipeline
  • Sophonz SDK가 앱에서 트레이스·로그·메트릭을 OTLP 형식으로 전송합니다.
  • OpenTelemetry Collector가 데이터를 받아 배치 처리 후 각 스토리지로 내보냅니다.
    • 트레이스 → ClickHouse (sophonz_traces 데이터베이스)
    • 로그 → ClickHouse (sophonz_logs 데이터베이스)
    • 스팬 메트릭 → ClickHouse (sophonz_metrics_* 테이블)
    • 세션 집계 → ClickHouse (stored_analysis_session 테이블)
  • Grafana는 ClickHouse 및 Prometheus 데이터소스를 통해 저장된 데이터를 조회하고 대시보드를 렌더링합니다.

프로비저닝된 대시보드

Sophonz는 v3 대시보드 7개를 Grafana에 넣어 줍니다. 웹·iOS·안드로이드를 플랫폼별로 나누지 않고, 한 대시보드에서 serviceNamespace(프로젝트)와 serviceName(앱) 변수로 고릅니다.

대시보드uid무엇을 보나
Sophonz Service (v3)sophonz-service-v3요청 흐름, KPI, 웹 바이탈, 트레이스, 에러 그루핑, 화면 분석, 세션 목록
Session (v3)sophonz-session-v3세션 목록과 선택한 세션의 타임라인·화면 흐름·트레이스
Sophonz Session Listsophonz-session-list-v3필터가 많은 세션 목록
Sophonz Session Detailsophonz-session-detail-v3세션 하나의 타임라인·화면 흐름·서비스 흐름·트레이스
Sophonz Tracessophonz-traces-v3트레이스·스팬 검색과 간트 뷰
Sophonz Logssophonz-logs-v3OpenTelemetry 로그 검색
Request Map (v3)sophonz-requestmap-v3요청 응답 시간 히트맵
Sophonz Service (v3) — 요청 흐름과 KPI부터 웹 바이탈, 트레이스, 에러, 화면, 세션까지

카드를 누르면 해당 대시보드 설명으로 이동합니다.

Sophonz Service (v3) 대시보드 화면
Sophonz Service (v3)
sophonz-service-v3

요청 흐름, KPI, 웹 바이탈, 트레이스, 에러, 화면, 세션.

Session (v3) 대시보드 화면
Session (v3)
sophonz-session-v3

세션 목록과 고른 세션의 타임라인·화면 흐름·트레이스.

Sophonz Session List 대시보드 화면
Sophonz Session List
sophonz-session-list-v3

사용자·디바이스·버전 필터가 붙은 세션 목록.

Sophonz Session Detail 대시보드 화면
Sophonz Session Detail
sophonz-session-detail-v3

세션 하나의 타임라인·화면 흐름·서비스 흐름·트레이스.

Sophonz Traces 대시보드 화면
Sophonz Traces
sophonz-traces-v3

트레이스·스팬 검색과 간트 뷰.

Sophonz Logs 대시보드 화면
Sophonz Logs
sophonz-logs-v3

심각도별 로그 볼륨과 로그 검색.

Request Map (v3) 대시보드 화면
Request Map (v3)
sophonz-requestmap-v3

요청 응답 시간 히트맵.

패널별 쿼리와 계산 방식은 대시보드 상세에, 커스텀 패널의 옵션과 JSON은 커스텀 패널에 있습니다.

세션 보기

스팬마다 sessionID가 붙어 있어서, 세션 하나를 기준으로 프론트엔드 동작과 백엔드 트레이스를 함께 봅니다. 세션을 다루는 대시보드는 세 개입니다.

대시보드쓰는 때
Session (v3)목록에서 세션을 고르고 바로 아래에서 그 세션을 봅니다
Sophonz Session List사용자·디바이스·앱 버전 같은 필터로 세션을 찾습니다
Sophonz Session Detail세션 하나를 깊게 봅니다

Session Detail에서 볼 수 있는 것은 다음과 같습니다.

  • Session Timeline — 세션의 스팬을 render·xhr·longtask·webvitals 같은 유형별 레인으로 한 시간축에 늘어놓습니다.
  • Screen Flow — 화면 사이 이동을 그래프로 그립니다. 화면을 누르면 타임라인이 그 화면에 머문 구간으로 확대됩니다.
  • Service Flow — 세션의 요청이 거쳐 간 서버와 그 안의 컴포넌트(핸들러, Prisma, pg 등)를 노드와 엣지로 잇습니다.
  • 트레이스 리스트와 간트 뷰 — 타임라인이나 목록에서 고른 트레이스를 스팬 단위로 펼치고, 그 트레이스의 로그로 넘어갑니다.

패널 구성은 대시보드 상세에, 각 패널의 동작은 커스텀 패널에 있습니다.

직접 쿼리하기

대시보드에 없는 질문은 ClickHouse에 SQL로 직접 묻습니다. 데이터소스는 대시보드와 같은 grafana-clickhouse-datasource이고, Grafana Explore나 새 패널의 쿼리 편집기에서 씁니다.

테이블한 행이
sophonz_traces.distributed_sophonz_index_v2스팬 하나
sophonz_traces.distributed_sophonz_error_index_v2에러 하나
sophonz_traces.stored_analysis_session세션 집계 상태
sophonz_logs.distributed_logs_v2로그 레코드

기존 대시보드의 패널 쿼리를 복사해 시작하는 편이 빠릅니다. 컬럼 폴백과 매크로, 집계할 때 틀리기 쉬운 점은 대시보드 상세의 쿼리 규칙을 참고하세요.

Sophonz 대시보드와의 관계

Grafana는 SRE·운영자를 위한 전문 쿼리 도구입니다. 개발자와 PM은 Sophonz Dashboard에서 동일한 관측 데이터를 제품 UI로 소비합니다.

grafana-layers

Grafana Provisioning 서비스는 Sophonz 앱·프로젝트 메타를 Grafana 데이터소스·폴더·대시보드로 자동 투영하며, Sophonz Dashboard에 임베드할 차트 URL도 발급합니다.

대시보드 접근

Grafana에는 https://grafana.example.com으로 접속합니다. 인증은 OAuth2/OIDC로 처리되며, Sophonz 계정으로 로그인하면 자동으로 Grafana 세션이 시작됩니다.

NOTE — 자동 새로고침

프로비저닝 설정(updateIntervalSeconds: 10)에 따라 대시보드 파일이 추가·변경되면 Grafana가 10초 이내에 자동으로 반영합니다. 별도의 재시작 없이 새 대시보드를 추가할 수 있습니다.

데이터소스

데이터소스플러그인용도
ClickHousegrafana-clickhouse-datasource트레이스, 로그, 스팬 메트릭 조회 (기본)
ClickHouse-Altinityvertamedia-clickhouse-datasource보조 ClickHouse 쿼리
Prometheus내장인프라·애플리케이션 메트릭
PostgreSQL내장애플리케이션 관계형 데이터

대시보드 프로비저닝 방법과 데이터소스 설정 파일 내용은 대시보드 설정을 참고하세요.