Документацияbreadcrumb arrow Grafanabreadcrumb arrow Документация GlaberGraphbreadcrumb arrow Как кодbreadcrumb arrow Наблюдаемость как кодbreadcrumb arrow Начало работы с Grafana Foundation SDKbreadcrumb arrow Ключевые концепции Foundation SDK

Ключевые концепции Foundation SDK

Grafana Foundation SDK построен вокруг нескольких ключевых концепций, которые делают ваши дашборды структурированными, переиспользуемыми и строго типизированными.

Построители

SDK следует шаблону построителя (builder pattern), который позволяет собирать дашборды шаг за шагом с помощью цепочек вызовов методов. Почти у каждой части дашборда, включая дашборды, панели, строки, запросы и переменные, есть собственный класс Builder.

Вот несколько из тех, которые вы уже видели:

  • DashboardBuilder — начинает определение дашборда и задаёт глобальные параметры конфигурации, такие как заголовок, UID, интервал обновления, временной диапазон и т. д.
  • PanelBuilder — создаёт отдельные визуализации, например панели временных рядов, панели stat или панели логов.
  • DataqueryBuilder — определяет, как панель получает данные, например из Prometheus или плагина testdata.

Построители можно объединять в цепочки, поэтому вы можете текуче собирать дашборды в читаемом структурированном виде:

Go 
stat.NewPanelBuilder().
  Title("Version").
  Datasource(testdataRef).
  ReduceOptions(common.NewReduceDataOptionsBuilder().
    Calcs([]string{"lastNotNull"}).
    Fields("/.*/")).
  WithTarget(
    testdata.NewDataqueryBuilder().
      ScenarioId("csv_content").
      CsvContent("version\nv1.2.3"),
  )
typescript 
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'));

Типы

Grafana Foundation SDK использует строгие типы под капотом, чтобы помочь выявлять ошибки до того, как вы развернёте сломанный дашборд.

Например:

  • При задании единицы измерения вы получите подсказки автодополнения для допустимых единиц Grafana, таких как "percent" или "bps".
  • При определении временного диапазона вам будет предложено указать правильную структуру, например значения from и to.
  • При ссылке на источники данных вы будете использовать структурированный объект DataSourceRef с определёнными полями type и uid.

Это помогает вам:

  • Избегать опечаток или неподдерживаемых значений конфигурации
  • Получать полное автодополнение и встроенную документацию в вашей IDE
  • Писать дашборды, которые меньше подвержены ошибкам и легче поддерживаются

Строгая типизация также упрощает создание переиспользуемых шаблонов и компонентов с уверенностью, особенно в больших кодовых базах или командах.

Опции

Большинство методов построителей принимают простые значения, такие как строки или числа, но другие ожидают более структурированные объекты опций. Они используются, например, для:

  • ReduceDataOptions — как сокращать данные временных рядов до отдельных значений (например, last, avg).
  • VizLegendOptions — настройка того, как отображается легенда панели.
  • CanvasElementOptions — определение того, как должны отображаться различные компоненты панели Canvas.

Пример использования опций:

Go 
stat.NewPanelBuilder().
  ReduceOptions(common.NewReduceDataOptionsBuilder().
    Calcs([]string{"lastNotNull"}).
    Fields("/.*/"))
  )
typescript 
new stat.PanelBuilder().reduceOptions(new common.ReduceDataOptionsBuilder().calcs(['lastNotNull']).fields('/.*/'));

Используя построители опций, вам не нужно вручную создавать глубоко вложенные объекты конфигурации. Вместо этого SDK предоставляет типизированный и управляемый API, который повторяет внутреннюю структуру дашборда, упрощая настройку сложных опций без догадок и без необходимости обращаться к схеме JSON.