Grafana Foundation SDK 시작하기

Grafana Foundation SDK 시작하기 (Get started with the Grafana Foundation SDK)

Grafana Foundation SDK는 강력한 타입의 코드로 Grafana 대시보드와 리소스를 정의할 수 있게 해주는 도구, 타입, 라이브러리의 집합이에요. 대시보드를 코드로 작성하면 다음을 할 수 있어요:

• 강력한 타입 활용: 컴파일 타임에 오류를 잡아 더 신뢰할 수 있는 구성을 보장해요.
• 버전 관리 향상: Git 같은 표준 버전 관리 시스템으로 변경 사항을 원활하게 추적해요.
• 배포 자동화: 대시보드 프로비저닝을 CI/CD 파이프라인에 통합해 일관되고 반복 가능한 설정을 만들어요.

SDK는 Go, TypeScript, Python, PHP, Java를 포함한 여러 프로그래밍 언어를 지원하므로 개발 환경에 가장 잘 맞는 언어를 선택할 수 있어요. 자세한 내용은 Grafana Foundation SDK GitHub 저장소를 참고해요.

출처: 문서

본문

Grafana Foundation SDK는 강력한 타입의 코드로 Grafana 대시보드와 리소스를 정의할 수 있게 해주는 도구, 타입, 라이브러리의 집합이에요. 대시보드를 코드로 작성하면 다음을 할 수 있어요:

• 강력한 타입 활용: 컴파일 타임에 오류를 잡아 더 신뢰할 수 있는 구성을 보장해요.
• 버전 관리 향상: Git 같은 표준 버전 관리 시스템으로 변경 사항을 원활하게 추적해요.
• 배포 자동화: 대시보드 프로비저닝을 CI/CD 파이프라인에 통합해 일관되고 반복 가능한 설정을 만들어요.

SDK는 Go, TypeScript, Python, PHP, Java를 포함한 여러 프로그래밍 언어를 지원하므로 개발 환경에 가장 잘 맞는 언어를 선택할 수 있어요. 자세한 내용은 Grafana Foundation SDK GitHub 저장소를 참고해요.

Grafana Foundation SDK 개요 (Grafana Foundation SDK overview)

Grafana Foundation SDK가 어떻게 작동하는지에 대한 빠른 개요예요:

• 구성 가능한 빌더 패턴: 서로 다른 빌더 블록을 연결해 대시보드를 유창하게 정의할 수 있어요. DashboardBuilder로 시작한 뒤 패널, 쿼리, 기타 구성 요소를 단계별로 추가해요.
• 안전한 강력한 타입: SDK의 모든 것이 강력한 타입이에요. 이는 IDE에서 자동 완성을 제공하고 실수를 일찍 잡아내며 항상 유효한 구성 값을 사용하도록 돕는 것을 보장해요.
• 구조화된 옵션으로 구성: 구성이 복잡해지면(데이터 축소나 디스플레이 설정처럼) SDK는 타입이 있는 옵션 빌더를 사용해 가독성 있고 예측 가능하며 제어하기 쉬운 상태를 유지해요.

더 고급 대시보드를 만든다면 더 풍부한 기능을 지원하는 추가 빌더와 타입으로 작업하게 돼요. SDK는 패널과 쿼리뿐만 아니라 변수, 임계값, 필드 오버라이드, 변환 등을 지원해요. 전체 API 참조를 참고해 가능한 것을 탐구해요.

더 광범위한 설명은 Foundation SDK 핵심 개념을 참고하고, 이 개념이 실제로 작동하는 것을 보려면 계속 읽어보세요.

시작하기 전에 (Before you begin)

다음 사전 요구 사항이 있는지 확인해요:

• 프로그래밍 환경: 선택한 언어로 설정돼 있어요. 예: Go, TypeScript용 Node.js, Python용 Python 3.x.
• Grafana 인스턴스: SDK와 호환되는 실행 중인 Grafana 인스턴스(Grafana v10.0 이상).
• 패키지 관리자: 언어에 적합한 것. 예: TypeScript용 npm 또는 yarn, Python용 pip.

Grafana Foundation SDK 설치 (Install the Grafana Foundation SDK)

Foundation SDK를 설치하려면:

1. 예제와 docker-compose 스택에 접근하려면 intro-to-foundation-sdk 저장소를 클론해요.
2. SDK 설치 지침을 보려면 go 또는 typescript 탭을 선택해요. 다른 언어는 설치 지침을 위해 Grafana Foundation SDK 문서를 참고해요.

Go

typescript

Go

go get github.com/grafana/grafana-foundation-sdk/go@latest

typescript

npm install @grafana/grafana-foundation-sdk

대시보드 만들기 (Create a dashboard)

간단한 대시보드를 만들기 위한 Go와 Typescript의 다음 예제를 참고해요:

이 코드는 "My Dashboard"라는 제목의 대시보드를 두 개의 패널로 정의해요:

• 버전 번호를 표시하는 간단한 stat 패널, 그리고
• testdata 데이터 소스 random_walk 시나리오의 무작위 데이터를 표시하는 time series 패널.

Go

typescript

Go

package main

