Foundation SDK 핵심 개념

이 문서에서는 Grafana Foundation SDK의 핵심 개념을 소개합니다. 빌더(Builder), 타입(Types), 옵션(Options) 같은 기본 개념을 이해하면 대시보드를 구조화되고 재사용 가능하며 강력한 타입으로 만들 수 있어요.

출처: 문서

본문

Grafana Foundation SDK는 대시보드를 구조화되고 재사용 가능하며 강력한 타입으로 만들 수 있게 해주는 몇 가지 핵심 개념을 중심으로 설계되어 있어요.

빌더(Builders)

SDK는 빌더 패턴을 따르며, 체이닝된 메서드 호출로 대시보드를 단계적으로 구성할 수 있게 해줘요. 대시보드, 패널, 행, 쿼리, 변수를 포함한 대시보드의 거의 모든 부분에 고유한 Builder 클래스가 있어요.

이미 살펴본 몇 가지 예는 다음과 같아요:

DashboardBuilder — 대시보드 정의를 시작하고 제목, UID, 새로고침 간격, 시간 범위 같은 전역 구성 설정을 지정해요.
PanelBuilder — 시계열 패널, 통계 패널, 로그 패널 같은 개별 시각화를 만들어요.
DataqueryBuilder — 예를 들어 Prometheus나 testdata 플러그인에서 패널이 데이터를 가져오는 방식을 정의해요.

빌더는 체이닝할 수 있어 가독성 있고 구조화된 방식으로 대시보드를 유창하게 구성할 수 있어요:

stat.NewPanelBuilder().
  Title("Version").
  Datasource(testdataRef).
  ReduceOptions(common.NewReduceDataOptionsBuilder().
    Calcs([]string{"lastNotNull"}).
    Fields("/.*/")).
  WithTarget(
    testdata.NewDataqueryBuilder().
      ScenarioId("csv_content").
      CsvContent("version\nv1.2.3"),
  )

new stat.PanelBuilder()
  .title('Version')
  .reduceOptions(new common.ReduceDataOptionsBuilder().calcs(['lastNotNull']).fields('/.*/'))
  .datasource(testdataRef)
  .withTarget(new testdata.DataqueryBuilder().scenarioId('csv_content').csvContent('version\nv1.2.3'));

타입(Types)

Grafana Foundation SDK는 내부적으로 강력한 타입을 사용해 깨진 대시보드를 배포하기 전에 실수를 잡아내도록 도와줘요.

예를 들어:

단위를 설정할 때 "percent"나 "bps" 같은 유효한 Grafana 단위에 대한 자동 완성 제안을 받아요.
시간 범위를 정의할 때 from과 to 값 같은 올바른 구조를 제공하도록 안내받아요.
데이터 소스를 참조할 때 정의된 type과 uid 필드가 있는 구조화된 DataSourceRef 객체를 사용해요.

이것은 다음과 같은 도움을 줘요:

오타나 지원되지 않는 구성 값을 피하게 해줘요.
IDE에서 전체 자동 완성과 인라인 문서를 받게 해줘요.
오류가 적고 유지보수가 쉬운 대시보드를 작성하게 해줘요.

강력한 타입은 특히 큰 코드베이스나 팀에서 재사용 가능한 패턴과 컴포넌트를 자신 있게 빌드하기도 쉽게 만들어요.

옵션(Options)

대부분의 빌더 메서드는 문자열이나 숫자 같은 단순한 값을 수용하지만, 다른 메서드는 더 구조화된 옵션 객체를 기대해요. 이들은 다음과 같은 용도로 사용돼요:

ReduceDataOptions — 시계열 데이터를 단일 값(예: last, avg)으로 줄이는 방법을 정의해요.
VizLegendOptions — 패널의 범례가 표시되는 방식을 구성해요.
CanvasElementOptions — Canvas 패널의 다양한 컴포넌트가 표시되는 방식을 정의해요.

옵션을 사용한 예:

stat.NewPanelBuilder().
  ReduceOptions(common.NewReduceDataOptionsBuilder().
    Calcs([]string{"lastNotNull"}).
    Fields("/.*/"))
  )

new stat.PanelBuilder().reduceOptions(new common.ReduceDataOptionsBuilder().calcs(['lastNotNull']).fields('/.*/'));

옵션 빌더를 사용하면 깊게 중첩된 구성 객체를 수동으로 구성할 필요가 없어요. 대신 SDK가 대시보드의 내부 구조를 반영하는 타입이 지정되고 안내된 API를 제공해, 추측이나 JSON 스키마 참고 없이도 복잡한 옵션을 더 쉽게 구성할 수 있게 해줘요.

더 알아보기

원문 문서