Chart Block 구성 설명¶

Chart Block은 Markdown 노트에 실시간으로 렌더링되는 차트를 삽입하는 데 사용됩니다. 정적 이미지와 달리 Chart Block은 차트 유형, 쿼리 구문 및 표시 매개변수만 설정하면 미리보기 시 플랫폼 차트 구성 요소가 자동으로 쿼리를 실행하고 결과를 렌더링합니다.

기본 작성법¶

Markdown에서 언어 표시를 chart로 고정한 fenced code block을 사용합니다.

version: chart/v1
type: sequence
name: 서비스 P99 지연 시간
time:
  range: 1h
queries:
  - code: A
    qtype: dql
    namespace: metric
    q: 'M::`service_latency`:(p99(`duration`)) { service = "checkout" }'
settings:
  chartType: line
  legendPostion: bottom
  isTimeInterval: true
  xAxisShowType: time
  mainMeasurementQueryCode: A
  unitType: custom
  globalUnit:
    - custom
    - ms

지원되는 차트 유형¶

차트	`type`	설명
시계열 꺾은선 차트	`sequence`	시간에 따른 변화 추세 표시, 주로 메트릭, 로그 수, 지연 시간, 오류율 등에 사용
개요 차트	`singlestat`	핵심 단일 값 표시, 총합, 최대값, 평균값 등에 사용 가능
테이블 차트	`table`	상세 또는 집계된 다중 열 데이터 표시
막대 차트	`bar`	소스, 상태 코드, 서비스별 그룹화 등 분류별 비교 표시
히스토그램	`histogram`	소요 시간 분포, bucket 분포 등 분포 상황 표시
파이 차트	`pie`	오류 유형별 비율, 소스별 비율 등 비율 표시

공통 필드¶

필드	필수 여부	설명
`version`	예	고정값 `chart/v1`
`type`	예	차트 유형, 현재 지원되는 6가지 유형만 사용 가능
`name`	예	차트 제목, 차트 카드 상단에 렌더링
`description`	아니요	차트 설명, 현재 주로 구성 가독성을 위해 사용됨
`time.range`	아니요	쿼리 시간 범위 (예: `15m`, `1h`, `1d`), 미입력 시 기본값 `1h`로 미리보기
`queries`	예	쿼리 목록, 비어 있지 않은 배열이어야 함
`settings`	아니요	차트 표시 설정, 차트 유형에 따라 다른 필드 사용 가능

참고

Chart Block 바로 앞 줄의 Markdown 제목이 name과 완전히 일치할 경우 미리보기 시 외부 제목이 자동으로 숨겨져 제목 중복 표시를 방지합니다.

queries 필드¶

queries는 배열이며, 각 쿼리 항목은 하나의 차트 쿼리를 나타냅니다.

필드	필수 여부	설명
`code`	예	쿼리 코드, `A`, `B`, `C` 사용 권장
`qtype`	예	쿼리 언어, `dql` 및 `promql` 지원
`namespace`	아니요	쿼리 네임스페이스, DQL에서 주로 사용: `metric`, `log`, `object`, `event`, `tracing`, `rum`
`q`	예	쿼리 구문
`name`	아니요	쿼리 표시 이름, 미입력 시 `code` 사용

YAML이 특수 문자를 잘못 파싱하는 것을 방지하려면 q를 작은따옴표로 감싸는 것이 좋습니다.

q: 'L::re(`.*`):(count(`*`)) BY `source`'

쿼리 구문 자체에 작은따옴표가 포함된 경우 YAML 작은따옴표 문자열 안에서 두 개의 작은따옴표로 표기해야 합니다.

q: 'L::re(`.*`):(count(`*`)) { `service` = ''checkout'' }'

settings 공통 설정¶

settings는 플랫폼의 기존 차트 구성 요소에 전달됩니다. 자주 사용되는 필드는 다음과 같습니다.