// Import the appropriate Grafana Foundation SDK packages
import (
  "encoding/json"
  "log"

  "github.com/grafana/grafana-foundation-sdk/go/cog"
  "github.com/grafana/grafana-foundation-sdk/go/common"
  "github.com/grafana/grafana-foundation-sdk/go/dashboard"
  "github.com/grafana/grafana-foundation-sdk/go/stat"
  "github.com/grafana/grafana-foundation-sdk/go/testdata"
  "github.com/grafana/grafana-foundation-sdk/go/timeseries"
)

func main() {
  // Define a data source reference for our testdata data source
  testdataRef := dashboard.DataSourceRef{
    Type: cog.ToPtr("grafana-testdata-datasource"),
    Uid:  cog.ToPtr("testdata"),
  }

  // Define our dashboard as strongly typed code
  builder := dashboard.NewDashboardBuilder("My Dashboard").
    WithPanel(
      stat.NewPanelBuilder().
        Title("Version").
        Datasource(testdataRef).
        ReduceOptions(common.NewReduceDataOptionsBuilder().
          Calcs([]string{"lastNotNull"}).
          Fields("/.*/")).
        WithTarget(
          testdata.NewDataqueryBuilder().
            ScenarioId("csv_content").
            CsvContent("version\nv1.2.3"),
        ),
    ).
    WithPanel(
      timeseries.NewPanelBuilder().
        Title("Random Time Series").
        Datasource(testdataRef).
        WithTarget(
          testdata.NewDataqueryBuilder().
            ScenarioId("random_walk"),
        ),
    )

  // Build the dashboard - errors in configuration will be thrown here
  dashboard, err := builder.Build()
  if err != nil {
    log.Fatalf("failed to build dashboard: %v", err)
  }

  // Output the generated dashboard as JSON
  dashboardJson, err := json.MarshalIndent(dashboard, "", "  ")
  if err != nil {
    log.Fatalf("failed to marshal dashboard: %v", err)
  }

  log.Printf("Dashboard JSON:\n%s", dashboardJson)
}

typescript

// Import the appropriate Grafana Foundation SDK packages
import * as common from '@grafana/grafana-foundation-sdk/common';
import * as dashboard from '@grafana/grafana-foundation-sdk/dashboard';
import * as stat from '@grafana/grafana-foundation-sdk/stat';
import * as testdata from '@grafana/grafana-foundation-sdk/testdata';
import * as timeseries from '@grafana/grafana-foundation-sdk/timeseries';

// Define a data source reference for our testdata data source
const testDataRef: dashboard.DataSourceRef = {
  type: 'grafana-testdata-datasource',
  uid: 'testdata',
};

// Define our dashboard as strongly typed code
const builder = new dashboard.DashboardBuilder('My Dashboard')
  .withPanel(
    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'))
  )
  .withPanel(
    new timeseries.PanelBuilder()
      .title('Random Time Series')
      .datasource(testdataRef)
      .withTarget(new testdata.DataqueryBuilder().scenarioId('random_walk'))
  );

// Build the dashboard - errors in configuration will be thrown here
const dashboard = builder.build();

// Output the generated dashboard as JSON
console.log(JSON.stringify(dashboard, null, 2));

JSON 내보내기와 사용 (Export and use the JSON)

대시보드를 코드로 정의한 뒤에는 대시보드 빌더를 사용해 최종 대시보드 표현을 만들고(보통 언어 선택에 따라 build() 함수 사용), 결과를 JSON으로 출력해요.

JSON 페이로드로 다음을 할 수 있어요:

• 수동 가져오기: Grafana의 대시보드 가져오기 기능에 붙여넣어요.
• 자동화: Grafana API, Grafana CLI, 또는 Git Sync를 사용해 대시보드 JSON을 프로그래밍 방식으로 업로드해요.

실제 사례 탐구 (Explore a real-world example)

더 탐구하고 Grafana Foundation SDK 사용의 실제 사례를 보고 싶다면 다음 워크스루를 시청해요:

이 비디오에서 코드로 대시보드를 생성하고 Grafana API로 배포하며, 프로덕션 환경에서 사용할 패턴과 관행을 다뤄요. 또한 메트릭과 로그를 방출하는 웹 서비스의 작동 예제를 포함하고 Docker Compose로 대시보드를 함께 배포하는 방법을 보여줘요.

이 예제의 전체 소스 코드는 intro-to-foundation-sdk 저장소에서 찾을 수 있어요.

다음 단계 (Next steps)

이제 Grafana Foundation SDK 사용의 기본을 이해했으니 다음 단계가 있어요:

• 더 많은 기능 탐구: 전체 API 참조를 확인해 고급 대시보드 구성에 대해 배워요.
• 대시보드 버전 관리: Git 저장소에 대시보드 코드를 저장해 시간 경과에 따른 변경 사항을 추적해요.
• CI/CD로 대시보드 프로비저닝 자동화: SDK를 CI/CD 파이프라인에 통합해 대시보드를 자동으로 배포해요.
• 재미있는 Grafana Git Sync 에 대해 배워보세요. 리소스를 동기화해 대시보드를 GitHub에 저장된 JSON 파일로 저장하고 코드로 관리할 수 있어요.

더 알아보기 (Learn more)

• Foundation SDK 핵심 개념 (Foundation SDK key concepts)
• Grafana Foundation SDK API 참조
• 대시보드 자동화 (Dashboard automation)
• Grafana Git Sync