Начало работы с Grafana Foundation SDK

Документация

Grafana

Документация GlaberGraph

Как код

Наблюдаемость как код

Начало работы с Grafana Foundation SDK

Grafana Foundation SDK — это набор инструментов, типов и библиотек, позволяющих определять дашборды и ресурсы Grafana с помощью строго типизированного кода. Определяя дашборды как код, вы можете:

Использовать преимущества строгой типизации: находите ошибки на этапе компиляции, что обеспечивает более надёжные конфигурации.
Улучшить контроль версий: отслеживайте изменения без усилий с помощью стандартных систем контроля версий, таких как Git.
Автоматизировать развёртывание: включайте выделение дашбордов в свои конвейеры CI/CD для согласованных и воспроизводимых настроек.

SDK поддерживает несколько языков программирования, включая Go, TypeScript, Python, PHP и Java, поэтому вы можете выбрать тот, который лучше всего подходит для вашей среды разработки. Дополнительные сведения см. в репозитории Grafana Foundation SDK на GitHub.

Обзор Grafana Foundation SDK

Вот краткий обзор того, как работает Grafana Foundation SDK:

Шаблон композируемых построителей (builder pattern): вы можете объединять в цепочки различные блоки-построители, чтобы описывать дашборды в текучем стиле. Вы начинаете с DashboardBuilder, затем шаг за шагом добавляете панели, запросы и другие компоненты.
Безопасная строгая типизация: в SDK всё строго типизировано. Это даёт автодополнение в вашей IDE, позволяет рано выявлять ошибки и помогает гарантировать, что вы всегда используете допустимые значения конфигурации.
Конфигурация со структурированными опциями: когда конфигурация усложняется (например, сокращение данных или настройки отображения), SDK использует типизированные построители опций, чтобы сохранить код читаемым, предсказуемым и легко управляемым.

По мере создания более сложных дашбордов вы будете работать с дополнительными построителями и типами для поддержки более богатой функциональности. SDK поддерживает не только панели и запросы, но также переменные, пороги, переопределения полей, преобразования и многое другое. Обратитесь к полному справочнику по API, чтобы изучить доступные возможности.

Более подробное объяснение см. в разделе Ключевые концепции Foundation SDK, а затем читайте дальше, чтобы увидеть эти концепции в действии.

Прежде чем начать

Убедитесь, что у вас есть следующие предварительные условия:

Среда программирования: настроенная для выбранного вами языка. Например: Go, Node.js для TypeScript или Python 3.x для Python.
Экземпляр Grafana: работающий экземпляр Grafana, совместимый с SDK (Grafana v10.0 или выше).
Менеджер пакетов: подходящий для вашего языка, например npm или yarn для TypeScript или pip для Python.

Установка Grafana Foundation SDK

Чтобы установить Foundation SDK:

Клонируйте репозиторий intro-to-foundation-sdk, чтобы получить доступ к примерам и стеку docker-compose.
Выберите вкладку go или typescript, чтобы просмотреть инструкции по установке SDK. Для других языков обратитесь к документации Grafana Foundation SDK за инструкциями по установке.

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

npm install @grafana/grafana-foundation-sdk

Создание дашборда

См. следующие примеры на Go и TypeScript для создания простого дашборда:

Этот код определяет дашборд с заголовком «My Dashboard» и двумя панелями:

простую панель stat, отображающую номер версии, и
панель временных рядов, отображающую случайные данные из сценария random_walk источника данных testdata.

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)
}

// 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

После того как вы определили дашборд как код, соберите итоговое представление дашборда с помощью построителя дашбордов, обычно используя функцию build() в зависимости от выбранного языка, и выведите результат в формате JSON.

Получив полезную нагрузку JSON, вы можете:

Импортировать вручную: вставить её в функцию импорта дашбордов Grafana.
Автоматизировать: использовать Grafana API, Grafana CLI или Git Sync для программной загрузки JSON дашборда.

Изучение примера из реальной практики

Если вы хотите узнать больше и увидеть более реалистичный пример использования Grafana Foundation SDK, посмотрите следующий разбор:

В этом видео мы генерируем дашборд из кода и развёртываем его с помощью Grafana API, рассматривая шаблоны и практики, которые вы будете использовать в производственных средах. Оно также включает рабочий пример веб-сервиса, который выдаёт метрики и логи, и показывает, как развернуть дашборд вместе с ним с помощью Docker Compose.

Полный исходный код этого примера можно найти в репозитории intro-to-foundation-sdk.

Дальнейшие шаги

Теперь, когда вы понимаете основы использования Grafana Foundation SDK, вот несколько дальнейших шагов:

Изучите больше возможностей: ознакомьтесь с полным справочником по API, чтобы узнать о расширенных конфигурациях дашбордов.
Возьмите дашборды под контроль версий: храните код дашбордов в репозитории Git, чтобы отслеживать изменения со временем.
Автоматизируйте выделение дашбордов с помощью CI/CD: интегрируйте SDK в свой конвейер CI/CD, чтобы развёртывать дашборды автоматически.
Изучите Grafana Git Sync, который позволяет синхронизировать ваши ресурсы, чтобы хранить дашборды в виде JSON-файлов в GitHub и управлять ими как кодом.

Была ли эта страница полезна?

Написать на docs@glaber.ru

Справка и поддержка

Сообщество