Observability as code on Grafana Labs

Introduction to Grafana CLI

Tue, 14 Apr 2026 09:48:24 +0000

Observability as Code

Using Observability as Code, you can version, automate, and scale Grafana configurations, including dashboards and observability workflows.

Explore

Grafana CLI

Grafana CLI (grafanactl) is a command-line tool designed to simplify interaction with Grafana instances using the new REST APIs. You can authenticate, manage multiple environments, and perform administrative tasks from the terminal. It’s suitable for CI/CD pipelines, local development, or free-form tasks.

Foundation SDK

The Grafana Foundation SDK is a set of tools, types, and libraries that let you define Grafana dashboards and resources using familiar programming languages like Go, TypeScript, Python, Java, and PHP. Use it in conjunction with grafanactl to push your programmatically generated resources.

Git Sync

Git Sync lets you store your dashboard files in a GitHub repository and synchronize those changes with your Grafana instance, enabling version control, branching, and pull requests directly from Grafana.

On-prem file provisioning

File provisioning in Grafana lets you include resources, including folders and dashboard JSON files, that are stored in a local file system.

Foundation SDK

Tue, 14 Apr 2026 09:48:24 +0000

Get started with the Grafana Foundation SDK

The Grafana Foundation SDK is a set of tools, types, and libraries that let you define Grafana dashboards and resources using strongly typed code. By writing your dashboards as code, you can:

Leverage strong typing: Catch errors at compile time, ensuring more reliable configurations.
Enhance version control: Track changes seamlessly using standard version control systems like Git.
Automate deployments: Integrate dashboard provisioning into your CI/CD pipelines for consistent and repeatable setups.

The SDK supports multiple programming languages, including Go, TypeScript, Python, PHP, and Java, so you can choose the one that best fits your development environment. Refer to the Grafana Foundation SDK GitHub repository for further details.

Grafana Foundation SDK overview

Here’s a quick overview of how the Grafana Foundation SDK works:

Composable builder pattern: You can chain different builder blocks to define dashboards fluently. You start with a DashboardBuilder, then add panels, queries, and other components step by step.
Safe strong typing: Everything in the SDK is strongly typed. This gives you autocompletion in your IDE, catches mistakes early, and helps ensure you’re always using valid configuration values.
Configuration with structured options: When a configuration get complex (like data reduction or display settings), the SDK uses typed option builders to keep things readable, predictable, and easy to control.

As you build more advanced dashboards, you’ll work with additional builders and types to support richer functionality. The SDK supports not just panels and queries, but also variables, thresholds, field overrides, transformations, and more. Refer to the full API reference to explore what’s possible.

Refer to Foundation SDK key concepts for a more extensive explanation, and read on to see these concepts in action.

Before you begin

Ensure you have the following prerequisites:

Programming environment: Set up for your chosen language. For example: Go, Node.js for TypeScript, or Python 3.x for Python.
Grafana instance: A running Grafana instance compatible with the SDK (Grafana v10.0 or higher).
Package manager: Appropriate for your language, for example, npm or yarn for TypeScript or pip for Python.

Install the Grafana Foundation SDK

To install the Foundation SDK:

Clone the intro-to-foundation-sdk repository to access examples and a docker-compose stack.
Select the go or typescript tab to view instructions to install the SDK. For other languages, refer to the Grafana Foundation SDK documentation for installation instructions.

typescript

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

npm install @grafana/grafana-foundation-sdk

Create a dashboard

See the following examples in Go and Typescript to create a simple dashboard:

This code defines a dashboard titled “My Dashboard” with a two panels:

a simple stat panel displaying a version number, and
a time series panel displaying randomized data from the testdata data source random_walk scenario.

typescript

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

Export and use the JSON

After you’ve defined your dashboard as code, build the final dashboard representation using the dashboard builder, typically using the build() function depending on language choice, and output the result as a JSON.

With the JSON payload, you can:

Manually import: Paste into Grafana’s dashboard import feature.
Automate: Use the Grafana API, the Grafana CLI, or Git Sync to programmatically upload the dashboard JSON.

