패널 편집

패널 편집 화면은 대시보드 패널의 데이터 쿼리, 값 표시 형식, 시각화 옵션, 레이아웃, JSON 설정을 한 곳에서 조정하는 화면입니다. 타입별 조작법은 하위 문서로 분리했고, 예시는 Node CPU Utilization, Pod Inventory, Node CPU, Pod CPU Status Grid, Trace Latency Heatmap 실제 패널을 기준으로 캡처했습니다.

진입 방법

대시보드에서 기존 패널 우측 상단의 Panel actions 메뉴를 열고 Edit을 선택합니다. 새 패널을 만들 때는 대시보드 상단의 Add panel을 사용합니다. 패널 묶음은 Add row로 만들며, row는 일반 지표 패널과 달리 데이터 쿼리보다 그룹 접기와 배치가 중심입니다.

편집 화면은 크게 다섯 영역으로 나뉩니다.

영역	역할
상단 바	패널 제목, 편집용 시간 범위, 새로고침, 패널 타입, 저장/취소 버튼을 제공합니다.
미리보기	현재 draft 설정으로 패널이 어떻게 보이는지 확인합니다.
Data	datasource, query type, query target, query 실행 테스트를 조작합니다.
오른쪽 탭	`Fields`, `Visualization`, `Panel & Layout`, `JSON` 설정을 전환합니다.
저장 버튼	`Apply`, `Apply & Save`, `Discard`로 draft 반영 범위를 정합니다.

저장과 취소

버튼	동작
Discard	현재 편집 draft를 버리고 편집 화면을 닫습니다.
Apply	편집 화면의 draft를 현재 대시보드 화면에 반영합니다. 대시보드 저장까지 필요한 화면에서는 별도 저장 흐름을 확인합니다.
Apply & Save	draft를 적용하고 backend 저장까지 요청합니다.
Refresh	현재 편집용 시간 범위로 미리보기와 쿼리 결과를 다시 불러옵니다. 패널 정의 자체를 저장하지는 않습니다.

패널 타입을 바꾸면 같은 패널 id 안에서 모델이 새 타입에 맞게 정규화됩니다. 예를 들어 Trace 타입은 ClickHouse 계열 데이터에 맞게 datasource가 바뀔 수 있습니다. 타입 변경도 draft이므로 저장 버튼을 누르기 전까지 운영 대시보드에 확정되지 않습니다.

타입 선택

상단 Type 선택에서 패널 종류를 바꿉니다. 타입을 바꾸면 오른쪽 Visualization 탭의 입력 항목이 타입에 맞게 달라집니다.

타입	주 사용 상황
Time Series	시간 흐름에 따른 메트릭 변화, 이상탐지 overlay, series 비교를 볼 때
Bar	Time Series 계열 데이터를 막대 스타일로 비교할 때
Heatmap	시간과 bucket, label, value가 있는 밀도/분포 데이터를 볼 때
Scatter	trace duration처럼 행 단위 관측치를 x/y 점으로 볼 때
Pie	적은 수의 category 비중을 볼 때
Stat	하나 또는 여러 series의 최신값, 합계, 평균 같은 대표값을 볼 때
Gauge	단일 값이 기준 범위 안에서 어디에 있는지 볼 때
Table	로그, 이벤트, trace, ClickHouse 결과처럼 행과 열을 자세히 볼 때
Logs	로그성 텍스트 결과를 표시할 때
Status Grid	여러 대상의 정상/비정상 상태를 타일로 볼 때
Gantt	시작/종료/기간이 있는 작업, span, 배치 흐름을 시간 막대로 볼 때
Trace	trace 목록과 trace 요약을 볼 때

Data 탭

Data 영역은 모든 데이터 패널의 출발점입니다. 먼저 datasource와 query type을 정한 뒤, query를 실행해서 반환 형태가 패널 타입과 맞는지 확인합니다.

설정	역할
Queries	패널이 사용하는 query target 목록입니다. `A`, `B` 같은 refId로 구분합니다.
Datasource	`Prometheus (PromQL)` 또는 `ClickHouse (SQL)`을 선택합니다. 상단 datasource를 바꾸면 현재 query target에도 같은 datasource가 적용됩니다.
Query type	Prometheus에서는 `Instant`와 `Range`를 고릅니다. ClickHouse는 table query로 동작합니다.
Add Query	같은 패널에 query target을 추가합니다. Time Series, Table, Status Grid처럼 여러 query를 비교하거나 join할 때 사용합니다.
Query editor	PromQL 또는 SQL을 작성합니다. 대시보드 변수와 시간 매크로를 함께 사용할 수 있습니다.
Format / snippet 버튼	PromQL/SQL 포맷 정리, trace query template, group by, time filter, limit snippet을 넣습니다.
Run Query	저장하지 않고 현재 query를 실행해 결과 형태를 확인합니다.

