DOCSEARCHbyAlgolia
Submit Docs

Grafana Foundation SDK

repository·main·Indexed 42 days ago

https://github.com/grafana/grafana-foundation-sdk

Strongly typed builder libraries for defining Grafana resources, such as dashboards and alerts, as code. Available for Go, TypeScript, Python, PHP, and Java, the SDK allows developers to leverage strong typing for configuration, manage resources via version control, and automate deployments. It is compatible with Grafana >= 10 and optimized for Grafana >= 12. Version v0.0.20 provides programmatic construction of dashboards, rows, and panels, and supports custom panel and query types for third-party plugins.

Tokens
792.2K
Snippets
3K
Records
4.3K
Agent score
51%

What's inside Grafana Foundation SDK

  1. What is the Grafana Foundation SDK?

    main

    The Grafana Foundation SDK is a set of types and builder libraries designed to let you define Grafana resources (such as dashboards and alerts) using strongly typed code.

    By using the SDK, you can:

    • Leverage strong typing: Catch configuration errors at compile time.
    • Enhance version control: Manage your Grafana resources using Git.
    • Automate deployments: Integrate resource provisioning into CI/CD pipelines.

    The SDK is best suited for Grafana >= 12, but is compatible with Grafana >= 10.

  6. Explore expression (expr) objects and builders

    main

    The expr module provides a comprehensive set of objects and builders for constructing and managing data query expressions.

    Objects

    Objects represent the structured data models for different expression types, including:

    • Classic Conditions: TypeClassicConditions, ExprTypeClassicConditionsConditions, etc.
    • Math: TypeMath, ExprTypeMathTimeRange, ExprTypeMathResultAssertions.
    • Reduce: TypeReduce, ExprTypeReduceSettings, ExprTypeReduceTimeRange.
    • Resample: TypeResample, ExprTypeResampleTimeRange.
    • SQL: TypeSql, ExprTypeSqlTimeRange.
    • Threshold: TypeThreshold, ExprTypeThresholdConditions.
    • General: Expr (a disjunction of types).

    Builders

    Builders are used to programmatically construct the objects listed above. Each major expression type has a corresponding builder (e.g., TypeMath builder, TypeSql builder, Query builder) to ensure valid configuration construction.

  9. Explore Grafana Foundation SDK TypeScript packages

    main

    The Grafana Foundation SDK for TypeScript is organized into several specialized packages. These packages are categorized by their purpose, such as core functionality, panel configurations, or data query implementations. Use the following categorization to find the relevant package for your development needs:

    Core Packages

    These provide fundamental SDK functionality:

    • alerting
    • dashboard
    • dashboardv2beta1
    • librarypanel
    • preferences
    • publicdashboard
    • team

    Panel Configuration Packages (package-variant-panelcfg)

    These packages define configurations for specific Grafana UI panels:

    • annotationslist, barchart, bargauge, candlestick, canvas, dashboardlist, datagrid, debug, gauge, geomap, heatmap, histogram, logs, news, nodegraph, piechart, stat, statetimeline, statushistory, table, text, timeseries, trend, `xychart

    Data Query Packages (package-variant-dataquery)

    These packages handle data source specific queries and expressions:

    • athena, azuremonitor, bigquery, cloudwatch, datasource, elasticsearch, expr, googlecloudmonitoring, grafanapyroscope, loki, parca, prometheus, tempo, `testdata

    Other Packages

    • common: Shared utilities and types.
    • dashboardv2: Dashboard version 2 definitions.
    • folderv1 / folderv1beta1: Folder management.
    • playlistv0alpha1 / playlistv1: Playlist management.
    • resource, starsv1alpha1, units: Miscellaneous domain models.

  11. Loki data query objects and builders

    main

    The Loki package provides objects and builders for constructing and managing Loki data queries within the Grafana Foundation SDK.

    Core Objects:

    • LokiQueryDirection: Defines the direction of the query.
    • LokiQueryType: Specifies the type of Loki query being performed.
    • QueryEditorMode: Determines the mode of the query editor.
    • SupportingQueryType: Defines types that support the query.
    • Dataquery: The primary class representing a data query.

    Builders: Use these builders to programmatically construct query structures:

    • Query: Builder for standard queries.
    • QueryV2: Builder for version 2 queries.
    • Dataquery: Builder for constructing Dataquery objects.

  12. What is a TransformationSpec and how is it used

    main

    A TransformationSpec defines a data transformation that manipulates query results before they are passed to a visualization. Transformations enable tasks such as renaming fields, joining time series data, performing mathematical operations across different queries, and chaining transformations by using the output of one as the input to another.

    Key properties of a TransformationSpec include:

    • disabled: A boolean that, if set, causes the transformation to be skipped.
    • filter: An optional MatcherConfig used to target specific data frames. If omitted, the transformation applies to all results.
    • topic: An optional DataTopic specifying where to pull input DataFrames from.
    • options: A mixed-type field containing configuration specific to the transformer's ID.