Explore a real-world example

If you want to explore further and see a more real-world example of using the Grafana Foundation SDK, watch the following walkthrough:

In this video, we generate a dashboard from code and deploy it using the Grafana API, covering patterns and practices you’d use in production environments. It also includes a working example of a web service that emits metrics and logs, and shows how to deploy a dashboard alongside it using Docker Compose.

You can find the full source code for this example in the intro-to-foundation-sdk repository.

Next steps

Now that you understand the basics of using the Grafana Foundation SDK, here are some next steps:

Explore more features: Check out the full API reference to learn about advanced dashboard configurations.
Version control your dashboards: Store your dashboard code in a Git repository to track changes over time.
Automate dashboard provisioning with CI/CD: Integrate the SDK into your CI/CD pipeline to deploy dashboards automatically.
Learn about Grafana Git Sync, which lets you synchronize your resources so you can store your dashboards as JSON files stored in GitHub and manage them as code.

Introduction to Git Sync

Tue, 14 Apr 2026 14:59:56 +0000

Introduction to Git Sync

Caution
Git Sync is now GA for Grafana Cloud, OSS and Enterprise. Refer to Usage and performance limitations to understand usage limits for the different tiers.

Contact Grafana for support or to report any issues you encounter and help us improve this feature.

Git Sync in Grafana lets you synchronize your resources so you can store your dashboards as JSON files in any Git provider and manage them as code. You and your team can version control, collaborate, and automate deployments efficiently.

How it works

Git Sync allows you to connect external resources with your Grafana instance. After setup, all synchronized resources live in Git under the provisioned folder, and you can continue to have non-provisioned resources outside that folder.

Git Sync is bidirectional. You can modify provisioned resources both from the Grafana UI or from the synced repository, and changes will be reflected in both places.

Git Sync is available for any Git provider through a Pure Git repository type, and has specific enhanced integrations for GitHub, GitLab and Bitbucket. Refer to Usage and performance limitations for further details, including usage tiers.

Refer to key concepts for more information on how Git Sync works.

Make changes in the Grafana UI

Whenever you modify a dashboard directly from the UI, you can also commit those changes to your synchronized Git repositories upon saving. You can configure settings to either enforce PR approvals before merging in your repository, or allow direct commits.

Make changes in your Git repositories

Your Grafana instance polls the provisioned Git resources to synchronize. If you made any changes in your synchronized Git repositories, they will be updated in the Grafana database as well. The Grafana UI reads from the database and updates the UI to reflect these changes.

Without webhooks, Grafana polls for changes at the specified interval. The default polling interval is 60 seconds, and you can change this setting in the Grafana UI.
If you enable the webhooks feature, repository notifications appear almost immediately.

Common use cases

Note
Refer to Git Sync deployment scenarios for sample scenarios, including architecture and configuration details.

You can use Git Sync for the following use cases:

Version control and auditing

Organizations can maintain a structured, version-controlled history of Grafana dashboards. The version control lets you revert to previous versions when necessary, compare modifications across commits, and ensure transparency in dashboard management.

Additionally, having a detailed history of changes enhances compliance efforts, as teams can generate audit logs that document who made changes, when they were made, and why.

Automated deployment and CI/CD integration

Teams can streamline their workflow by integrating dashboard updates into their CI/CD pipelines. By pushing changes to GitHub, automated processes can trigger validation checks, test dashboard configurations, and deploy updates programmatically using the grafanactl CLI and Foundation SDK.

This reduces the risk of human errors, ensures consistency across environments, and enables a faster, more reliable release cycle for dashboards used in production monitoring and analytics.

Collaborative dashboard development

With Git Sync, multiple users can work on dashboards simultaneously without overwriting each other’s modifications. By leveraging pull requests and branch-based workflows, teams can submit changes for review before merging them into the main branch. This process not only improves quality control but also ensures that dashboards adhere to best practices and organizational standards.

Additionally, GitHub’s built-in discussion and review tools facilitate effective collaboration, making it easier to address feedback before changes go live.