ClickHouse 쿼리는 "$__fromTime", "$__toTime" 매크로를 지원합니다. 이 값은 편집 화면 상단의 Time range 기준으로 치환됩니다. Prometheus range query는 시간 범위와 start/end가 중요하고, instant query는 특정 시점의 대표값을 가져옵니다.

Table 타입에서 query가 둘 이상이면 join 설정이 나타납니다.

Join 설정	설명
Enable join across queries	여러 query 결과를 하나의 table로 합칩니다.
Join Queries	join에 포함할 refId를 고릅니다. 선택하지 않으면 전체 query가 대상입니다.
Join Key Field	여러 결과를 같은 행으로 묶을 기준 field입니다.
Join Type	inner, left, outer join 중 의도에 맞는 방식을 고릅니다.

중복 설정을 피하려면 datasource는 가능한 한 query target에서 한 번에 맞춥니다. 패널 타입 전환 후 datasource가 자동 변경된 경우, query editor와 datasource 표시가 서로 맞는지 먼저 확인합니다.

Fields 탭

Fields는 값이 화면에 표시되는 방식을 정합니다. 타입별 시각화가 달라도 단위, 소수점, min/max, threshold, value mapping은 대부분 공통으로 영향을 줍니다.

Field Display & Format

설정	역할
Display Name	legend, tooltip, stat title처럼 field 이름을 사람이 읽기 쉬운 이름으로 바꿉니다.
No Value Text	값이 없거나 null일 때 표시할 문구입니다. 기본값은 `No value`입니다.
Unit	숫자 단위를 지정합니다. `percent`, `bytes`, `ms`, `short` 등으로 값 formatter가 달라집니다.
Decimals	소수점 자리수를 고정합니다. 비워두면 자동으로 정합니다.
Min / Max	값 범위를 정합니다. Gauge, axis, threshold 색상 판단의 기준과 함께 쓰입니다.
Color Mode	값 자체 색상, 배경 색상, 색상 미사용 여부를 정합니다.

Unit, Decimals, Min, Max, Display Name, No Value Text는 내부적으로 fieldConfig.defaults에도 같이 반영됩니다. 같은 의미의 값을 JSON에서 따로 바꾸면 UI 값과 JSON 값이 어긋날 수 있으므로, 일반 편집에서는 Fields 탭을 기준으로 관리합니다.

Field Config

설정	역할
Threshold Mode	threshold step 값을 절대값으로 볼지 percentage로 볼지 정합니다.
Color Scheme	threshold나 value 색상 기본 팔레트를 정합니다.
Series Palette	Time Series/Bar 계열에서 여러 series 색상 순서를 정합니다.
Threshold Steps	값 범위별 색상을 순서대로 정의합니다. 각 step은 해당 값 이상부터 적용됩니다.
Value Mappings	특정 값 또는 범위를 텍스트와 색상으로 바꿉니다. 상태 코드, boolean, sentinel 상태를 사람이 읽는 문구로 바꿀 때 사용합니다.

중복 관계는 아래 원칙으로 정리합니다.

상황	권장 기준
Field Unit과 Axis Unit이 모두 있는 경우	값 표시와 tooltip은 Field Unit, 축 눈금은 Axis Unit을 따릅니다. 특별한 이유가 없으면 같은 단위로 맞춥니다.
Field Min/Max와 Axis Min/Max가 모두 있는 경우	Axis 입력은 chart 축에 직접 영향을 주며, 현재 UI는 min/max/decimals를 Field/Standard 값에도 동기화합니다. 한 곳에서 바꾼 뒤 다른 탭에서 값이 맞는지 확인합니다.
Global threshold와 Table column threshold가 모두 있는 경우	Table column threshold가 해당 column 표시를 더 구체적으로 제어합니다. 공통 기준은 Fields, 특정 column 예외는 Table column에서 둡니다.
Value Mapping과 Threshold가 모두 있는 경우	Mapping은 표시 텍스트/색상을 바꾸고, Threshold는 값 범위 기반 상태 색상을 만듭니다. 같은 값을 서로 다른 의미로 색칠하지 않도록 색상 기준을 하나로 맞춥니다.

Axes & Legend

Visualization 그룹 안에는 타입에 따라 Axes & Scale과 Legend도 함께 나타납니다.