필드	설명
`chartType`	차트 내부 형태, 예: `line`, `areaLine`, `bar`, `pie`, `doughnut`, `histogram`
`legendPostion`	범례 위치, 주로 `bottom`, `right`, `hide` 사용. 필드명은 `legendPostion`입니다.
`precision`	소수점 자릿수, 문자열로 작성하는 것이 좋습니다. (예: `"2"`)
`isTimeInterval`	시계열 표시 여부, 시계열 차트는 보통 `true`, 그룹화 차트는 보통 `false`
`xAxisShowType`	X축 표시 방식, 시계열은 `time`, 분류는 `groupBy` 주로 사용
`mainMeasurementQueryCode`	주 쿼리 코드, 주로 `A` 사용
`mainMeasurementSort`	주 메트릭 정렬 방식, 주로 `top`, `bottom` 사용
`mainMeasurementLimit`	표시 개수 상한, 예: `10`, `20`
`unitType`	단위 유형, 주로 `custom` 사용
`globalUnit`	전역 단위, 예: `['custom', 'ms']`, `['custom', 'count']`
`showLine`	개요 차트에서 추세선 표시 여부
`openStack`	누적(stack) 활성화 여부
`stackType`	누적 유형
`enableCombine`	파이 차트에서 작은 비율 항목 병합 여부
`combine`	파이 차트 병합 규칙
`promqlType`	PromQL 쿼리 유형, `rangeQuery` 주로 사용

차트 유형별 예시¶

시계열 꺾은선 차트 (sequence)¶

특정 메트릭의 시간에 따른 변화 추세를 표시하는 데 적합합니다.

version: chart/v1
type: sequence
name: 서비스 P99 지연 시간
time:
  range: 1h
queries:
  - code: A
    qtype: dql
    namespace: metric
    q: 'M::`service_latency`:(p99(`duration`)) { service = "checkout" }'
settings:
  chartType: line
  legendPostion: bottom
  isTimeInterval: true
  xAxisShowType: time
  mainMeasurementQueryCode: A
  unitType: custom
  globalUnit:
    - custom
    - ms

개요 차트 (singlestat)¶

오류 총 수, 최대값, 평균값 등 핵심 단일 메트릭 값을 표시하는 데 적합합니다.

version: chart/v1
type: singlestat
name: 최근 1시간 오류 수
time:
  range: 1h
queries:
  - code: A
    qtype: dql
    namespace: log
    q: 'L::re(`.*`):(count(`*`)) { status = "error" }'
settings:
  precision: "0"
  isTimeInterval: false
  showLine: false
  unitType: custom
  globalUnit:
    - custom
    - count

테이블 차트 (table)¶

상위 목록, 상세 목록 또는 집계 결과를 표시하는 데 적합합니다.

version: chart/v1
type: table
name: 상위 느린 인터페이스
time:
  range: 1h
queries:
  - code: A
    qtype: dql
    namespace: log
    q: 'L::re(`.*`):(`time`, `source`, `message`) LIMIT 20'
settings:
  queryMode: toGroupColumn
  showColumns:
    - time
    - source
    - message
  mainMeasurementQueryCode: A
  mainMeasurementSort: top
  mainMeasurementLimit: 20

막대 차트 (bar)¶

오류 소스 분포, 상태 코드 분포 등 분류별 비교를 표시하는 데 적합합니다.

version: chart/v1
type: bar
name: 로그 소스 분포
time:
  range: 1h
queries:
  - code: A
    qtype: dql
    namespace: log
    q: 'L::re(`.*`):(count(`*`)) BY `source`'
settings:
  direction: vertical
  xAxisShowType: groupBy
  isTimeInterval: false
  showTopSize: false
  aliasVersion: 2
  mainMeasurementLimit: 10
  unitType: custom
  globalUnit:
    - custom
    - count

히스토그램 (histogram)¶

분포를 표시하는 데 적합합니다. PromQL 시나리오의 경우 bucket/histogram 쿼리에 사용할 수 있습니다.