Multi-environment synchronization

Enterprises managing multiple Grafana instances, such as development, staging, and production environments, can seamlessly sync dashboards across these instances. This ensures consistency in visualization and monitoring configurations, reducing discrepancies that might arise from manually managing dashboards in different environments.

By using Git Sync, teams can automate deployments across environments, eliminating repetitive setup tasks and maintaining a standardized monitoring infrastructure across the organization.

Disaster recovery and backup

By continuously syncing dashboards to GitHub, organizations can create an always-updated backup, ensuring dashboards are never lost due to accidental deletion or system failures.

If an issue arises, such as a corrupted dashboard, unintended modification, or a system crash, teams can quickly restore the latest functional version from the Git repository. This not only minimizes downtime but also adds a layer of resilience to Grafana monitoring setups, ensuring critical dashboards remain available when needed.

Build dashboards as code

Because dashboards are defined in JSON files, you can enable as-code workflows where the JSON file is an output from Go, TypeScript, or another coding language in the format of a dashboard schema.

To learn more about creating dashboards in a coding language to provision them for Git Sync, refer to the Foundation SDK documentation.

Explore Git Sync

Git Sync Key concepts
Key concepts to understand how Git Sync works.
Usage and performance limitations
Git Sync usage tiers, compatible Git providers, and known limitations.
Set up Git Sync
Instructions for setting up Git Sync, so you can provision GitHub repositories for use with Grafana.
- Setup prerequisites
  Prerequisites for Git Sync, so you can provision GitHub repositories for use with Grafana.
- Set up Git Sync as code
  Instructions for setting up Git Sync as code, so you can provision Git repositories for use with Grafana.
- Set up Git Sync with Terraform
  Instructions for setting up Git Sync as code, so you can provision Git repositories for use with Grafana.
- Instantaneous pulling and dashboard previews
  Instructions for extending Git Sync for real-time notification and image rendering.
Add non-provisioned resources from Grafana
Export non-provisioned resources from Grafana.
Work with provisioned repositories in Git Sync
Instructions for working with Git Sync to perform common tasks, such as saving dashboards to GitHub and synchronizing changes with Grafana.
Work with provisioned dashboards in Git Sync
Update, save, and modify provisioned resources in Grafana using Git Sync.
Git Sync deployment scenarios
Learn about common Git Sync deployment patterns and configurations for different organizational needs
- Single instance Git Sync
  Synchronize a single Grafana instance with a Git repository
- Git Sync for development and production environments
  Use separate Grafana instances for development and production with Git-controlled promotion
- Git Sync with regional replication
  Synchronize multiple regional Grafana instances from a shared Git location
- Git Sync for high availability environments
  Run multiple Grafana instances serving traffic simultaneously, synchronized via Git Sync
- Multiple team Git Sync
  Use multiple Git repositories with one Grafana instance, one repository per team

Provision resources on-prem

Tue, 14 Apr 2026 09:48:24 +0000

On-prem file provisioning

Caution
On-prem file provisioning is an experimental feature introduced in Grafana v12 for open source and Enterprise editions available in nightly releases. It’s not available in Grafana Cloud.

Engineering and on-call support is not available. Documentation is either limited or not provided outside of code comments. No SLA is provided.

On-prem local file provisioning allows you to configure how to store your dashboard JSON and other files from your local file system. You can set a single folder, or multiple folders to a different repository, with up to 10 connections.

With on-prem file provisioning:

All provisioned resources are changed in the local files.
The dashboards saved in your GitHub repository or local folder appear in Grafana in the ‘provisioned’ folder. The dashboards and folders saved to the local path are referred to as ‘provisioned’ resources and are labeled as such in the Grafana UI.
Any changes made in the provisioned files are reflected in the Grafana database. The Grafana UI reads the database and updates the UI to reflect these changes.
You can’t use the Grafana UI to edit or delete provisioned resources.

Explore file provisioning

Set up file provisioning
Instructions for setting up file provisioning with a local path.