설정	적용 타입	설명
Axis Label	Bar, Scatter, Time Series, Pie, Gauge	축에 표시할 이름입니다.
Scale	Bar, Scatter, Time Series, Pie, Gauge	`Linear` 또는 `Logarithmic`을 고릅니다. 0 또는 음수가 포함된 데이터에는 log scale을 피합니다.
Placement	Bar, Scatter, Time Series, Pie, Gauge	축을 왼쪽 또는 오른쪽에 둡니다.
Axis Unit	Bar, Scatter, Time Series, Pie, Gauge	축 눈금 단위를 정합니다. Field Unit과 맞추는 것이 기본입니다.
Decimals / Min / Max	Bar, Scatter, Time Series, Pie, Gauge	축과 값 범위의 정밀도를 정합니다.
Soft Min / Soft Max	Bar, Scatter, Time Series, Pie, Gauge	데이터가 범위를 벗어나면 자동 확장할 수 있는 느슨한 범위입니다.
Show Legend	Bar, Scatter, Time Series, Pie	legend 표시 여부입니다.
Mode	Bar, Scatter, Time Series, Pie	`List` 또는 `Table` legend를 고릅니다.
Placement	Bar, Scatter, Time Series, Pie	legend를 아래 또는 오른쪽에 둡니다.
Values	Time Series	table legend에 Last, Min, Max, Avg 같은 계산값을 column으로 표시합니다. 최소 하나는 남아야 합니다.

타입별 문서

타입별 조작 설명은 개별 페이지에서 확인합니다. 각 페이지는 query 결과 형태를 맞추는 Data, 단위와 threshold를 맞추는 Fields, 타입 전용 렌더링을 조정하는 Visualization 순서로 읽을 수 있게 구성했습니다.

타입 문서	대표 사용 상황	먼저 확인할 설정
Time Series	시간 흐름에 따른 메트릭 추세, series 비교	range query, draw style, null 처리, 축, legend
Bar	bucket, category, series를 막대 스타일로 비교	draw style, stack, fill, 축 단위
Stat	최신값, 평균, 합계 같은 대표값 표시	instant query, reducer, trend, color mode
Gauge	현재값이 기준 범위 안에서 어디에 있는지 표시	reducer, min/max, threshold, unit
Table	행과 열로 근거 데이터 검토	join, detected columns, cell type, filter
Heatmap	시간과 bucket별 밀도/분포 확인	x/y/value field, color scale, empty cell
Scatter	row 단위 관측치를 x/y 점으로 비교	x field, y field, series field
Status Grid	여러 대상의 정상/비정상 상태 스캔	reducer, reverse status, group, true/false text
Trace	trace 목록과 요약 확인	summary card, trace columns, column visibility
Gantt	시작/종료/기간이 있는 작업을 시간 막대로 표시	time unit, row grouping, row height
Pie	적은 수의 category 비중 표시	category query, unit, decimals, legend
Logs	로그성 텍스트 결과 표시	query, field formatting, panel layout, JSON

Panel & Layout

설정	역할
Panel Title	대시보드와 패널 header에 표시되는 제목입니다.
Description	패널 설명입니다. 미리보기와 문서화 목적에 사용됩니다.
Transparent Background	패널 배경 투명 여부입니다. 주변 row 배경과 맞춰야 합니다.
Panel Link	패널 메뉴에서 열 수 있는 외부 또는 내부 링크입니다.
Width	24-column grid 기준 너비입니다.
Height	row 단위 높이입니다.
X	0부터 시작하는 좌우 위치입니다.
Y	0부터 시작하는 세로 위치입니다.

빠른 배치는 대시보드의 Edit layout에서 drag/resize로 조정하고, 정확한 좌표가 필요할 때 이 탭에서 숫자를 맞춥니다. Width와 X의 합이 24를 넘지 않도록 관리합니다.

JSON

JSON 탭은 UI에 아직 노출되지 않은 panel config를 가져오거나 수정할 때 사용합니다.

설정	역할
Panel Config JSON	패널 config payload를 직접 편집합니다.
Apply Config	JSON을 현재 미리보기 draft에 적용합니다.
error message	JSON parse 또는 적용 실패 이유를 표시합니다.

Apply Config는 편집기 내부 draft에만 반영합니다. 실제 대시보드에 확정하려면 이후 Apply 또는 Apply & Save를 눌러야 합니다. JSON 적용 시 id와 gridPos는 대상 패널의 identity와 위치를 유지하기 위해 무시됩니다.

JSON을 쓸 때는 아래 순서를 권장합니다.

현재 패널 JSON을 백업합니다.
type, queryModel, visualization, options, fieldConfig 중 필요한 부분만 바꿉니다.
Apply Config로 미리보기와 오른쪽 탭 값이 맞는지 확인합니다.
Apply 또는 Apply & Save로 확정합니다.

Row와 Text 패널

Row 패널은 대시보드의 Add row로 추가하는 패널 묶음입니다. 일반 지표 패널처럼 query를 실행하지 않고, row 제목과 접힘 상태, 묶인 패널 배치가 핵심입니다. Row 편집에서는 General, Layout, JSON 중심으로 확인합니다.

Text 패널은 현재 타입 선택 메뉴에는 기본 노출되지 않을 수 있습니다. 기존 대시보드에 Text 패널이 있다면 markdown/text 표시 모드가 JSON에 들어있을 수 있으므로, Panel & Layout과 JSON을 함께 확인합니다.