version: chart/v1
type: histogram
name: 요청 소요 시간 분포
time:
  range: 1h
queries:
  - code: A
    qtype: promql
    q: 'histogram_quantile(0.95, sum(rate(http_request_duration_seconds_bucket[5m])) by (le))'
settings:
  chartType: histogram
  direction: vertical
  legendPostion: bottom
  isTimeInterval: false
  promqlType: rangeQuery
  unitType: custom
  globalUnit:
    - custom
    - ms

파이 차트 (pie)¶

오류 유형별 비율, 소스별 비율 등 비율을 표시하는 데 적합합니다.

version: chart/v1
type: pie
name: 오류 소스 비율
time:
  range: 1h
queries:
  - code: A
    qtype: dql
    namespace: log
    q: 'L::re(`.*`):(count(`*`)) { status = "error" } BY `source`'
settings:
  chartType: doughnut
  legendPostion: right
  mainMeasurementQueryCode: A
  mainMeasurementSort: top
  mainMeasurementLimit: 8
  enableCombine: true
  combine:
    percent: "5"
    operator: lt
  unitType: custom
  globalUnit:
    - custom
    - count

필드 폐기 안내¶

chart/v1에서는 더 이상 다음과 같은 이전 필드명을 사용하지 않습니다. 새 구성에서는 해당 대체 필드를 사용하세요.

폐기된 필드	대체 필드
`title`	`name`
`view`	`settings`
`queries[].id`	`queries[].code`
`queries[].lang`	`queries[].qtype`
`queries[].datasource`	`queries[].namespace`

잘못된 예시:

version: chart/v1
type: sequence
title: 서비스 지연 시간
queries:
  - id: q1
    lang: dql
    datasource: metric
    q: 'M::x'
view:
  chartType: line

올바른 예시:

version: chart/v1
type: sequence
name: 서비스 지연 시간
queries:
  - code: A
    qtype: dql
    namespace: metric
    q: 'M::x'
settings:
  chartType: line

설정 검증 규칙¶

Chart Block은 렌더링 전에 다음 검증을 수행합니다.

version은 반드시 chart/v1이어야 합니다.
type은 반드시 sequence, singlestat, table, bar, histogram, pie 중 하나여야 합니다.
name은 비어 있을 수 없습니다.
queries는 반드시 비어 있지 않은 배열이어야 합니다.
각 query는 반드시 code, qtype, q를 포함해야 합니다.
qtype은 dql 또는 promql만 가능합니다.
YAML은 올바르게 파싱될 수 있어야 합니다.

검증에 실패하면 미리보기 영역에 오류 카드와 원본 설정 내용이 표시되며, 노트의 다른 Markdown 내용 표시에는 영향을 미치지 않습니다.

설정 권장 사항¶

Chart Block은 쿼리 및 표시 매개변수 설정에만 사용하십시오. data, items, series와 같은 정적 데이터를 포함하지 마십시오.
쿼리 구문은 실제 실행 가능한 쿼리를 사용하여 렌더링 결과의 정확성을 보장하는 것이 좋습니다.
여러 차트를 삽입해야 하는 경우 여러 개의 chart block을 연속으로 작성하면 각 block이 하나의 차트에 해당합니다.
텍스트 설명만 필요한 경우 Chart Block을 사용하지 않고 Markdown을 직접 사용하여 작성하십시오.
차트 렌더링 결과가 비어 있는 경우 시간 범위, 쿼리 조건, 네임스페이스 및 쿼리 구문의 정확성을 먼저 확인하는 것이 좋습니다.

이전 chart_json 호환성 안내¶

시스템은 이전 노트 데이터와의 호환성을 위해 이전 버전의 chart_json fenced block을 계속 파싱할 수 있습니다. 새 노트 작성 및 AI 생성 콘텐츠는 chart/v1을 통일하여 사용하십시오.