[release-12.3.0] Restructure As code and developer resources (#113969)
Co-authored-by: Roberto Jiménez Sánchez <roberto.jimenez@grafana.com> Co-authored-by: Anna Urbiztondo <anna.urbiztondo@grafana.com>
This commit is contained in:
Jack Baldry
GitHub
@@ -0,0 +1,116 @@
|
||||
---
|
||||
description: Overview of Observability as Code including description, key features, and explanation of benefits.
|
||||
keywords:
|
||||
- observability
|
||||
- configuration
|
||||
- as code
|
||||
- dashboards
|
||||
- git integration
|
||||
- git sync
|
||||
- github
|
||||
labels:
|
||||
products:
|
||||
- enterprise
|
||||
- oss
|
||||
- cloud
|
||||
title: Observability as Code
|
||||
weight: 100
|
||||
cards:
|
||||
items:
|
||||
- title: Get started
|
||||
height: 24
|
||||
href: ./get-started/
|
||||
description: Learn about how you can use Observability as Code.
|
||||
- title: Grafana CLI
|
||||
height: 24
|
||||
href: ./grafana-cli/
|
||||
description: Grafana CLI (`grafanactl`) is a command-line tool designed to simplify interaction with Grafana instances. You can authenticate, manage multiple environments, and perform administrative tasks through Grafana’s REST API, all from the terminal.
|
||||
- title: JSON schema v2
|
||||
height: 24
|
||||
href: ./schema-v2/
|
||||
description: Grafana dashboards are represented as JSON objects that store metadata, panels, variables, and settings. Observability as Code works with all versions of the JSON model, and it's fully compatible with version 2.
|
||||
- title: Foundation SDK
|
||||
height: 24
|
||||
href: ./foundation-sdk/
|
||||
description: The Grafana Foundation SDK is a set of tools, types, and libraries that let you define Grafana dashboards and resources using strongly typed code.
|
||||
- title: Git Sync (private preview)
|
||||
height: 24
|
||||
href: ./provision-resources/intro-git-sync/
|
||||
description: Git Sync is an experimental feature that lets you store your dashboard files in a GitHub repository and synchronize those changes with your Grafana instance.
|
||||
- title: File provisioning (private preview)
|
||||
height: 24
|
||||
href: ./provision-resources/
|
||||
description: File provisioning in Grafana lets you include resources, including folders and dashboard JSON files, that are stored in a local file system.
|
||||
title_class: pt-0 lh-1
|
||||
hero:
|
||||
title: Observability as Code
|
||||
description: Using Observability as Code, you can version, automate, and scale Grafana configurations, including dashboards and observability workflows.
|
||||
height: 110
|
||||
level: 1
|
||||
width: 110
|
||||
canonical: https://grafana.com/docs/grafana/latest/as-code/observability-as-code/
|
||||
aliases:
|
||||
- ../observability-as-code/ # /docs/grafana/next/observability-as-code/
|
||||
---
|
||||
|
||||
{{< docs/hero-simple key="hero" >}}
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
Observability as Code lets you apply code management best practices to your observability resources.
|
||||
By representing Grafana resources as code, you can integrate them into existing infrastructure-as-code workflows and apply standard development practices.
|
||||
|
||||
Observability as Code provides more control over configuration. Instead of manually configuring dashboards or settings through the Grafana UI, you can:
|
||||
|
||||
- Write configurations in code: Define dashboards in JSON or other supported formats.
|
||||
- Sync your Grafana setup to GitHub: Track changes, collaborate, and roll back updates using Git and GitHub, or other remote sources.
|
||||
- Automate with CI/CD: Integrate Grafana directly into your development and deployment pipelines.
|
||||
- Standardize workflows: Ensure consistency across your teams by using repeatable, codified processes for managing Grafana resources.
|
||||
|
||||
## Explore
|
||||
|
||||
{{< card-grid key="cards" type="simple" >}}
|
||||
|
||||
<!-- Hiding this part of the doc because the rest of the docs aren't released yet
|
||||
|
||||
## Key features
|
||||
|
||||
At this time, Observability as Code lets you configure dashboards in static files rather than using the UI.
|
||||
The number of resources covered by this approach will expand over time.
|
||||
|
||||
### App Platform: A unified foundation
|
||||
|
||||
The [App Platform](https://github.com/grafana/grafana-app-sdk) is the backbone of Observability as Code. It provides consistent APIs for managing Grafana resources like dashboards, data sources, and service-level objectives (SLOs). With the App Platform, you gain:
|
||||
|
||||
- A stable and predictable API for integrating Grafana into your systems.
|
||||
- Support for cloud-native workflows, making it easier to build and scale observability solutions.
|
||||
- The ability to manage Grafana resources programmatically.
|
||||
- Backwards compatibility with earlier versions of Grafana APIs, so older applications still work.
|
||||
|
||||
### Git integration
|
||||
|
||||
Version control is at the heart of Observability as Code. By integrating Grafana with Git, you can:
|
||||
|
||||
- Store your dashboards in a Git repository.
|
||||
- Automatically deploy changes through CI/CD pipelines.
|
||||
- Track who made changes, when they were made, and why.
|
||||
|
||||
### Enhanced dashboard management
|
||||
|
||||
Dashboards are central to Grafana’s value, and Observability as Code introduces improvements to make them easier to work with:
|
||||
|
||||
- **Ready for Schema v2:** An experimental dashboard schema that simplifies dashboards definition, separating properties for better clarity and making configurations more intuitive.
|
||||
- **New layout options:** Flexible layouts, including a new responsive grid layout that allow for more dynamic and responsive panel layouts.
|
||||
- **Improved metadata management:** Add descriptions, tags, and other metadata to better organize and understand your dashboards.
|
||||
|
||||
### Tooling and integrations
|
||||
|
||||
Observability as Code comes with tools to make your workflows seamless:
|
||||
|
||||
- Examples and best practices for integrating Grafana with tools like Terraform, Kubernetes, and GitHub Actions.
|
||||
- The Foundation SDK provides a set of libraries for getting started quickly configuring and manipulating Grafana resources.
|
||||
- A command line tool for configuring your dashboards programmatically.
|
||||
- Documentation, videos, and SDKs to help you get started quickly.
|
||||
-->
|
||||
@@ -0,0 +1,306 @@
|
||||
---
|
||||
description: Learn about the Foundation SDK, a set of tools, types, and libraries for defining Grafana dashboards and resources.
|
||||
keywords:
|
||||
- as code
|
||||
- as-code
|
||||
- Foundation SDK
|
||||
labels:
|
||||
products:
|
||||
- enterprise
|
||||
- oss
|
||||
title: Foundation SDK
|
||||
weight: 250
|
||||
canonical: https://grafana.com/docs/grafana/latest/as-code/observability-as-code/foundation-sdk/
|
||||
aliases:
|
||||
- ../../observability-as-code/foundation-sdk/ # /docs/grafana/next/observability-as-code/foundation-sdk/
|
||||
---
|
||||
|
||||
# Get started with the Grafana Foundation SDK
|
||||
|
||||
The [Grafana Foundation SDK](https://github.com/grafana/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.
|
||||
|
||||
{{< youtube id="_OKQoABmg0Q" >}}
|
||||
|
||||
## 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 version you’re using (refer to the [compatibility matrix](https://github.com/grafana/grafana-foundation-sdk#navigating-the-sdk)).
|
||||
- **Package manager:** Appropriate for your language, for example, `npm` or `yarn` for TypeScript or `pip` for Python.
|
||||
|
||||
To get started, clone the [intro-to-foundation-sdk repository](https://github.com/grafana/intro-to-foundation-sdk) to access examples and a `docker-compose` stack.
|
||||
|
||||
## Install the Grafana Foundation SDK
|
||||
|
||||
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.
|
||||
{{< code >}}
|
||||
|
||||
```go
|
||||
go get github.com/grafana/grafana-foundation-sdk/go@next+cog-v0.0.x
|
||||
```
|
||||
|
||||
```typescript
|
||||
npm install @grafana/grafana-foundation-sdk
|
||||
```
|
||||
|
||||
{{< /code >}}
|
||||
|
||||
## Grafana Foundation SDK Overview
|
||||
|
||||
Here's a quick overview of how the Grafana Foundation SDK works:
|
||||
|
||||
- **Builder pattern:** The SDK uses a chainable builder pattern to let you define dashboards fluently. You start with a `DashboardBuilder`, then add panels, queries, and other components step by step.
|
||||
- **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.
|
||||
- **Structured options:** When a configuration get complex (like data reduction or display settings), the SDK uses typed option builders to keep things readable and predictable.
|
||||
|
||||
You'll see these concepts in action in the next example. These concepts are explained in more detail afterwards.
|
||||
|
||||
## Create a dashboard
|
||||
|
||||
The following example demonstrates how you can create a simple dashboard:
|
||||
|
||||
{{< code >}}
|
||||
|
||||
```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));
|
||||
```
|
||||
|
||||
{{< /code >}}
|
||||
|
||||
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.
|
||||
|
||||
## 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 [Grafana's API](/docs/grafana/<GRAFANA_VERSION>/developer-resources/api-reference/http-api/) or the [Grafana CLI](../grafana-cli/) to programmatically upload the dashboard JSON.
|
||||
|
||||
## Concepts
|
||||
|
||||
Now that you've seen how to define a basic dashboard using code, let's take a moment to explain how it all works behind the scenes. The Grafana Foundation SDK is built around a few core concepts that make your dashboards structured, reusable, and strongly typed.
|
||||
|
||||
### Builders
|
||||
|
||||
The SDK follows a builder pattern, which lets you compose dashboards step-by-step using chained method calls.
|
||||
Almost every piece of the dashboard, including dashboards, panels, rows, queries, and variables, has its own `Builder` class.
|
||||
|
||||
Here are a few you've already seen:
|
||||
|
||||
- `DashboardBuilder` - Starts the dashboard definition and sets global configuration settings like title, UID, refresh interval, time range, etc.
|
||||
- `PanelBuilder` - Creates individual visualizations like time series panels, stat panels, or log panels.
|
||||
- `DataqueryBuilder` - Defines how a panel fetches data, for example, from Prometheus or the `testdata` plugin.
|
||||
|
||||
Builders are chainable, so you can fluently compose dashboards in a readable, structured way:
|
||||
|
||||
{{< code >}}
|
||||
|
||||
```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'));
|
||||
```
|
||||
|
||||
{{< /code >}}
|
||||
|
||||
### Types
|
||||
|
||||
The Grafana Foundation SDK uses strong types under the hood to help catch mistakes before you deploy a broken dashboard.
|
||||
|
||||
For example:
|
||||
|
||||
- When setting a unit, you'll get autocomplete suggestions for valid Grafana units like `"percent"` or `"bps"`.
|
||||
- When defining a time range, you'll be guided to provide the correct structure, like `from` and `to` values.
|
||||
- When referencing data sources, you'll use a structured `DataSourceRef` object with defined `type` and `uid` fields.
|
||||
|
||||
This helps you:
|
||||
|
||||
- Avoid typos or unsupported configuration values
|
||||
- Get full autocomplete and inline documentation in your IDE
|
||||
- Write dashboards that are less error-prone and easier to maintain
|
||||
|
||||
Strong typing also makes it easier to build reusable patterns and components with confidence, especially in large codebases or teams.
|
||||
|
||||
### Options
|
||||
|
||||
Most builder methods accept simple values like strings or numbers, but others expect more structured option objects. These are used for things like:
|
||||
|
||||
- `ReduceDataOptions` - How to reduce time series data into single values (e.g. last, avg).
|
||||
- `VizLegendOptions` - Configure how the legend of a panel is displayed.
|
||||
- `CanvasElementOptions` - Define how the the various components of a Canvas panel should be displayed.
|
||||
|
||||
Example using options:
|
||||
|
||||
{{< code >}}
|
||||
|
||||
```go
|
||||
stat.NewPanelBuilder().
|
||||
ReduceOptions(common.NewReduceDataOptionsBuilder().
|
||||
Calcs([]string{"lastNotNull"}).
|
||||
Fields("/.*/"))
|
||||
)
|
||||
```
|
||||
|
||||
```typescript
|
||||
new stat.PanelBuilder().reduceOptions(new common.ReduceDataOptionsBuilder().calcs(['lastNotNull']).fields('/.*/'));
|
||||
```
|
||||
|
||||
{{< /code >}}
|
||||
|
||||
By using option builders, you don't need to manually construct deeply nested configuration objects. Instead, the SDK gives you a typed and guided API that mirrors a dashboards internal structure, making it easier to configure complex options without guesswork or referring back to the JSON schema.
|
||||
|
||||
## 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:
|
||||
|
||||
{{< youtube id="ZjWdGVsrCiQ" >}}
|
||||
|
||||
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](https://github.com/grafana/intro-to-foundation-sdk/tree/main/generate-and-deploy-example).
|
||||
|
||||
## Summary
|
||||
|
||||
The Grafana Foundation SDK is designed to make dashboard creation:
|
||||
|
||||
- **Composable** through the use of chainable builders
|
||||
- **Safe** with strong typing and clear APIs
|
||||
- **Configurable** using structured options for fine 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](https://grafana.github.io/grafana-foundation-sdk/) to explore what's possible.
|
||||
|
||||
## 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](https://grafana.github.io/grafana-foundation-sdk/) 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](./dashboard-automation) to deploy dashboards automatically.
|
||||
@@ -0,0 +1,260 @@
|
||||
---
|
||||
description: Learn how to automatically generate and deploy Grafana dashboards as code with GitHub Actions.
|
||||
keywords:
|
||||
- foundation SDK
|
||||
- dashboard provisioning
|
||||
- CI/CD
|
||||
- GitHub Actions
|
||||
labels:
|
||||
products:
|
||||
- cloud
|
||||
- enterprise
|
||||
- oss
|
||||
title: Automate dashboard provisioning with CI/CD
|
||||
weight: 200
|
||||
canonical: https://grafana.com/docs/grafana/latest/as-code/observability-as-code/foundation-sdk/dashboard-automation/
|
||||
aliases:
|
||||
- ../../../observability-as-code/foundation-sdk/dashboard-automation/ # /docs/grafana/next/observability-as-code/foundation-sdk/dashboard-automation/
|
||||
---
|
||||
|
||||
# Automate dashboard provisioning with CI/CD
|
||||
|
||||
## Introduction
|
||||
|
||||
Managing Grafana dashboards manually can be inefficient and error-prone. As you saw in the Getting Started guide, we can define dashboards using strongly typed code with the Grafana Foundation SDK. We can then commit them to version controls, and automatically deploy them using GitHub Actions.
|
||||
|
||||
This guide walks through:
|
||||
|
||||
- Generating a Grafana dashboard as code
|
||||
- Formatting it for Kubernetes-style deployment
|
||||
- Using GitHub Actions to deploy the dashboard
|
||||
- Checking if the dashboard exists and updating it if needed
|
||||
|
||||
By the end, every change to your dashboard code will be automatically created or updated in your Grafana instance without manual intervention.
|
||||
|
||||
{{< youtube id="cFnO8kVOaAI" >}}
|
||||
|
||||
You can find the full example source code in the [intro-to-foundation-sdk repository](https://github.com/grafana/intro-to-foundation-sdk/tree/main/github-actions-example).
|
||||
|
||||
## 1. Generating the dashboard JSON
|
||||
|
||||
Before deploying a dashboard, we need to define it in code using the Grafana Foundation SDK. We ran through an example of this in the Getting Started guide, however, in order to comply with the Kubernetes resource compatible API that Grafana exposes, we’ll make some changes to the code to output the dashboard JSON in the appropriate format.
|
||||
|
||||
{{< code >}}
|
||||
|
||||
```go
|
||||
package main
|
||||
|
||||
import (
|
||||
"encoding/json"
|
||||
"log"
|
||||
"os"
|
||||
|
||||
"github.com/grafana/grafana-foundation-sdk/go/cog"
|
||||
"github.com/grafana/grafana-foundation-sdk/go/common"
|
||||
"github.com/grafana/grafana-foundation-sdk/go/dashboard"
|
||||
)
|
||||
|
||||
type DashboardWrapper struct {
|
||||
APIVersion string `json:"apiVersion"`
|
||||
Kind string `json:"kind"`
|
||||
Metadata Metadata `json:"metadata"`
|
||||
Spec dashboard.Dashboard `json:"spec"`
|
||||
}
|
||||
|
||||
type Metadata struct {
|
||||
Name string `json:"name"`
|
||||
}
|
||||
|
||||
func main() {
|
||||
builder := dashboard.NewDashboardBuilder("My Dashboard").
|
||||
Uid("my-dashboard").
|
||||
Tags([]string{"generated", "foundation-sdk", "go"}).
|
||||
Refresh("5m").
|
||||
Time("now-1h", "now").
|
||||
Timezone(common.TimeZoneBrowser).
|
||||
WithRow(dashboard.NewRowBuilder("Overview"))
|
||||
|
||||
dashboard, err := builder.Build()
|
||||
if err != nil {
|
||||
log.Fatalf("failed to build dashboard: %v", err)
|
||||
}
|
||||
|
||||
dashboardWrapper := DashboardWrapper{
|
||||
APIVersion: "dashboard.grafana.app/v1beta1",
|
||||
Kind: "Dashboard",
|
||||
Metadata: Metadata{
|
||||
Name: *dashboard.Uid,
|
||||
},
|
||||
Spec: dashboard,
|
||||
}
|
||||
|
||||
dashboardJson, err := json.MarshalIndent(dashboardWrapper, "", " ")
|
||||
if err != nil {
|
||||
log.Fatalf("failed to marshal dashboard: %v", err)
|
||||
}
|
||||
|
||||
err = os.WriteFile("dashboard.json", dashboardJson, 0644)
|
||||
if err != nil {
|
||||
log.Fatalf("failed to write dashboard to file: %v", err)
|
||||
}
|
||||
|
||||
log.Printf("Dashboard JSON:\n%s", dashboardJson)
|
||||
}
|
||||
```
|
||||
|
||||
```typescript
|
||||
import { DashboardBuilder, RowBuilder } from '@grafana/grafana-foundation-sdk/dashboard';
|
||||
import * as fs from 'fs';
|
||||
|
||||
// Generate the dashboard JSON
|
||||
const dashboard = new DashboardBuilder('My Dashboard')
|
||||
.uid('my-dashboard')
|
||||
.tags(['generated', 'foundation-sdk', 'typescript'])
|
||||
.refresh('5m')
|
||||
.time({ from: 'now-1h', to: 'now' })
|
||||
.timezone('browser')
|
||||
.withRow(new RowBuilder('Overview'))
|
||||
.build();
|
||||
|
||||
// Convert to Kubernetes-style format
|
||||
const dashboardWrapper = {
|
||||
apiVersion: "dashboard.grafana.app/v1beta1",
|
||||
kind: "Dashboard",
|
||||
metadata: {
|
||||
name: dashboard.uid!
|
||||
},
|
||||
spec: dashboard
|
||||
};
|
||||
|
||||
// Save the formatted JSON to a file
|
||||
const dashboardJSON = JSON.stringify(dashboardWrapper, null, 2);
|
||||
fs.writeFileSync('dashboard.json', dashboardJSON, 'utf8');
|
||||
|
||||
console.log(`Dashboard JSON:\n${}`);
|
||||
```
|
||||
|
||||
{{< /code >}}
|
||||
|
||||
This script:
|
||||
|
||||
- Generates a Grafana dashboard JSON file
|
||||
- Wraps it in a Kubernetes-style API format (`apiVersion`, `kind`, `metadata`, `spec`)
|
||||
- Saves it as `dashboard.json` for deployment
|
||||
|
||||
## 2. Automating deployment with GitHub Actions
|
||||
|
||||
Next, we’ll set up GitHub Actions to:
|
||||
Extract the dashboard name from `dashboard.json`
|
||||
Check if the dashboard already exists within our Grafana instance
|
||||
Update it if it does, create it if it doesn’t
|
||||
|
||||
{{< admonition type="note" >}}
|
||||
The following GitHub Action configuration assumes you are using a Go-based dashboard generator. If you are using one of the other languages that the Foundation SDK supports, please modify the **Generate Dashboard JSON** step accordingly.
|
||||
{{< /admonition >}}
|
||||
|
||||
`.github/workflows/deploy-dashboard.yml`
|
||||
|
||||
```yaml
|
||||
name: Deploy Grafana Dashboard
|
||||
|
||||
on:
|
||||
push:
|
||||
branches:
|
||||
- main
|
||||
|
||||
jobs:
|
||||
deploy:
|
||||
runs-on: ubuntu-latest
|
||||
|
||||
steps:
|
||||
- name: Checkout code
|
||||
uses: actions/checkout@v3
|
||||
|
||||
- name: Set up Go
|
||||
uses: actions/setup-go@v5
|
||||
with:
|
||||
go-version: 1.24.6
|
||||
|
||||
- name: Verify Go version
|
||||
run: go version
|
||||
|
||||
- name: Download and Extract grafanactl
|
||||
run: |
|
||||
curl -L -o grafanactl-x86_64.tar.gz "https://github.com/grafana/grafanactl/releases/download/${{ vars.GRAFANACTL_VERSION }}/grafanactl_Linux_x86_64.tar.gz"
|
||||
tar -xzf grafanactl-x86_64.tar.gz
|
||||
chmod +x grafanactl
|
||||
sudo mv grafanactl /usr/local/bin/grafanactl
|
||||
|
||||
- name: Generate Dashboard JSON
|
||||
working-directory: ./github-actions-example
|
||||
run: go run main.go
|
||||
|
||||
- name: Deploy Dashboard with grafanactl
|
||||
env:
|
||||
GRAFANA_SERVER: ${{ vars.GRAFANA_SERVER }}
|
||||
GRAFANA_STACK_ID: ${{ vars.GRAFANA_STACK_ID }}
|
||||
GRAFANA_TOKEN: ${{ secrets.GRAFANA_TOKEN }}
|
||||
run: |
|
||||
if [ -f dashboard.json ]; then
|
||||
echo "dashboard.json exists, deploying dashboard."
|
||||
grafanactl resources push dashboards --path ./dashboard.json
|
||||
else
|
||||
echo "dashboard.json does not exist."
|
||||
exit 1
|
||||
fi
|
||||
working-directory: ./github-actions-example
|
||||
```
|
||||
|
||||
## 3. Explaining this GitHub Action
|
||||
|
||||
This GitHub Action automates the deployment of a Grafana dashboard using the Foundation SDK and the `grafanactl` CLI tool.
|
||||
|
||||
### 1. Checkout and set up Go
|
||||
|
||||
The first few steps:
|
||||
|
||||
- Check out the repository to access the project code.
|
||||
- Install Go 1.24.6 using the `actions/setup-go` action.
|
||||
- Verify Go is properly installed.
|
||||
|
||||
### 2. Download and install `grafanactl`
|
||||
|
||||
This step downloads the `grafanactl` CLI from GitHub using a version defined in `vars.GRAFANACTL_VERSION`. It unpacks the tarball, makes it executable, and moves it to a location in the system `PATH`.
|
||||
|
||||
### 3. Generate the dashboard JSON
|
||||
|
||||
Runs the dashboard generator (`main.go`) from the `./github-actions-example` directory. This should produce a `dashboard.json` file that contains the Grafana dashboard definition.
|
||||
|
||||
### 4. Deploy the dashboard with `grafanactl`
|
||||
|
||||
If `dashboard.json` exists, it is deployed to your Grafana instance using:
|
||||
|
||||
```bash
|
||||
grafanactl resources push dashboards --path ./dashboard.json
|
||||
```
|
||||
|
||||
This command authenticates against Grafana using the following environment variables:
|
||||
|
||||
- `GRAFANA_SERVER`: Your Grafana instance URL
|
||||
- `GRAFANA_STACK_ID`: Your Grafana stack ID
|
||||
- `GRAFANA_TOKEN`: A Grafana service account token with sufficient permissions
|
||||
|
||||
### GitHub variables and secrets used
|
||||
|
||||
These are configured in your repository under **Settings → Security → Secrets and variables → Actions**:
|
||||
|
||||
- `vars.GRAFANACTL_VERSION`: Version of `grafanactl` to install
|
||||
- `vars.GRAFANA_SERVER`: The URL of your Grafana instance
|
||||
- `vars.GRAFANA_STACK_ID`: The stack ID in Grafana
|
||||
- `secrets.GRAFANA_TOKEN`: Grafana API token
|
||||
|
||||
This action ensures that every push to `main` will regenerate and deploy your latest dashboard definition to Grafana.
|
||||
|
||||
### Why automate this?
|
||||
|
||||
Automating Grafana dashboard deployment eliminates the need for manual dashboard creation and updates, ensuring that dashboards remain consistent across environments. By defending dashboards as code and managing them through CI/CD such as GitHub Actions, we gain full version control, making it easy to track changes over time and roll back if needed. This also prevents duplication, as the workflow intelligently checks whether a dashboard exists before deciding to create or update it. With this fully automated CI/CD pipeline, developers can focus on improving their dashboards rather than manually uploading JSON files to Grafana.
|
||||
|
||||
### Conclusion
|
||||
|
||||
By integrating the Grafana Foundation SDK with GitHub Actions, we have successfully automated the entire lifecycle of Grafana dashboards. This setup allows us to define dashboards programmatically, convert them into a Kubernetes-compatible format, and deploy them automatically. With each push to the repository, the workflow ensures that dashboards are either created or updated as needed. This not only improves the efficiency but also guarantees that all deployed dashboards are always in sync with the latest code changes, reducing manual effort and potential errors.
|
||||
@@ -0,0 +1,88 @@
|
||||
---
|
||||
description: Get started with Observability as Code by exploring the documentation, libraries, and tools available for as-code practices.
|
||||
keywords:
|
||||
- configuration
|
||||
- as code
|
||||
- as-code
|
||||
- dashboards
|
||||
- Git Sync
|
||||
- Git
|
||||
labels:
|
||||
products:
|
||||
- enterprise
|
||||
- oss
|
||||
title: Get started with Observability as Code
|
||||
weight: 100
|
||||
canonical: https://grafana.com/docs/grafana/latest/as-code/observability-as-code/get-started/
|
||||
aliases:
|
||||
- ../../observability-as-code/get-started/ # /docs/grafana/next/observability-as-code/get-started/
|
||||
---
|
||||
|
||||
# Get started with Observability as Code
|
||||
|
||||
Grafana provides a suite of tools for **Observability as Code** to help you manage your Grafana resources programmatically and at scale. This approach lets you define dashboards, data sources, and other configurations in code, enabling version control, automated testing, and reliable deployments through CI/CD pipelines.
|
||||
|
||||
Historically, managing Grafana as code involved various community and Grafana Labs tools, but lacked a single, cohesive story. Grafana 12 introduces foundational improvements, including new versioned APIs and official tooling, to provide a clearer path forward.
|
||||
|
||||
## Grafana CLI (`grafanactl`)
|
||||
|
||||
Use the official command-line tool, `grafanactl`, to interact with your Grafana instances and manage resources via the new APIs.
|
||||
|
||||
- It's the recommended tool for automation and direct API interaction, suitable for CI/CD pipelines and local development or free-form tasks. It supports pulling/pushing configurations from remote instances, validating configurations, and more.
|
||||
- `grafanactl` works across all environments for Grafana OSS, Enterprise, and Cloud.
|
||||
|
||||
Refer to the [Grafana CLI (`grafanactl`)](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/observability-as-code/grafana-cli) documentation for more information.
|
||||
|
||||
## Git Sync
|
||||
|
||||
For an integrated, UI-driven Git workflow focused on dashboards, explore Git Sync.
|
||||
|
||||
- Connect folders or entire Grafana instances directly to a GitHub repository to synchronize dashboard definitions, enabling version control, branching, and pull requests directly from Grafana.
|
||||
- Git Sync offers a simple, out-of-the-box approach for managing dashboards as code.
|
||||
{{< admonition type="note" >}}
|
||||
Git Sync is available in **private preview** for Grafana Cloud, and it's an **experimental feature** in Grafana 12, available in Grafana OSS and Enterprise [nightly releases](https://grafana.com/grafana/download/nightly).
|
||||
{{< /admonition >}}
|
||||
|
||||
Refer to the [Git Sync documentation](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/observability-as-code/provision-resources/intro-git-sync/) to learn more.
|
||||
|
||||
## Direct API usage
|
||||
|
||||
For maximum flexibility, advanced use cases, or building custom tooling, you can interact directly with the underlying versioned APIs.
|
||||
|
||||
- This approach requires handling HTTP requests and responses but provides complete control over resource management.
|
||||
- `grafanactl`, Git Sync, and the Foundation SDK are all built on top of these APIs.
|
||||
- To understand Dashboard Schemas accepted by the APIs, refer to the [JSON models documentation](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/observability-as-code/schema-v2/).
|
||||
|
||||
Refer to the [Grafana APIs](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/developers/http_api/apis/) documentation for more information.
|
||||
|
||||
## Foundation SDK
|
||||
|
||||
To programmatically define your Grafana resources (like dashboards or alerts) using familiar programming languages, use Foundation SDK.
|
||||
|
||||
- Define resources using strongly typed builders in languages like Go, TypeScript, Python, Java, and PHP.
|
||||
- Avoid crafting complex JSON manually and integrate resource generation into your existing development workflows.
|
||||
- Catch errors at compile time and easily integrate resource generation into your CI/CD pipelines.
|
||||
- Use in conjunction with `grafanactl` to push your programmatically generated resources.
|
||||
|
||||
Refer to the [Foundation SDK](../foundation-sdk) documentation for more information.
|
||||
|
||||
## Additional Observability as Code tools
|
||||
|
||||
If you're already using established Infrastructure as Code or other configuration management tools, Grafana offers integrations to manage resources within your existing workflows.
|
||||
|
||||
- [Terraform](https://grafana.com/docs/grafana-cloud/as-code/infrastructure-as-code/terraform/)
|
||||
- Use the Grafana Terraform provider to manage dashboards, alerts, and more.
|
||||
- Understand how to define and deploy resources using HCL/JSON configurations.
|
||||
|
||||
- [Ansible](https://grafana.com/docs/grafana-cloud/as-code/infrastructure-as-code/ansible/)
|
||||
- Learn to use the Grafana Ansible collection to manage Grafana Cloud resources, including folders and cloud stacks.
|
||||
- Write playbooks to automate resource provisioning through the Grafana API.
|
||||
|
||||
- [Grafana Operator](https://grafana.com/docs/grafana-cloud/as-code/infrastructure-as-code/grafana-operator/)
|
||||
- Utilize Kubernetes-native management with the Grafana Operator.
|
||||
- Manage dashboards, folders, and data sources via Kubernetes Custom Resources.
|
||||
- Integrate with GitOps workflows for seamless version control and deployment.
|
||||
|
||||
- [Crossplane](https://github.com/grafana/crossplane-provider-grafana) lets you manage Grafana resources using Kubernetes manifests with the Grafana Crossplane provider.
|
||||
- [Grafonnet](https://github.com/grafana/grafonnet) is a Jsonnet library for generating Grafana dashboard JSON definitions programmatically.
|
||||
- [Grizzly](https://grafana.com/docs/grafana-cloud/as-code/infrastructure-as-code/grizzly/dashboards-folders-datasources/) is a deprecated command-line tool that simplifies managing Grafana resources using Kubernetes-inspired YAML syntax.
|
||||
@@ -0,0 +1,50 @@
|
||||
---
|
||||
description: Overview of Grafana CLI, a command line tool for managing Grafana resources as code.
|
||||
keywords:
|
||||
- observability
|
||||
- configuration
|
||||
- as code
|
||||
- as-code
|
||||
- dashboards
|
||||
- git integration
|
||||
- git sync
|
||||
- github
|
||||
labels:
|
||||
products:
|
||||
- cloud
|
||||
- enterprise
|
||||
- oss
|
||||
cards:
|
||||
items:
|
||||
- description: Learn how to install Grafana CLI
|
||||
height: 24
|
||||
href: ./install-grafana-cli/
|
||||
title: Install Grafana CLI
|
||||
- description: Set up Grafana CLI
|
||||
height: 24
|
||||
href: ./set-up-grafana-cli/
|
||||
title: Set up your Grafana CLI
|
||||
- description: Learn how to manage resources with Grafana CLI
|
||||
height: 24
|
||||
href: ./grafanacli-workflows
|
||||
title: Manage resources with Grafana CLI
|
||||
title_class: pt-0 lh-1
|
||||
hero:
|
||||
description: Grafana CLI (`grafanactl`) is a command-line tool designed to simplify interaction with Grafana instances. It enables users to authenticate, manage multiple environments, and perform administrative tasks through Grafana’s REST API, all from the terminal. Whether you're automating workflows in CI/CD pipelines or switching between staging and production environments, Grafana CLI provides a flexible and scriptable way to manage your Grafana setup efficiently.
|
||||
height: 110
|
||||
level: 1
|
||||
title: Grafana CLI
|
||||
width: 110
|
||||
title: Introduction to Grafana CLI
|
||||
menuTitle: Grafana CLI
|
||||
weight: 130
|
||||
canonical: https://grafana.com/docs/grafana/latest/as-code/observability-as-code/grafana-cli/
|
||||
aliases:
|
||||
- ../../observability-as-code/grafana-cli/ # /docs/grafana/next/observability-as-code/grafana-cli/
|
||||
---
|
||||
|
||||
{{< docs/hero-simple key="hero" >}}
|
||||
|
||||
## Explore
|
||||
|
||||
{{< card-grid key="cards" type="simple" >}}
|
||||
@@ -0,0 +1,224 @@
|
||||
---
|
||||
description: Learn more about the supported workflows and use cases for Grafana CLI
|
||||
keywords:
|
||||
- workflows
|
||||
- Grafana CLI
|
||||
- CLI
|
||||
- command line
|
||||
- grafanactl
|
||||
labels:
|
||||
products:
|
||||
- cloud
|
||||
- enterprise
|
||||
- oss
|
||||
title: Manage resources with Grafana CLI
|
||||
weight: 300
|
||||
canonical: https://grafana.com/docs/grafana/latest/as-code/observability-as-code/grafana-cli/grafanacli-workflows/
|
||||
aliases:
|
||||
- ../../../observability-as-code/grafana-cli/grafanacli-workflows/ # /docs/grafana/next/observability-as-code/grafana-cli/grafanacli-workflows/
|
||||
---
|
||||
|
||||
# Manage resources with Grafana CLI
|
||||
|
||||
{{< admonition type="note" >}}
|
||||
`grafanactl` is under active development. Command-line flags and subcommands described here may change. This document outlines the target workflows the tool is expected to support. You can find a full list of supported commands [in this page](https://grafana.github.io/grafanactl/reference/cli/grafanactl/).
|
||||
{{< /admonition >}}
|
||||
|
||||
## Migrate resources between environments
|
||||
|
||||
Using the `config` and `resources` options, you can migrate Grafana resources from one environment to another, for example, from a development to production environment.
|
||||
The `config` option lets you define the configuration context.
|
||||
Using `resources` with `pull`, `push`, and `serve` lets you pull a defined resource from one instance, and push that resource to another instance. `Serve` allows you to preview changes locally before pushing.
|
||||
|
||||
Use these steps to migrate resources between environments:
|
||||
|
||||
{{< admonition type="note" >}}
|
||||
Currently, the `serve` command only works with dashboards.
|
||||
{{< /admonition >}}
|
||||
|
||||
Use these steps to migrate resources between environments:
|
||||
|
||||
{{< admonition type="note" >}}
|
||||
Resources are pulled and pushed from the `./resources` directory by default.
|
||||
This can be configured with the `-p, --path` flags to specify custom paths on disk.
|
||||
{{< /admonition >}}
|
||||
|
||||
1. Make changes to dashboards and other resources using the Grafana UI in your **development instance**.
|
||||
1. Pull those resources from the development environment to your local machine:
|
||||
|
||||
```bash
|
||||
grafanactl config use-context YOUR_CONTEXT # for example "dev"
|
||||
grafanactl resources pull --path ./resources/ -o yaml # or json
|
||||
```
|
||||
|
||||
1. (Optional) Preview the resources locally before pushing:
|
||||
|
||||
```bash
|
||||
grafanactl config use-context YOUR_CONTEXT # for example "prod"
|
||||
grafanactl resources serve ./resources/
|
||||
```
|
||||
|
||||
1. Switch to the **production instance** and push the resources:
|
||||
|
||||
```bash
|
||||
grafanactl config use-context YOUR_CONTEXT # for example "prod"
|
||||
grafanactl resources push -p ./resources/
|
||||
```
|
||||
|
||||
## Back up Grafana resources
|
||||
|
||||
This workflow helps you back up all Grafana resources from one instance and later restore them. This is useful to replicate a configuration or perform disaster recovery.
|
||||
|
||||
1. Use `grafanactl` to pull all resources from your target environment:
|
||||
|
||||
```bash
|
||||
grafanactl config use-context YOUR_CONTEXT # for example "prod"
|
||||
grafanactl resources pull --path ./resources/ -o yaml # or json
|
||||
```
|
||||
|
||||
1. Save the exported resources to version control or cloud storage.
|
||||
|
||||
## Restore Grafana resources
|
||||
|
||||
1. (Optional) Preview the backup locally:
|
||||
|
||||
```bash
|
||||
grafanactl config use-context YOUR_CONTEXT # for example "prod"
|
||||
grafanactl resources serve ./resources/
|
||||
```
|
||||
|
||||
1. To restore the resources later or restore them on another instance, push the saved resources:
|
||||
|
||||
```bash
|
||||
grafanactl config use-context YOUR_CONTEXT # for example "prod"
|
||||
grafanactl resources push -p ./resources/
|
||||
```
|
||||
|
||||
## Manage dashboards as code
|
||||
|
||||
With this workflow, you can define and manage dashboards as code, saving them to a version control system like Git. This is useful for teams that want to maintain a history of changes, collaborate on dashboard design, and ensure consistency across environments.
|
||||
|
||||
1. Use a dashboard generation script (for example, with the [Foundation SDK](https://github.com/grafana/grafana-foundation-sdk)). You can find an example implementation in the Grafana as code [hands-on lab repository](https://github.com/grafana/dashboards-as-code-workshop/tree/main/part-one-golang-starter).
|
||||
|
||||
1. Serve and preview the output of the dashboard generator locally:
|
||||
|
||||
```bash
|
||||
grafanactl config use-context YOUR_CONTEXT # for example "dev"
|
||||
grafanactl resources serve --script 'go run scripts/generate-dashboard.go' --watch './scripts'
|
||||
```
|
||||
|
||||
1. When the output looks correct, generate dashboard manifest files:
|
||||
|
||||
```bash
|
||||
go run scripts/generate-dashboard.go --generate-resource-manifests --output './resources'
|
||||
```
|
||||
|
||||
1. Push the generated resources to your Grafana instance:
|
||||
|
||||
```bash
|
||||
grafanactl config use-context YOUR_CONTEXT # for example "dev"
|
||||
grafanactl resources push -p ./resources/
|
||||
```
|
||||
|
||||
## Explore and modify resources from the terminal
|
||||
|
||||
This section describes how to use the Grafana CLI to interact with Grafana resources directly from your terminal. These commands allow you to browse, inspect, update, and delete resources without using the Grafana UI. This approach is useful for advanced users who want to manage resources more efficiently or integrate Grafana operations into automated workflows.
|
||||
|
||||
### Find and delete dashboards using invalid data sources
|
||||
|
||||
Use this workflow to identify dashboards that reference incorrect or outdated data sources, and remove them if necessary.
|
||||
|
||||
1. Set the context to the appropriate environment:
|
||||
|
||||
```bash
|
||||
grafanactl config use-context YOUR_CONTEXT # for example "prod"
|
||||
```
|
||||
|
||||
1. Find dashboards using specific data sources:
|
||||
|
||||
```bash
|
||||
grafanactl resources get dashboards -ojson | jq '.items | map({ uid: .metadata.name, datasources: .spec.panels | map(.datasource.uid) })'
|
||||
[
|
||||
{
|
||||
"uid": "important-production-dashboard",
|
||||
"datasources": [
|
||||
"mimir-prod"
|
||||
]
|
||||
},
|
||||
{
|
||||
"uid": "test-dashboard-from-dev",
|
||||
"datasources": [
|
||||
"mimir-prod",
|
||||
"mimir-dev"
|
||||
]
|
||||
},
|
||||
{
|
||||
"uid": "test-dashboard-from-stg",
|
||||
"datasources": [
|
||||
"mimir-prod",
|
||||
"mimir-stg",
|
||||
"mimir-dev"
|
||||
]
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
This command lists dashboard UIDs along with the data source UIDs used in their panels. You can then identify the dashboards that are using invalid or unexpected data sources.
|
||||
|
||||
1. Delete the identified dashboards directly:
|
||||
|
||||
```bash
|
||||
grafanactl resources delete dashboards/test-dashboard-from-stg,test-dashboard-from-dev
|
||||
✔ 2 resources deleted, 0 errors
|
||||
```
|
||||
|
||||
### Find and deprecate dashboards using the old API version
|
||||
|
||||
Use this workflow to locate dashboards using a deprecated API version and mark them accordingly.
|
||||
|
||||
1. Set the context to the appropriate environment:
|
||||
|
||||
```bash
|
||||
grafanactl config use-context YOUR_CONTEXT # for example "prod"
|
||||
```
|
||||
|
||||
1. List all available resources types and versions:
|
||||
|
||||
```bash
|
||||
grafanactl resources list
|
||||
```
|
||||
|
||||
This command returns a list of resources, including their versions, types, and quantities:
|
||||
|
||||
```bash
|
||||
GROUP VERSION KIND
|
||||
folder.grafana.app v1 folder
|
||||
dashboard.grafana.app v1 dashboard
|
||||
dashboard.grafana.app v1 librarypanel
|
||||
dashboard.grafana.app v2 dashboard
|
||||
dashboard.grafana.app v2 librarypanel
|
||||
playlist.grafana.app v1 playlist
|
||||
```
|
||||
|
||||
1. Find dashboards that are still using a deprecated API version:
|
||||
|
||||
```bash
|
||||
grafanactl resources get dashboards.v1.dashboard.grafana.app
|
||||
```
|
||||
|
||||
This command returns a table displaying the resource type, resource name, and associated namespace:
|
||||
|
||||
```bash
|
||||
KIND NAME NAMESPACE
|
||||
dashboards really-old-dashboard default
|
||||
```
|
||||
|
||||
1. Edit each of these dashboards to add a `deprecated` tag:
|
||||
|
||||
```bash
|
||||
grafanactl resources edit dashboards.v1.dashboard.grafana.app/really-old-dashboard -p '{"spec":{"tags":["deprecated"]}}'
|
||||
```
|
||||
|
||||
{{< admonition type="tip" >}}
|
||||
You can get help by using the `grafanactl --help` command.
|
||||
{{< /admonition >}}
|
||||
@@ -0,0 +1,49 @@
|
||||
---
|
||||
description: Installation guide for Grafana CLI, a command line tool for managing Grafana Observability as Code
|
||||
keywords:
|
||||
- configuration
|
||||
- Grafana CLI
|
||||
- CLI
|
||||
- command line
|
||||
- grafanactl
|
||||
- installation
|
||||
labels:
|
||||
products:
|
||||
- cloud
|
||||
- enterprise
|
||||
- oss
|
||||
title: Install Grafana CLI
|
||||
weight: 100
|
||||
canonical: https://grafana.com/docs/grafana/latest/as-code/observability-as-code/grafana-cli/install-grafana-cli/
|
||||
aliases:
|
||||
- ../../../observability-as-code/grafana-cli/install-grafana-cli/ # /docs/grafana/next/observability-as-code/grafana-cli/install-grafana-cli/
|
||||
---
|
||||
|
||||
# Install Grafana CLI
|
||||
|
||||
You can install the project using one of the following supported methods:
|
||||
|
||||
## 1. Download a pre-built binary
|
||||
|
||||
Download the latest binary for your platform from the [Releases page](https://github.com/grafana/grafanactl/releases).
|
||||
|
||||
Prebuilt binaries are available for a variety of operating systems and architectures. Visit the latest release page, and scroll down to the Assets section.
|
||||
|
||||
To install the binary, follow the instructions below:
|
||||
|
||||
1. Download the archive for the desired operating system and architecture
|
||||
1. Extract the archive
|
||||
1. Move the executable to the desired directory
|
||||
1. Ensure this directory is included in the PATH environment variable
|
||||
1. Verify that you have execute permission on the file
|
||||
|
||||
## 2. Build from source
|
||||
|
||||
To build `grafanactl` from source you must:
|
||||
|
||||
- Have `git` installed
|
||||
- Have `go` v1.24 (or greater) installed
|
||||
|
||||
```bash
|
||||
go install github.com/grafana/grafanactl/cmd/grafanactl@latest
|
||||
```
|
||||
@@ -0,0 +1,122 @@
|
||||
---
|
||||
description: Configuration guide for Grafana CLI, a command line tool for managing Grafana resources as code.
|
||||
keywords:
|
||||
- configuration
|
||||
- Grafana CLI
|
||||
- CLI
|
||||
- command line
|
||||
- grafanactl
|
||||
labels:
|
||||
products:
|
||||
- cloud
|
||||
- enterprise
|
||||
- oss
|
||||
title: Set up Grafana CLI
|
||||
weight: 200
|
||||
canonical: https://grafana.com/docs/grafana/latest/as-code/observability-as-code/grafana-cli/set-up-grafana-cli/
|
||||
aliases:
|
||||
- ../../../observability-as-code/grafana-cli/set-up-grafana-cli/ # /docs/grafana/next/observability-as-code/grafana-cli/set-up-grafana-cli/
|
||||
---
|
||||
|
||||
# Set up Grafana CLI
|
||||
|
||||
You can configure Grafana CLI in two ways: using environment variables or through a configuration file.
|
||||
|
||||
- **Environment variables** are ideal for CI environments and support a single context. A full list of supported environment variables is available in the [reference documentation](https://github.com/grafana/grafanactl/blob/main/docs/reference/environment-variables/index.md#environment-variables-reference).
|
||||
- **Configuration files** can manage multiple contexts, making it easier to switch between different Grafana instances.
|
||||
|
||||
{{< admonition type="note" >}}
|
||||
Configuration items may change depending on your set-up. For example, use `org-id` for Grafana on-prem, but use `stack-id` for Grafana Cloud.
|
||||
{{< /admonition >}}
|
||||
|
||||
## Configure Grafana CLI with environment variables
|
||||
|
||||
Grafana CLI communicates with Grafana via its REST API, which requires authentication credentials.
|
||||
|
||||
At a minimum, set the URL of your Grafana instance and the organization ID:
|
||||
|
||||
```bash
|
||||
GRAFANA_SERVER='http://localhost:3000' GRAFANA_ORG_ID='1' grafanactl config check
|
||||
```
|
||||
|
||||
Depending on your authentication method, you may also need to set:
|
||||
|
||||
- A [token](https://github.com/grafana/grafanactl/blob/main/docs/reference/environment-variables/index.md#grafana_token) for a [Grafana service account](https://grafana.com/docs/grafana/latest/administration/service-accounts/) (recommended)
|
||||
- A [username](https://github.com/grafana/grafanactl/blob/main/docs/reference/environment-variables/index.md#grafana_user) and [password](https://github.com/grafana/grafanactl/blob/main/docs/reference/environment-variables/index.md#grafana_password) for basic authentication
|
||||
|
||||
To persist your configuration, consider [creating a context](#use-configuration-contexts).
|
||||
|
||||
### Use configuration contexts
|
||||
|
||||
Contexts allow you to easily switch between multiple Grafana instances.
|
||||
|
||||
By default, the CLI uses a context named `default`. To configure it use:
|
||||
|
||||
```bash
|
||||
grafanactl config set contexts.default.grafana.server http://localhost:3000
|
||||
grafanactl config set contexts.default.grafana.org-id 1
|
||||
|
||||
# Authenticate with a service account token
|
||||
grafanactl config set contexts.default.grafana.token service-account-token
|
||||
|
||||
# Or use basic authentication
|
||||
grafanactl config set contexts.default.grafana.user admin
|
||||
grafanactl config set contexts.default.grafana.password admin
|
||||
```
|
||||
|
||||
You can define additional contexts in the same way:
|
||||
|
||||
```bash
|
||||
grafanactl config set contexts.staging.grafana.server https://staging.grafana.example
|
||||
grafanactl config set contexts.staging.grafana.org-id 1
|
||||
```
|
||||
|
||||
{{< admonition type="note" >}}
|
||||
In these examples, `default` and `staging` are the names of the contexts.
|
||||
{{< /admonition >}}
|
||||
|
||||
## Configure Grafana CLI with configuration files
|
||||
|
||||
Grafana CLI stores its configuration in a YAML file. The CLI determines the configuration file location in the following order:
|
||||
|
||||
1. If the `--config` flag is provided, the specified file is used.
|
||||
2. If `$XDG_CONFIG_HOME` is set:
|
||||
`$XDG_CONFIG_HOME/grafanactl/config.yaml`
|
||||
3. If `$HOME` is set:
|
||||
`$HOME/.config/grafanactl/config.yaml`
|
||||
4. If `$XDG_CONFIG_DIRS` is set:
|
||||
`$XDG_CONFIG_DIRS/grafanactl/config.yaml`
|
||||
|
||||
{{< admonition type="note" >}}
|
||||
Use `grafanactl config check` to display the configuration file currently in use.
|
||||
{{< /admonition >}}
|
||||
|
||||
## Useful commands
|
||||
|
||||
Check the current configuration:
|
||||
|
||||
```bash
|
||||
grafanactl config check
|
||||
```
|
||||
|
||||
{{< admonition type="note" >}}
|
||||
This command is useful to troubleshoot your configuration.
|
||||
{{< /admonition >}}
|
||||
|
||||
List all available contexts:
|
||||
|
||||
```bash
|
||||
grafanactl config list-contexts
|
||||
```
|
||||
|
||||
Switch to a specific context:
|
||||
|
||||
```bash
|
||||
grafanactl config use-context staging
|
||||
```
|
||||
|
||||
View the full configuration:
|
||||
|
||||
```bash
|
||||
grafanactl config view
|
||||
```
|
||||
@@ -0,0 +1,67 @@
|
||||
---
|
||||
description: Learn about how to provision resources using Git Sync and local file provisioning administration.
|
||||
keywords:
|
||||
- observability
|
||||
- configuration
|
||||
- as code
|
||||
- git integration
|
||||
- git sync
|
||||
- github
|
||||
labels:
|
||||
products:
|
||||
- enterprise
|
||||
- oss
|
||||
title: Provision resources and sync dashboards
|
||||
menuTitle: Provision resources
|
||||
weight: 300
|
||||
canonical: https://grafana.com/docs/grafana/latest/as-code/observability-as-code/provision-resources/
|
||||
aliases:
|
||||
- ../../observability-as-code/provision-resources/ # /docs/grafana/next/observability-as-code/provision-resources/
|
||||
---
|
||||
|
||||
# Provision resources and sync dashboards
|
||||
|
||||
{{< admonition type="caution" >}}
|
||||
|
||||
Git Sync is available in [private preview](https://grafana.com/docs/release-life-cycle/) for Grafana Cloud. Support and documentation is available but might be limited to enablement, configuration, and some troubleshooting. No SLAs are provided. You can sign up to the private preview using the [Git Sync early access form](https://forms.gle/WKkR3EVMcbqsNnkD9).
|
||||
|
||||
Git Sync and local file provisioning are [experimental features](https://grafana.com/docs/release-life-cycle/) introduced in Grafana v12 for open source and Enterprise editions. Engineering and on-call support is not available. Documentation is either limited or not provided outside of code comments. No SLA is provided.
|
||||
|
||||
{{< /admonition >}}
|
||||
|
||||
Provisioning allows you to configure how to store your dashboard JSON and other files in GitHub repositories using either Git Sync or a local path.
|
||||
|
||||
Of the two options, **Git Sync** is the favorited method for provisioning your dashboards. You can synchronize any new dashboards and changes to existing dashboards from the UI to your configured GitHub repository. If you push a change in the repository, those changes are mirrored in your Grafana instance. Refer to [Git Sync workflow](#git-sync-workflow) for more information.
|
||||
|
||||
Alternatively, **local file provisioning** allows you to include in your Grafana instance resources (such as folders and dashboard JSON files) that are stored in a local file system. Refer to [Local file workflow](#local-file-workflow) for more information.
|
||||
|
||||
## Provisioned folders and connections
|
||||
|
||||
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. You can update any provisioned dashboard that is either stored within a GitHub repository (Git Sync workflow) or in a local file (local file workflow).
|
||||
|
||||
You can set a single folder, or multiple folders to a different repository, with up to 10 connections. Alternatively, your entire Grafana instance can be the provisioned folder.
|
||||
|
||||
## Git Sync workflow
|
||||
|
||||
In the Git Sync workflow:
|
||||
|
||||
- When you provision resources with Git Sync you can modify them from within the Grafana UI or within the GitHub repository. Changes made in either the repository or the Grafana UI are bidirectional.
|
||||
- Any changes made in the provisioned files stored in the GitHub repository are reflected in the Grafana database. By default, Grafana polls GitHub every 60 seconds. The Grafana UI reads from the database and updates the UI to reflect these changes.
|
||||
|
||||
For example, if you update a dashboard within the Grafana UI and click **Save** to preserve the changes, you'll be notified that the dashboard is provisioned in a GitHub repository. Next you'll be prompted to choose how to preserve the changes: either directly to a branch, or pushed to a new branch using a pull request in GitHub.
|
||||
|
||||
For more information, see [Introduction to Git Sync](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/observability-as-code/provision-resources/intro-git-sync) and [Set up Git Sync](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/observability-as-code/provision-resources/git-sync-setup).
|
||||
|
||||
## Local file workflow
|
||||
|
||||
In the local file workflow:
|
||||
|
||||
- All provisioned resources are changed in the local files.
|
||||
- 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.
|
||||
|
||||
Learn more in [Set up file provisioning](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/observability-as-code/provision-resources/file-path-setup/).
|
||||
|
||||
## Explore provisioning
|
||||
|
||||
{{< section withDescriptions="true" depth="5" >}}
|
||||
@@ -0,0 +1,170 @@
|
||||
---
|
||||
description: Instructions for setting up file provisioning with a local path.
|
||||
keywords:
|
||||
- as code
|
||||
- as-code
|
||||
- file provisioning
|
||||
- local path
|
||||
labels:
|
||||
products:
|
||||
- enterprise
|
||||
- oss
|
||||
title: Set up file provisioning
|
||||
weight: 200
|
||||
canonical: https://grafana.com/docs/grafana/latest/as-code/observability-as-code/provision-resources/file-path-setup/
|
||||
aliases:
|
||||
- ../../../observability-as-code/provision-resources/file-path-setup/ # /docs/grafana/next/observability-as-code/provision-resources/file-path-setup/
|
||||
---
|
||||
|
||||
# Set up file provisioning
|
||||
|
||||
{{< admonition type="caution" >}}
|
||||
|
||||
Local file provisioning is an [experimental feature](https://grafana.com/docs/release-life-cycle/) introduced in Grafana v12 for open source and Enterprise editions, but 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.
|
||||
|
||||
{{< /admonition >}}
|
||||
|
||||
Use local file provisioning to include in your Grafana instance resources (such as folders and dashboard JSON files) that are stored in a local file system.
|
||||
|
||||
This page explains how to set up local file provisioning.
|
||||
|
||||
The local path mount is referred to as a repository.
|
||||
|
||||
Using the local path lets you also use it with a tool like `fuse`, allowing you to mount S3 buckets as local paths. You can also use tools like `restic` to automatically back up your dashboards to your preferred backup storage solution.
|
||||
|
||||
To set up file sync with local with local files, you need to:
|
||||
|
||||
1. Enable feature toggles and paths in Grafana configuration file (first time set up).
|
||||
1. Set the local path.
|
||||
1. Choose what content to sync with Grafana.
|
||||
|
||||
## New file provisioning capabilities
|
||||
|
||||
Local file provisioning using **Administration** > **Provisioning** will eventually replace the traditional methods Grafana has used for referencing local file systems for dashboard files.
|
||||
|
||||
{{< admonition type="note" >}}
|
||||
For production systems, use the `folderFromFilesStructure` capability instead of **Administration** > **Provisioning** to include dashboards from a local file system in your Grafana instance. Refer to [Provision Grafana](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/administration/provisioning/#provision-folders-structure-from-filesystem-to-grafana) for more information.
|
||||
{{< /admonition >}}
|
||||
|
||||
### Limitations
|
||||
|
||||
- A provisioned dashboard can't be deleted from within Grafana UI. The dashboard has to be deleted at the local file system and those changes synced to Grafana.
|
||||
- Changes from the local file system are one way: you can't save changes from the Grafana UI to GitHub.
|
||||
|
||||
## Before you begin
|
||||
|
||||
{{< admonition type="note" >}}
|
||||
Enable the `provisioning` and `kubernetesDashboards` feature toggles in Grafana to use this feature.
|
||||
{{< /admonition >}}
|
||||
|
||||
To set up file provisioning, you need:
|
||||
|
||||
- Administration rights in your Grafana organization.
|
||||
- A local directory where your dashboards will be stored.
|
||||
- If you want to use a GitHub repository, refer to [Set up Git Sync](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/observability-as-code/provision-resources/file-path-setup/).
|
||||
- To update the `permitted_provisioning_paths` section of `custom.ini`.
|
||||
- To enable the required feature toggles in your Grafana instance.
|
||||
|
||||
## Enable required feature toggles and configure permitted paths
|
||||
|
||||
To activate local file provisioning in Grafana, you need to enable the `provisioning` and `kubernetesDashboards` feature toggles.
|
||||
For additional information about feature toggles, refer to [Configure feature toggles](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/setup-grafana/configure-grafana/feature-toggles).
|
||||
|
||||
The local setting must be a relative path and its relative path must be configured in the `permitted_provisioned_paths` configuration option.
|
||||
The configuration option is relative to your working directory, i.e. where you are running Grafana from; this is usually `/usr/share/grafana` or similar.
|
||||
|
||||
Local file paths can point to any directory that is permitted by the configuration.
|
||||
The default paths is `devenv/dev-dashboards` and `conf/provisioning` in your `grafana` installation directory.
|
||||
|
||||
The path must behave as a standard file directory on the system of choice.
|
||||
Any subdirectories are automatically included.
|
||||
|
||||
The values that you enter for the `permitted_provisioning_paths` become the base paths for those entered when you enter a local path in the **Connect to local storage** wizard.
|
||||
|
||||
1. Open your Grafana configuration file, either `grafana.ini` or `custom.ini`. For file location based on operating system, refer to [Configuration file location](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/setup-grafana/configure-grafana/feature-toggles/#experimental-feature-toggles).
|
||||
1. Locate or add a `[feature_toggles]` section. Add these values:
|
||||
|
||||
```ini
|
||||
[feature_toggles]
|
||||
provisioning = true
|
||||
kubernetesDashboards = true ; use k8s from browser
|
||||
```
|
||||
|
||||
1. Locate or add a `[paths]` section. To add more than one location, use the pipe character (`|`) to separate the paths. The list should not include empty paths or trailing pipes. Add these values:
|
||||
|
||||
```ini
|
||||
[paths]
|
||||
; This is devenv/dev-dashboards and conf/provisioning by default.
|
||||
permitted_provisioning_paths = grafana/ | /etc/grafana/provisioning/
|
||||
```
|
||||
|
||||
1. Save the changes to the file and start Grafana.
|
||||
|
||||
## Set up file-based provisioning
|
||||
|
||||
To use file-based provisioning, you need the file path to the `grafana` folder where your dashboards are stored in the repository.
|
||||
|
||||
To start setting up file-based provisioning:
|
||||
|
||||
1. Log in to your Grafana server with an account that has the Grafana Admin flag set.
|
||||
1. Select **Administration** in the left-side menu and then **Provisioning**.
|
||||
1. Select [Configure file provisioning](#set-up-file-based-provisioning).
|
||||
|
||||
### Connect to local storage
|
||||
|
||||
The local path can point to any directory that is permitted by the configuration.
|
||||
Refer to [Enabled required feature toggles and paths](#enable-required-feature-toggles-and-configure-permitted-paths) for information.
|
||||
|
||||
The starting path is always your working `grafana` directory.
|
||||
The prefix that must be entered is determined by the locations configured in `permitted_provisioning_paths`.
|
||||
The default paths are `devenv/dev-dashboards` and `conf/provisioning` in your `grafana` installation directory.
|
||||
The value you enter in the Grafana UI must _begin_ with any of the configured values. For example, `conf/provisioning/test` is valid, but `conf/test` is not.
|
||||
|
||||
1. Enter the **Local path**, for example `grafana/`. This must begin with any of the configured `permitted_provisioned_paths`.
|
||||
1. Select **Choose what to synchronize**.
|
||||
|
||||
The set up process verifies the path and provides an error message if a problem occurs.
|
||||
|
||||
### Choose what to synchronize
|
||||
|
||||
#### Synchronization limitations
|
||||
|
||||
Full instance sync is not available in Grafana Cloud.
|
||||
|
||||
In Grafana OSS/Enterprise:
|
||||
|
||||
- If you try to perform a full instance sync with resources that contain alerts or panels, the connection will be blocked.
|
||||
- You won't be able to create new alerts or library panels after setup is completed.
|
||||
- If you opted for full instance sync and want to use alerts and library panels, you'll have to delete the provisioned repository and connect again with folder sync.
|
||||
|
||||
#### Set up synchronization
|
||||
|
||||
Choose to either sync your entire organization resources with external storage, or to sync certain resources to a new Grafana folder (with up to 10 connections).
|
||||
|
||||
- Choose **Sync all resources with external storage** if you want to sync and manage your entire Grafana instance through external storage. With this option, all of your dashboards are synced to that one repository. You can only have one provisioned connection with this selection, and you won't have the option of setting up additional repositories to connect to.
|
||||
|
||||
- Choose **Sync external storage to new Grafana folder** to sync external resources into a new folder without affecting the rest of your instance. You can repeat this process for up to 10 connections.
|
||||
|
||||
Next, enter a **Display name** for the repository connection. Resources stored in this connection appear under the chosen display name in the Grafana UI.
|
||||
|
||||
Click **Synchronize** to continue.
|
||||
|
||||
### Synchronize with external storage
|
||||
|
||||
After this one time step, all future updates are automatically saved to the local file path and provisioned back to the instance.
|
||||
|
||||
During the initial synchronization, your dashboards will be temporarily unavailable. No data or configurations will be lost.
|
||||
How long the process takes depends upon the number of resources involved.
|
||||
|
||||
Select **Begin synchronization** to start the process.
|
||||
|
||||
### Choose additional settings
|
||||
|
||||
If you wish, you can make any files synchronized as as **Read only** so no changes can be made to the resources through Grafana.
|
||||
Any resources made outside of Grafana and saved to the local repository will be reflected in Grafana.
|
||||
|
||||
Select **Finish**.
|
||||
|
||||
## Verify your dashboards in Grafana
|
||||
|
||||
To verify that your dashboards are available at the location that you specified, click **Dashboards**. The name of the dashboard is listed in the **Name** column.
|
||||
@@ -0,0 +1,227 @@
|
||||
---
|
||||
description: Instructions for setting up Git Sync, so you can provision GitHub repositories for use with Grafana.
|
||||
keywords:
|
||||
- set up
|
||||
- git integration
|
||||
- git sync
|
||||
- github
|
||||
labels:
|
||||
products:
|
||||
- enterprise
|
||||
- oss
|
||||
title: Set up Git Sync
|
||||
weight: 100
|
||||
canonical: https://grafana.com/docs/grafana/latest/as-code/observability-as-code/provision-resources/git-sync-setup/
|
||||
aliases:
|
||||
- ../../../observability-as-code/provision-resources/git-sync-setup/ # /docs/grafana/next/observability-as-code/provision-resources/git-sync-setup/
|
||||
---
|
||||
|
||||
# Set up Git Sync
|
||||
|
||||
{{< admonition type="caution" >}}
|
||||
|
||||
Git Sync is available in [private preview](https://grafana.com/docs/release-life-cycle/) for Grafana Cloud, and is an [experimental feature](https://grafana.com/docs/release-life-cycle/) in Grafana v12 for open source and Enterprise editions.
|
||||
|
||||
Support and documentation is available but might be limited to enablement, configuration, and some troubleshooting. No SLAs are provided.
|
||||
|
||||
You can sign up to the private preview using the [Git Sync early access form](https://forms.gle/WKkR3EVMcbqsNnkD9).
|
||||
|
||||
{{< /admonition >}}
|
||||
|
||||
Git Sync lets you manage Grafana dashboards as code by storing dashboard JSON files and folders in a remote GitHub repository.
|
||||
|
||||
To set up Git Sync and synchronize with a GitHub repository follow these steps:
|
||||
|
||||
1. [Enable feature toggles in Grafana](#enable-required-feature-toggles) (first time set up).
|
||||
1. [Create a GitHub access token](#create-a-github-access-token).
|
||||
1. [Configure a connection to your GitHub repository](#set-up-the-connection-to-github).
|
||||
1. [Choose what content to sync with Grafana](#choose-what-to-synchronize).
|
||||
|
||||
Optionally, you can [extend Git Sync](#configure-webhooks-and-image-rendering) by enabling pull request notifications and image previews of dashboard changes.
|
||||
|
||||
| Capability | Benefit | Requires |
|
||||
| ----------------------------------------------------- | ------------------------------------------------------------------------------- | -------------------------------------- |
|
||||
| Adds a table summarizing changes to your pull request | Provides a convenient way to save changes back to GitHub. | Webhooks configured |
|
||||
| Add a dashboard preview image to a PR | View a snapshot of dashboard changes to a pull request without opening Grafana. | Image renderer and webhooks configured |
|
||||
|
||||
{{< admonition type="note" >}}
|
||||
|
||||
Alternatively, you can configure a local file system instead of using GitHub. Refer to [Set up file provisioning](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/observability-as-code/provision-resources/file-path-setup/) for more information.
|
||||
|
||||
{{< /admonition >}}
|
||||
|
||||
## Performance impacts of enabling Git Sync
|
||||
|
||||
Git Sync is an experimental feature and is under continuous development. Reporting any issues you encounter can help us improve Git Sync.
|
||||
|
||||
When Git Sync is enabled, the database load might increase, especially for instances with a lot of folders and nested folders. Evaluate the performance impact, if any, in a non-production environment.
|
||||
|
||||
## Before you begin
|
||||
|
||||
{{< admonition type="caution" >}}
|
||||
|
||||
Refer to [Known limitations](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/observability-as-code/provision-resources/intro-git-sync#known-limitations/) before using Git Sync.
|
||||
|
||||
{{< /admonition >}}
|
||||
|
||||
### Requirements
|
||||
|
||||
To set up Git Sync, you need:
|
||||
|
||||
- Administration rights in your Grafana organization.
|
||||
- Enable the required feature toggles in your Grafana instance. Refer to [Enable required feature toggles](#enable-required-feature-toggles) for instructions.
|
||||
- A GitHub repository to store your dashboards in.
|
||||
- If you want to use a local file path, refer to [the local file path guide](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/observability-as-code/provision-resources/file-path-setup/).
|
||||
- A GitHub access token. The Grafana UI will prompt you during setup.
|
||||
- Optional: A public Grafana instance.
|
||||
- Optional: The [Image Renderer service](https://github.com/grafana/grafana-image-renderer) to save image previews with your PRs.
|
||||
|
||||
## Enable required feature toggles
|
||||
|
||||
To activate Git Sync in Grafana, you need to enable the `provisioning` and `kubernetesDashboards` feature toggles.
|
||||
For additional information about feature toggles, refer to [Configure feature toggles](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/setup-grafana/configure-grafana/feature-toggles).
|
||||
|
||||
To enable the required feature toggles, add them to your Grafana configuration file:
|
||||
|
||||
1. Open your Grafana configuration file, either `grafana.ini` or `custom.ini`. For file location based on operating system, refer to [Configuration file location](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/setup-grafana/configure-grafana/feature-toggles/#experimental-feature-toggles).
|
||||
1. Locate or add a `[feature_toggles]` section. Add these values:
|
||||
|
||||
```ini
|
||||
[feature_toggles]
|
||||
provisioning = true
|
||||
kubernetesDashboards = true ; use k8s from browser
|
||||
```
|
||||
|
||||
1. Save the changes to the file and restart Grafana.
|
||||
|
||||
## Create a GitHub access token
|
||||
|
||||
Whenever you connect to a GitHub repository, you need to create a GitHub access token with specific repository permissions.
|
||||
This token needs to be added to your Git Sync configuration to enable read and write permissions between Grafana and GitHub repository.
|
||||
|
||||
1. Create a new token using [Create new fine-grained personal access token](https://github.com/settings/personal-access-tokens/new). Refer to [Managing your personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens) for instructions.
|
||||
1. Under **Permissions**, expand **Repository permissions**.
|
||||
1. Set these permissions for Git Sync:
|
||||
- **Contents**: Read and write permission
|
||||
- **Metadata**: Read-only permission
|
||||
- **Pull requests**: Read and write permission
|
||||
- **Webhooks**: Read and write permission
|
||||
|
||||
1. Select any additional options and then press **Generate token**.
|
||||
1. Verify the options and select **Generate token**.
|
||||
1. Copy the access token. Leave the browser window available with the token until you've completed configuration.
|
||||
|
||||
GitHub Apps are not currently supported.
|
||||
|
||||
## Set up the connection to GitHub
|
||||
|
||||
Use **Provisioning** to guide you through setting up Git Sync to use a GitHub repository.
|
||||
|
||||
1. Log in to your Grafana server with an account that has the Grafana Admin flag set.
|
||||
1. Select **Administration** in the left-side menu and then **Provisioning**.
|
||||
1. Select **Configure Git Sync**.
|
||||
|
||||
### Connect to external storage
|
||||
|
||||
To connect your GitHub repository, follow these steps:
|
||||
|
||||
1. Paste your GitHub personal access token into **Enter your access token**. Refer to [Create a GitHub access token](#create-a-github-access-token) for instructions.
|
||||
1. Paste the **Repository URL** for your GitHub repository into the text box.
|
||||
1. Enter a branch to use. The default value is `main`.
|
||||
1. Add a **Path** to a subdirectory where your dashboards are stored. The default value is `grafana/`. If your dashboards are stored in the root of your repository, then remove the directory name.
|
||||
1. Select **Choose what to synchronize** to have the connection to your repository verified and continue setup.
|
||||
|
||||
### Choose what to synchronize
|
||||
|
||||
In this step you can decide which elements to synchronize. Keep in mind the available options depend on the status of your Grafana instance.
|
||||
|
||||
- If the instance contains resources in an incompatible data format, you'll have to migrate all the data using instance sync. Folder sync won't be supported.
|
||||
- If there is already another connection using folder sync, instance sync won't be offered.
|
||||
|
||||
#### Synchronization limitations
|
||||
|
||||
Git Sync only supports dashboards and folders. Alerts, panels, and other resources are not supported yet.
|
||||
|
||||
{{< admonition type="caution" >}}
|
||||
|
||||
Refer to [Known limitations](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/observability-as-code/provision-resources/intro-git-sync#known-limitations/) before using Git Sync. Refer to [Supported resources](/docs/grafana/<GRAFANA_VERSION>/observability-as-code/provision-resources/intro-git-sync#supported-resources) for details about which resources you can sync.
|
||||
|
||||
{{< /admonition >}}
|
||||
|
||||
Full instance sync is not available in Grafana Cloud.
|
||||
|
||||
In Grafana OSS/Enterprise:
|
||||
|
||||
- If you try to perform a full instance sync with resources that contain alerts or panels, Git Sync will block the connection.
|
||||
- You won't be able to create new alerts or library panels after the setup is completed.
|
||||
- If you opted for full instance sync and want to use alerts and library panels, you'll have to delete the synced repository and connect again with folder sync.
|
||||
|
||||
#### Set up synchronization
|
||||
|
||||
To set up synchronization, choose to either sync your entire organization resources with external storage, or to sync certain resources to a new Grafana folder (with up to 10 connections).
|
||||
|
||||
- Choose **Sync all resources with external storage** if you want to sync and manage your entire Grafana instance through external storage. With this option, all of your dashboards are synced to that one repository. You can only have one provisioned connection with this selection, and you won't have the option of setting up additional repositories to connect to.
|
||||
- Choose **Sync external storage to new Grafana folder** to sync external resources into a new folder without affecting the rest of your instance. You can repeat this process for up to 10 connections.
|
||||
|
||||
Next, enter a **Display name** for the repository connection. Resources stored in this connection appear under the chosen display name in the Grafana UI. Click **Synchronize** to continue.
|
||||
|
||||
### Choose additional settings
|
||||
|
||||
Finally, you can set up how often your configured storage is polled for updates.
|
||||
|
||||
1. For **Update instance interval (seconds)**, enter how often you want the instance to pull updates from GitHub. The default value is 60 seconds.
|
||||
1. Optional: Select **Read only** to ensure resources can't be modified in Grafana.
|
||||
1. Optional: If you have the Grafana Image Renderer plugin configured, you can **Enable dashboards previews in pull requests**. If image rendering is not available, then you can't select this option. For more information, refer to the [Image Renderer service](https://github.com/grafana/grafana-image-renderer).
|
||||
1. Select **Finish** to proceed.
|
||||
|
||||
## Verify your dashboards in Grafana
|
||||
|
||||
To verify that your dashboards are available at the location that you specified, click **Dashboards**. The name of the dashboard is listed in the **Name** column.
|
||||
|
||||
Now that your dashboards have been synced from a repository, you can customize the name, change the branch, and create a pull request (PR) for it. Refer to [Manage provisioned repositories with Git Sync](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/observability-as-code/provision-resources/use-git-sync/) for more information.
|
||||
|
||||
## Configure webhooks and image rendering
|
||||
|
||||
You can extend Git Sync by getting instant updates and pull requests using webhooks and add dashboard previews in pull requests.
|
||||
|
||||
### Set up webhooks for realtime notification and pull request integration
|
||||
|
||||
When connecting to a GitHub repository, Git Sync uses webhooks to enable real-time updates from GitHub public repositories or enable pull request integrations. Without webhooks, the polling interval is set in the final configuration screen, and the default is 60 seconds. If you use local storage, then Git Sync only provides periodic pulling.
|
||||
|
||||
You can set up webhooks with whichever service or tooling you prefer. You can use Cloudflare Tunnels with a Cloudflare-managed domain, port-forwarding and DNS options, or a tool such as `ngrok`.
|
||||
|
||||
To set up webhooks you need to expose your Grafana instance to the public Internet. You can do this via port forwarding and DNS, a tool such as `ngrok`, or any other method you prefer. The permissions set in your GitHub access token provide the authorization for this communication.
|
||||
|
||||
After you have the public URL, you can add it to your Grafana configuration file:
|
||||
|
||||
```yaml
|
||||
[server]
|
||||
root_url = https://PUBLIC_DOMAIN.HERE
|
||||
```
|
||||
|
||||
To check the configured webhooks, go to **Administration** > **Provisioning** and click the **View** link for your GitHub repository.
|
||||
|
||||
#### Expose necessary paths only
|
||||
|
||||
If your security setup does not permit publicly exposing the Grafana instance, you can either choose to `allowlist` the GitHub IP addresses, or expose only the necessary paths.
|
||||
|
||||
The necessary paths required to be exposed are, in RegExp:
|
||||
|
||||
- `/apis/provisioning\.grafana\.app/v0(alpha1)?/namespaces/[^/]+/repositories/[^/]+/(webhook|render/.*)$`
|
||||
<!-- TODO: Path for the blob storage for image rendering? @ryantxu would know this best. -->
|
||||
|
||||
### Set up image rendering for dashboard previews
|
||||
|
||||
Set up image rendering to add visual previews of dashboard updates directly in pull requests. Image rendering also requires webhooks.
|
||||
|
||||
To enable this capability, install the Grafana Image Renderer in your Grafana instance. For more information and installation instructions, refer to the [Image Renderer service](https://github.com/grafana/grafana-image-renderer).
|
||||
|
||||
## Modify configurations after set up is complete
|
||||
|
||||
To update your repository configuration after you've completed set up:
|
||||
|
||||
1. Log in to your Grafana server with an account that has the Grafana Admin flag set.
|
||||
1. Select **Administration** in the left-side menu and then **Provisioning**.
|
||||
1. Select **Settings** for the repository you wish to modify.
|
||||
1. Use the **Configure repository** screen to update any of the settings.
|
||||
1. Select **Save** to preserve the updates.
|
||||
@@ -0,0 +1,167 @@
|
||||
---
|
||||
description: Learn about Git Sync, the Grafana feature for storing and managing dashboards within GitHub repositories.
|
||||
keywords:
|
||||
- dashboards
|
||||
- git integration
|
||||
- git sync
|
||||
- github
|
||||
labels:
|
||||
products:
|
||||
- enterprise
|
||||
- oss
|
||||
- cloud
|
||||
refs:
|
||||
roles-and-permissions:
|
||||
- pattern: /docs/grafana/
|
||||
destination: /docs/grafana/<GRAFANA_VERSION>/administration/roles-and-permissions/
|
||||
- pattern: /docs/grafana-cloud/
|
||||
destination: /docs/grafana-cloud/account-management/authentication-and-permissions/cloud-roles/
|
||||
title: Git Sync
|
||||
weight: 100
|
||||
canonical: https://grafana.com/docs/grafana/latest/as-code/observability-as-code/provision-resources/intro-git-sync/
|
||||
aliases:
|
||||
- ../../../observability-as-code/provision-resources/intro-git-sync/ # /docs/grafana/next/observability-as-code/provision-resources/intro-git-sync/
|
||||
---
|
||||
|
||||
# Introduction to Git Sync
|
||||
|
||||
{{< admonition type="caution" >}}
|
||||
|
||||
Git Sync is available in [private preview](https://grafana.com/docs/release-life-cycle/) for Grafana Cloud, and is an [experimental feature](https://grafana.com/docs/release-life-cycle/) in Grafana v12 for open source and Enterprise editions.
|
||||
|
||||
Support and documentation is available but might be limited to enablement, configuration, and some troubleshooting. No SLAs are provided.
|
||||
|
||||
You can sign up to the private preview using the [Git Sync early access form](https://forms.gle/WKkR3EVMcbqsNnkD9).
|
||||
|
||||
{{< /admonition >}}
|
||||
|
||||
Git Sync in Grafana lets you manage your dashboards as code as JSON files stored in GitHub. You and your team can version control, collaborate, and automate deployments efficiently.
|
||||
|
||||
Using Git Sync, you can:
|
||||
|
||||
- Manage dashboard configuration outside of Grafana instances using Git
|
||||
- Introduce a review process for creating and modifying dashboards
|
||||
- Replicate dashboards across multiple instances
|
||||
|
||||
## How it works
|
||||
|
||||
{{< admonition type="caution" >}}
|
||||
|
||||
Git Sync only works with specific folders for the moment. Full-instance sync is not currently supported.
|
||||
|
||||
{{< /admonition >}}
|
||||
|
||||
Git Sync is bidirectional and works both with changes done directly in GitHub as well as in the Grafana UI.
|
||||
|
||||
### Provisioning folder
|
||||
|
||||
Git Sync creates a folder for all the synchronized resources to live under. You can continue to have unprovisioned resources outside that folder.
|
||||
|
||||
### Make changes in Grafana
|
||||
|
||||
Whenever you modify a dashboard directly from the UI, Grafana can commit changes to Git upon saving. You can configure settings to either enforce PR approvals before merging in your repository, or allow direct commits.
|
||||
|
||||
Grafana periodically polls GitHub at a regular internal to synchronize any changes. The default polling interval is 60 seconds, and you can change this setting in the Grafana UI.
|
||||
|
||||
- If you enable the [webhooks feature](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/observability-as-code/provision-resources/git-sync-setup/#configure-webhooks-and-image-rendering), repository notifications appear almost immediately.
|
||||
- Without webhooks, Grafana polls for changes at the specified interval.
|
||||
|
||||
### Make changes in your GitHub repositories
|
||||
|
||||
With Git Sync, you can make changes to the files in the provisioned folder in GitHub and see them in Grafana. Automated workflows ensure those changes are automatically represented in the Grafana database by updating Git. The Grafana UI reads the database and updates the UI to reflect these changes.
|
||||
|
||||
## Known limitations
|
||||
|
||||
{{< admonition type="caution" >}}
|
||||
|
||||
Refer to [Requirements](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/observability-as-code/provision-resources/git-sync-setup#requirements/) to learn what you need to use Git Sync.
|
||||
|
||||
{{< /admonition >}}
|
||||
|
||||
**Git Sync is under development and the following limitations apply.**
|
||||
|
||||
**Synced resources**
|
||||
|
||||
- You can only sync dashboards and folders. Refer to [Supported resources](#supported-resources) for more information.
|
||||
- If you're using Git Sync in Grafana OSS and Grafana Enterprise, some resources might be in an incompatible data format and won't be synced.
|
||||
- Full-instance sync is not available in Grafana Cloud and has limitations in Grafana OSS and Grafana Enterprise. Refer to [Choose what to synchronize](../git-sync-setup/#choose-what-to-synchronize) for more details.
|
||||
- When migrating to full instance sync, during the synchronization process your resources will be temporarily unavailable. No one will be able to create, edit, or delete resources during this process.
|
||||
- If you want to manage existing resources with Git Sync, you need to save them as JSON files and commit them to the synced repository. Open a PR to import, copy, move, or save a dashboard.
|
||||
- Restoring resources from the UI is currently not possible. As an alternative, you can restore dashboards directly in your GitHub repository by raising a PR, and they will be updated in Grafana.
|
||||
|
||||
**Authentication**
|
||||
|
||||
- You can only authenticate in GitHub using your Personal Access Token token.
|
||||
|
||||
**Permission management**
|
||||
|
||||
- You cannot modify the permissions of a provisioned folder after you've synced it.
|
||||
- Default permissions are: Admin = Admin, Editor = Editor, and Viewer = Viewer. Refer to [Roles and permissions](ref:roles-and-permissions) for more information.
|
||||
|
||||
**Compatibility**
|
||||
|
||||
- Support for native Git, Git app, and other providers, such as GitLab or Bitbucket, is on the roadmap.
|
||||
|
||||
## Supported resources
|
||||
|
||||
Git Sync only supports dashboards and folders. Alerts, panels, and other resources are not supported yet.
|
||||
|
||||
If you're using Git Sync in Grafana OSS or Grafana Enterprise, some supported resources might be in an incompatible data format. If this happens, syncing will be blocked. Compatibility issues will be fixed with an upcoming migration tool.
|
||||
|
||||
### Resource states
|
||||
|
||||
A resource can be:
|
||||
|
||||
| Is the resource? | **Compatible** | **Incompatible** |
|
||||
| ---------------- | -------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
|
||||
| **Supported** | The resource can be managed with Git Sync. | The resource is supported but has compatibility issues. It **cannot** be managed with Git Sync. |
|
||||
| **Unsupported** | The resource is **not** supported and **cannot** be managed with Git Sync. | Not applicable. |
|
||||
|
||||
### Git Sync instance states
|
||||
|
||||
An instance can be in one of the following Git Sync states:
|
||||
|
||||
- **Unprovisioned**: None of the instance's resources are being managed by Git Sync.
|
||||
- **Partially provisioned**: Some of the resources are controlled by Git Sync.
|
||||
- **Fully provisioned**: All supported resource types are managed by Git Sync. Note that unsupported resources are not managed.
|
||||
|
||||
## Common use cases
|
||||
|
||||
You can use Git Sync in the following scenarios.
|
||||
|
||||
### 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.
|
||||
|
||||
## Provision 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](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/observability-as-code/foundation-sdk) documentation.
|
||||
+138
@@ -0,0 +1,138 @@
|
||||
---
|
||||
description: Update, save, and modify provisioned resources in Grafana using Git Sync.
|
||||
keywords:
|
||||
- dashboards
|
||||
- provisioned files
|
||||
- git sync
|
||||
- github
|
||||
labels:
|
||||
products:
|
||||
- enterprise
|
||||
- oss
|
||||
title: Work with provisioned dashboards
|
||||
weight: 300
|
||||
canonical: https://grafana.com/docs/grafana/latest/as-code/observability-as-code/provision-resources/provisioned-dashboards/
|
||||
aliases:
|
||||
- ../../../observability-as-code/provision-resources/provisioned-dashboards/ # /docs/grafana/next/observability-as-code/provision-resources/provisioned-dashboards/
|
||||
---
|
||||
|
||||
# Work with provisioned dashboards
|
||||
|
||||
{{< admonition type="caution" >}}
|
||||
|
||||
Git Sync is available in [private preview](https://grafana.com/docs/release-life-cycle/) for Grafana Cloud. Support and documentation is available but might be limited to enablement, configuration, and some troubleshooting. No SLAs are provided. You can sign up to the private preview using the [Git Sync early access form](https://forms.gle/WKkR3EVMcbqsNnkD9).
|
||||
|
||||
Git Sync and local file provisioning are [experimental features](https://grafana.com/docs/release-life-cycle/) introduced in Grafana v12 for open source and Enterprise editions. Engineering and on-call support is not available. Documentation is either limited or not provided outside of code comments. No SLA is provided.
|
||||
|
||||
{{< /admonition >}}
|
||||
|
||||
Using Provisioning, you can choose to store your dashboard JSON files in either GitHub repositories using Git Sync or a local file path.
|
||||
|
||||
For more information, refer to the [Dashboards](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/dashboards/) documentation.
|
||||
|
||||
## Provisioning methods
|
||||
|
||||
Dashboards and folders synchronized using Git Sync or a local file path are referred to as "provisioned" resources.
|
||||
|
||||
### Git Sync provisioning
|
||||
|
||||
Of the two experimental options, **Git Sync** is the recommended method for provisioning your dashboards.
|
||||
You can synchronize any new dashboards and changes to existing dashboards to your configured GitHub repository.
|
||||
If you push a change in the repository, those changes are mirrored in your Grafana instance.
|
||||
|
||||
For more information on configuring Git Sync, refer to [Introduction to Git Sync](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/observability-as-code/provision-resources/intro-git-sync/).
|
||||
|
||||
### Local path provisioning
|
||||
|
||||
Local path provisioning makes files from a specified path available within Grafana, and any changes made in the configured local path are updated in Grafana. Note that these provisioned resources can only be modified in the local files and not within Grafana.
|
||||
|
||||
Refer to [Set up file provisioning](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/observability-as-code/provision-resources/file-path-setup) to learn more about the version of local file provisioning in Grafana 12.
|
||||
|
||||
{{< admonition type="note" >}}
|
||||
The experimental local path provisioning using **Administration** > **Provisioning** will replace the file provisioning methods Grafana uses for referencing local file.
|
||||
|
||||
For production systems, use the established methods for provisioning file systems in Grafana.
|
||||
Refer to [Provision Grafana](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/administration/provisioning/#provision-folders-structure-from-filesystem-to-grafana) for more information.
|
||||
{{< /admonition >}}
|
||||
|
||||
## Manage dashboards provisioned with Git Sync
|
||||
|
||||
Using Git Sync, you can manage your dashboards in the UI and synchronize them with a GitHub repository.
|
||||
|
||||
Git Sync changes the behavior in Grafana for dashboards that are saved in Git Sync:
|
||||
|
||||
- Dashboards saved in your repository or local folder configured with Git Sync appear in a provisioned folder in Grafana.
|
||||
- Any dashboard folders saved with Git Sync have a **Provisioned** label in the UI.
|
||||
- Any changes to a provisioned resources have to be saved to the repository by opening a pull request or committing directly to the `main` branch.
|
||||
|
||||
You can set a single folder, or multiple folders to a different repository, with up to 10 connections.
|
||||
|
||||
### Git workflow with dashboards
|
||||
|
||||
By default, Git version control uses a branch-based workflow for changes. This means that you can:
|
||||
|
||||
- Commit changes to an existing branch (such as `main`) or save them to a new branch in your GitHub repository.
|
||||
- Use pull requests to review changes to dashboards.
|
||||
- Preview the changes before merging.
|
||||
|
||||
To learn more about Git, refer to [Getting Started - About Version Control](https://git-scm.com/book/en/v2/Getting-Started-About-Version-Control) of the [Pro Git book](https://git-scm.com/book/en/v2) in the official Git documentation.
|
||||
|
||||
### Add and save a new dashboard
|
||||
|
||||
When you create a new dashboard in a provisioned folder associated with a GitHub repository, you follow the same process you use for any new dashboard.
|
||||
Refer to [Create a dashboard](http://grafana.com/docs/grafana/<GRAFANA_VERSION>/dashboards/build-dashboards/create-dashboard/) for more information.
|
||||
|
||||
After you create the dashboard, the steps are similar to [Save dashboard changes to GitHub](#save-dashboard-changes-to-github).
|
||||
|
||||
1. Select **Save** to preserve the new dashboard.
|
||||
1. Enter a title for the dashboard and a description.
|
||||
1. Select the provisioned folder from the **Folder** drop-down list.
|
||||
1. In **Path**, provide the path for your repository, ending in a JSON or YAML file.
|
||||
1. For **Workflow**, select **Push to main** to make a Git commit directly to the repository or **Push to a new branch** to create a pull request.
|
||||
- **Branch**: Specify the branch name in GitHub (for example, main). This option only appears if you select **Push to a new branch**.
|
||||
1. Select **Save**.
|
||||
|
||||
### Save dashboard changes to GitHub
|
||||
|
||||
When you edit a provisioned resource, you are prompted to save or discard those changes.
|
||||
Saving changes requires opening a pull request in your GitHub repository.
|
||||
|
||||
1. Select **Edit** to update a provisioned dashboard. Make your desired changes.
|
||||
|
||||
1. Click **Save dashboard**.
|
||||
|
||||
1. On the **Provisioned dashboard** panel, choose the options you want to use:
|
||||
- **Update default refresh value**: Check this box to make the current refresh the new default.
|
||||
- **Update default variable values**: Check this box to make the current values the new default.
|
||||
- **Path**: Provide the path for your repository, ending in a JSON or YAML file.
|
||||
- **Workflow:** Select **Push to main** to make a Git commit directly to the repository or **Push to a new branch** to create a pull request.
|
||||
- **Branch**: Specify the branch name in GitHub (for example, main). This option only appears if you select **Push to a new branch**.
|
||||
- **Comment**: Add a comment describing your changes.
|
||||
|
||||
1. Optional: Select the **Changes** tab to view the differences between the updates you made and the original resource.
|
||||
|
||||
1. Select **Save**.
|
||||
|
||||
1. If you chose **Push to a new branch**, select **Open a pull request in GitHub** to open a new PR to your repository. GitHub opens with your dashboard’s code as the contents of the PR.
|
||||
|
||||
1. Follow your usual GitHub workflow to save and merge the PR to your repository.
|
||||
|
||||
### Remove dashboards
|
||||
|
||||
You can remove a provisioned dashboard by deleting the dashboard from the repository. The Grafana UI updates when the changes from the GitHub repository sync.
|
||||
|
||||
To restore a deleted dashboard, raise a PR directly in your GitHub repository. Restoring resources from the UI is currently not possible.
|
||||
|
||||
### Tips
|
||||
|
||||
- Use GitHub pull requests for changes to maintain review processes.
|
||||
- Provide clear commit messages describing your changes.
|
||||
- Regularly sync your repository to keep Grafana up to date.
|
||||
- Review the **Events** tab to monitor sync status.
|
||||
|
||||
## Manage dashboards provisioned with file provisioning
|
||||
|
||||
To update any resources in the local path, you need to edit the files directly and then save them locally.
|
||||
These changes are synchronized to Grafana. However, you can't create, edit, or delete these resources using the Grafana UI.
|
||||
|
||||
Refer to [Set up file provisioning](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/observability-as-code/provision-resources/file-path-setup/) for configuration instructions.
|
||||
@@ -0,0 +1,94 @@
|
||||
---
|
||||
description: Instructions for working with Git Sync to perform common tasks, such as saving dashboards to GitHub and synchronizing changes with Grafana.
|
||||
keywords:
|
||||
- as code
|
||||
- as-code
|
||||
- dashboards
|
||||
- git integration
|
||||
- git sync
|
||||
- github
|
||||
labels:
|
||||
products:
|
||||
- enterprise
|
||||
- oss
|
||||
title: Manage provisioned repositories with Git Sync
|
||||
menuTitle: Manage repositories with Git Sync
|
||||
weight: 400
|
||||
canonical: https://grafana.com/docs/grafana/latest/as-code/observability-as-code/provision-resources/use-git-sync/
|
||||
aliases:
|
||||
- ../../../observability-as-code/provision-resources/use-git-sync/ # /docs/grafana/next/observability-as-code/provision-resources/use-git-sync/
|
||||
---
|
||||
|
||||
# Manage provisioned repositories with Git Sync
|
||||
|
||||
{{< admonition type="caution" >}}
|
||||
|
||||
Git Sync is available in [private preview](https://grafana.com/docs/release-life-cycle/) for Grafana Cloud, and is an [experimental feature](https://grafana.com/docs/release-life-cycle/) in Grafana v12 for open source and Enterprise editions.
|
||||
|
||||
Support and documentation is available but might be limited to enablement, configuration, and some troubleshooting. No SLAs are provided.
|
||||
|
||||
You can sign up to the private preview using the [Git Sync early access form](https://forms.gle/WKkR3EVMcbqsNnkD9).
|
||||
|
||||
{{< /admonition >}}
|
||||
|
||||
After you have set up Git Sync, you can synchronize any changes you make in your existing provisioned folders in the UI with your configured GitHub repository. Similarly, if you push a change into your repository, those changes are mirrored in your Grafana instance.
|
||||
|
||||
## View current status of synchronization
|
||||
|
||||
When you synchronize a repository, Git Sync also creates a dashboard that provides a summary of resources, health, pull status, webhook, sync jobs, resources, and files.
|
||||
|
||||
Use the **View** section in **Provisioning** to see detailed information about the current status of your sync, understand the health of your repository's connection with Grafana, and [troubleshoot](#troubleshoot-synchronization) possible issues:
|
||||
|
||||
1. Log in to your Grafana server with an account that has the Grafana Admin or Editor flag set.
|
||||
1. Select **Administration** in the left-side menu and then **Provisioning**.
|
||||
1. Locate the repository you are interested in.
|
||||
1. If you see a green `Up-to-date` label next to the repository name, then everything is syncing as expected.
|
||||
1. Select **View** to access detailed dashboards and reports about the synchronization history of your repository.
|
||||
|
||||
## Synchronize changes
|
||||
|
||||
Synchronizing resources from provisioned repositories into your Grafana instance pulls the resources into the selected folder. Existing dashboards with the same `uid` are overwritten.
|
||||
|
||||
To sync changes from your Grafana dashboards with your Git repository:
|
||||
|
||||
1. From the left menu, select **Administration** > **Provisioning**.
|
||||
1. Select **Pull** under the repository you want to sync.
|
||||
1. Wait for the synchronization process to complete.
|
||||
|
||||
## Remove a repository
|
||||
|
||||
To delete a repository, follow these steps.
|
||||
|
||||
1. Log in to your Grafana server with an account that has the Grafana Admin or Editor flag set.
|
||||
1. Select **Administration** in the left-side menu and then **Provisioning**.
|
||||
1. Locate the repository you are interested in.
|
||||
1. Select the trashcan icon in the right side to delete the chosen entry.
|
||||
1. Select **Delete** to confirm.
|
||||
|
||||
Refer to [Work with provisioned dashboards](../provisioned-dashboards) for information on removing provisioned files.
|
||||
|
||||
## Troubleshoot synchronization
|
||||
|
||||
{{< admonition type="caution" >}}
|
||||
|
||||
Before you proceed to troubleshoot, understand the [known limitations](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/observability-as-code/provision-resources/intro-git-sync#known-limitations/).
|
||||
|
||||
{{< /admonition >}}
|
||||
|
||||
Monitor the **View** status page for synchronization issues and status updates. Common events include:
|
||||
|
||||
- Sync started
|
||||
- Sync completed
|
||||
- Sync failed (with error details)
|
||||
- Sync issues
|
||||
|
||||
### Dashboard sync errors
|
||||
|
||||
- If dashboards are not syncing, check if the repository URL is correct and accessible from the Grafana instance.
|
||||
- Ensure that the configured repository branch exists and is correctly referenced.
|
||||
- Check for conflicts in the repository that may prevent syncing.
|
||||
|
||||
### Dashboard import errors
|
||||
|
||||
- Validate the JSON format of the dashboard files before importing.
|
||||
- If the import fails, check Grafana logs for error messages and troubleshoot accordingly.
|
||||
@@ -0,0 +1,243 @@
|
||||
---
|
||||
description: A reference for the JSON dashboard schemas used with Observability as Code, including the experimental V2 schema.
|
||||
keywords:
|
||||
- configuration
|
||||
- as code
|
||||
- dashboards
|
||||
- git integration
|
||||
- git sync
|
||||
- github
|
||||
labels:
|
||||
products:
|
||||
- cloud
|
||||
- enterprise
|
||||
- oss
|
||||
title: JSON schema v2
|
||||
weight: 200
|
||||
canonical: https://grafana.com/docs/grafana/latest/as-code/observability-as-code/schema-v2/
|
||||
aliases:
|
||||
- ../../observability-as-code/schema-v2/ # /docs/grafana/next/observability-as-code/schema-v2/
|
||||
---
|
||||
|
||||
# Dashboard JSON schema v2
|
||||
|
||||
{{< admonition type="caution" >}}
|
||||
|
||||
Dashboard JSON schema v2 is an [experimental](https://grafana.com/docs/release-life-cycle/) feature. Engineering and on-call support is not available. Documentation is either limited or not provided outside of code comments. No SLA is provided. To get early access to this feature, request it through [this form](https://docs.google.com/forms/d/e/1FAIpQLSd73nQzuhzcHJOrLFK4ef_uMxHAQiPQh1-rsQUT2MRqbeMLpg/viewform?usp=dialog).
|
||||
|
||||
**Do not enable this feature in production environments as it may result in the irreversible loss of data.**
|
||||
|
||||
{{< /admonition >}}
|
||||
|
||||
Grafana dashboards are represented as JSON objects that store metadata, panels, variables, and settings.
|
||||
|
||||
Observability as Code works with all versions of the JSON model, and it's fully compatible with version 2.
|
||||
|
||||
## Before you begin
|
||||
|
||||
Schema v2 is automatically enabled with the Dynamic Dashboards feature toggle.
|
||||
To get early access to this feature, request it through [this form](https://docs.google.com/forms/d/e/1FAIpQLSd73nQzuhzcHJOrLFK4ef_uMxHAQiPQh1-rsQUT2MRqbeMLpg/viewform?usp=dialog).
|
||||
It also requires the new dashboards API feature toggle, `kubernetesDashboards`, to be enabled as well.
|
||||
|
||||
For more information on how dashboards behave depending on your feature flag configuration, refer to [Notes and limitations](#notes-and-limitations).
|
||||
|
||||
## Accessing the JSON Model
|
||||
|
||||
To view the JSON representation of a dashboard:
|
||||
|
||||
1. Toggle on the edit mode switch in the top-right corner of the dashboard.
|
||||
1. Click the gear icon in the top navigation bar to go to **Settings**.
|
||||
1. Select the **JSON Model** tab.
|
||||
1. Copy or edit the JSON structure as needed.
|
||||
|
||||
## JSON fields
|
||||
|
||||
```json
|
||||
{
|
||||
"annotations": [],
|
||||
"cursorSync": "Off",
|
||||
"editable": true,
|
||||
"elements": {},
|
||||
"layout": {
|
||||
"kind": GridLayout, // Can also be AutoGridLayout, RowsLayout, or TabsLayout
|
||||
"spec": {
|
||||
"items": []
|
||||
}
|
||||
},
|
||||
"links": [],
|
||||
"liveNow": false,
|
||||
"preload": false,
|
||||
"tags": [], // Tags associated with the dashboard.
|
||||
"timeSettings": {
|
||||
"autoRefresh": "",
|
||||
"autoRefreshIntervals": [
|
||||
"5s",
|
||||
"10s",
|
||||
"30s",
|
||||
"1m",
|
||||
"5m",
|
||||
"15m",
|
||||
"30m",
|
||||
"1h",
|
||||
"2h",
|
||||
"1d"
|
||||
],
|
||||
"fiscalYearStartMonth": 0,
|
||||
"from": "now-6h",
|
||||
"hideTimepicker": false,
|
||||
"timezone": "browser",
|
||||
"to": "now"
|
||||
},
|
||||
"title": "",
|
||||
"variables": []
|
||||
},
|
||||
```
|
||||
|
||||
The dashboard JSON sample shown uses the default `GridLayoutKind`.
|
||||
The JSON in a new dashboard for the other three layout options, `AutoGridLayout`, `RowsLayout`, and `TabsLayout`, are as follows:
|
||||
|
||||
**`AutoGridLayout`**
|
||||
|
||||
```json
|
||||
"layout": {
|
||||
"kind": "AutoGridLayout",
|
||||
"spec": {
|
||||
"columnWidthMode": "standard",
|
||||
"items": [],
|
||||
"fillScreen": false,
|
||||
"maxColumnCount": 3,
|
||||
"rowHeightMode": "standard"
|
||||
}
|
||||
},
|
||||
```
|
||||
|
||||
**`RowsLayout`**
|
||||
|
||||
```json
|
||||
"layout": {
|
||||
"kind": "RowsLayout",
|
||||
"spec": {
|
||||
"rows": []
|
||||
},
|
||||
```
|
||||
|
||||
**`TabsLayout`**
|
||||
|
||||
```json
|
||||
"layout": {
|
||||
"kind": "TabsLayout",
|
||||
"spec": {
|
||||
"tabs": []
|
||||
},
|
||||
```
|
||||
|
||||
### `DashboardSpec`
|
||||
|
||||
The following table explains the usage of the dashboard JSON fields.
|
||||
The table includes default and other fields:
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
|
||||
| Name | Usage |
|
||||
| ------------ | ------------------------------------------------------------------------- |
|
||||
| annotations | Contains the list of annotations that are associated with the dashboard. |
|
||||
| cursorSync | Dashboard cursor sync behavior.<ul><li>`Off` - No shared crosshair or tooltip (default)</li><li>`Crosshair` - Shared crosshair</li><li>`Tooltip` - Shared crosshair and shared tooltip</li></ul> |
|
||||
| editable | bool. Whether or not a dashboard is editable. |
|
||||
| elements | Contains the list of elements included in the dashboard. Supported dashboard elements are: PanelKind and LibraryPanelKind. |
|
||||
| layout | The dashboard layout. Supported layouts are:<ul><li>GridLayoutKind</li><li>AutoGridLayoutKind</li><li>RowsLayoutKind</li><li>TabsLayoutKind</li></ul> |
|
||||
| links | Links with references to other dashboards or external websites. |
|
||||
| liveNow | bool. When set to `true`, the dashboard redraws panels at an interval matching the pixel width. This keeps data "moving left" regardless of the query refresh rate. This setting helps avoid dashboards presenting stale live data. |
|
||||
| preload | bool. When set to `true`, the dashboard loads all panels when the dashboard is loaded. |
|
||||
| tags | Contains the list of tags associated with dashboard. |
|
||||
| timeSettings | All time settings for the dashboard. |
|
||||
| title | Title of the dashboard. |
|
||||
| variables | Contains the list of configured template variables. |
|
||||
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
### `annotations`
|
||||
|
||||
The configuration for the list of annotations that are associated with the dashboard.
|
||||
For the JSON and field usage notes, refer to the [annotations schema documentation](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/observability-as-code/schema-v2/annotations-schema/).
|
||||
|
||||
### `elements`
|
||||
|
||||
Dashboards can contain the following elements:
|
||||
|
||||
- [PanelKind](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/observability-as-code/schema-v2/panel-schema/)
|
||||
- [LibraryPanelKind](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/observability-as-code/schema-v2/librarypanel-schema/)
|
||||
|
||||
### `layout`
|
||||
|
||||
Dashboards can have four layout options:
|
||||
|
||||
- [GridLayoutKind](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/observability-as-code/schema-v2/layout-schema/#gridlayoutkind)
|
||||
- [AutoGridLayoutKind](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/observability-as-code/schema-v2/layout-schema/#autogridlayoutkind)
|
||||
- [RowsLayoutKind](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/observability-as-code/schema-v2/layout-schema/#rowslayoutkind)
|
||||
- [TabsLayoutKind](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/observability-as-code/schema-v2/layout-schema/#tabslayoutkind)
|
||||
|
||||
For the JSON and field usage notes about each of these, refer to the [layout schema documentation](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/observability-as-code/schema-v2/layout-schema/).
|
||||
|
||||
### `links`
|
||||
|
||||
The configuration for links with references to other dashboards or external websites.
|
||||
|
||||
For the JSON and field usage notes, refer to the [links schema documentation](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/observability-as-code/schema-v2/links-schema/).
|
||||
|
||||
### `tags`
|
||||
|
||||
The tags associated with the dashboard:
|
||||
|
||||
` [...string]`
|
||||
|
||||
### `timesettings`
|
||||
|
||||
The `TimeSettingsSpec` defines the default time configuration for the time picker and the refresh picker for the specific dashboard.
|
||||
For the JSON and field usage notes about the `TimeSettingsSpec`, refer to the [timesettings schema documentation](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/observability-as-code/schema-v2/timesettings-schema/).
|
||||
|
||||
### `variables`
|
||||
|
||||
The `variables` schema defines which variables are used in the dashboard.
|
||||
|
||||
There are eight variables types:
|
||||
|
||||
- QueryVariableKind
|
||||
- TextVariableKind
|
||||
- ConstantVariableKind
|
||||
- DatasourceVariableKind
|
||||
- IntervalVariableKind
|
||||
- CustomVariableKind
|
||||
- GroupByVariableKind
|
||||
- AdhocVariableKind
|
||||
|
||||
For the JSON and field usage notes about the `variables` spec, refer to the [variables schema documentation](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/observability-as-code/schema-v2/variables-schema/).
|
||||
|
||||
## Notes and limitations
|
||||
|
||||
### Existing dashboards
|
||||
|
||||
With schema v2 enabled, you can still open and view your pre-existing dashboards.
|
||||
Upon saving, they’ll be updated to the new schema where you can take advantage of the new features and functionalities.
|
||||
|
||||
### Dashboard behavior with disabled feature flags
|
||||
|
||||
If you disable the Dynamic dashboards or `kubernetesDashboards` feature flags, you should be aware of how dashboards will behave.
|
||||
|
||||
#### Disable Dynamic dashboards
|
||||
|
||||
If the Dynamic dashboards feature toggle is disabled, depending on how the dashboard was built, it will behave differently:
|
||||
|
||||
- Dashboards built on the new schema through the UI - View only
|
||||
- Dashboards built on Schema v1 - View and edit
|
||||
- Dashboards built on the new schema by way of Terraform or the CLI - View and edit
|
||||
- Provisioned dashboards built on the new schema - View and edit, but the edit experience will be the old experience
|
||||
|
||||
#### Disable Dynamic dashboards and `kubernetesDashboards`
|
||||
|
||||
You’ll be unable to view or edit dashboards created or updated in the new schema.
|
||||
|
||||
### Import and export
|
||||
|
||||
From the UI, dashboards created on schema v2 can be exported and imported like other dashboards.
|
||||
When you export them to use in another instance, references of data sources are not persisted but data source types are.
|
||||
You’ll have the option to select the data source of your choice in the import UI.
|
||||
@@ -0,0 +1,86 @@
|
||||
---
|
||||
description: A reference for the JSON annotations schema used with Observability as Code.
|
||||
keywords:
|
||||
- configuration
|
||||
- as code
|
||||
- as-code
|
||||
- dashboards
|
||||
- git integration
|
||||
- git sync
|
||||
- github
|
||||
- annotations
|
||||
labels:
|
||||
products:
|
||||
- cloud
|
||||
- enterprise
|
||||
- oss
|
||||
menuTitle: annotations schema
|
||||
title: annotations
|
||||
weight: 100
|
||||
canonical: https://grafana.com/docs/grafana/latest/as-code/observability-as-code/schema-v2/annotations-schema/
|
||||
aliases:
|
||||
- ../../../observability-as-code/schema-v2/annotations-schema/ # /docs/grafana/next/observability-as-code/schema-v2/annotations-schema/
|
||||
---
|
||||
|
||||
# `annotations`
|
||||
|
||||
The configuration for the list of annotations that are associated with the dashboard.
|
||||
|
||||
```json
|
||||
"annotations": [
|
||||
{
|
||||
"kind": "AnnotationQuery",
|
||||
"spec": {
|
||||
"builtIn": false,
|
||||
"datasource": {
|
||||
"type": "",
|
||||
"uid": ""
|
||||
},
|
||||
"enable": false,
|
||||
"hide": false,
|
||||
"iconColor": "",
|
||||
"name": ""
|
||||
}
|
||||
}
|
||||
],
|
||||
```
|
||||
|
||||
`AnnotationsQueryKind` consists of:
|
||||
|
||||
- kind: "AnnotationQuery"
|
||||
- spec: [AnnotationQuerySpec](#annotationqueryspec)
|
||||
|
||||
## `AnnotationQuerySpec`
|
||||
|
||||
| Name | Type/Definition |
|
||||
| ---------- | ----------------------------------------------------------------- |
|
||||
| datasource | [`DataSourceRef`](#datasourceref) |
|
||||
| query | [`DataQueryKind`](#dataquerykind) |
|
||||
| enable | bool |
|
||||
| hide | bool |
|
||||
| iconColor | string |
|
||||
| name | string |
|
||||
| builtIn | bool. Default is `false`. |
|
||||
| filter | [`AnnotationPanelFilter`](#annotationpanelfilter) |
|
||||
| options | `[string]`: A catch-all field for datasource-specific properties. |
|
||||
|
||||
### `DataSourceRef`
|
||||
|
||||
| Name | Usage |
|
||||
| ----- | ---------------------------------- |
|
||||
| type? | string. The plugin type-id. |
|
||||
| uid? | The specific data source instance. |
|
||||
|
||||
### `DataQueryKind`
|
||||
|
||||
| Name | Type |
|
||||
| ---- | ------ |
|
||||
| kind | string |
|
||||
| spec | string |
|
||||
|
||||
### `AnnotationPanelFilter`
|
||||
|
||||
| Name | Type/Definition |
|
||||
| -------- | ------------------------------------------------------------------------------ |
|
||||
| exclude? | bool. Should the specified panels be included or excluded. Default is `false`. |
|
||||
| ids | `[...uint8]`. Panel IDs that should be included or excluded. |
|
||||
@@ -0,0 +1,339 @@
|
||||
---
|
||||
description: A reference for the JSON layout schema used with Observability as Code.
|
||||
keywords:
|
||||
- configuration
|
||||
- as code
|
||||
- as-code
|
||||
- dashboards
|
||||
- git integration
|
||||
- git sync
|
||||
- github
|
||||
- layout
|
||||
labels:
|
||||
products:
|
||||
- cloud
|
||||
- enterprise
|
||||
- oss
|
||||
menuTitle: layout schema
|
||||
title: layout
|
||||
weight: 400
|
||||
canonical: https://grafana.com/docs/grafana/latest/as-code/observability-as-code/schema-v2/layout-schema/
|
||||
aliases:
|
||||
- ../../../observability-as-code/schema-v2/layout-schema/ # /docs/grafana/next/observability-as-code/schema-v2/layout-schema/
|
||||
---
|
||||
|
||||
# `layout`
|
||||
|
||||
There are four layout options offering two types of panel control:
|
||||
|
||||
**Panel layout options**
|
||||
|
||||
These options control the size and position of panels:
|
||||
|
||||
- [GridLayoutKind](#gridlayoutkind) - Corresponds to the **Custom** option in the UI. You define panel size and panel positions using x- and y- settings.
|
||||
- [AutoGridLayoutKind](#autogridlayoutkind) - Corresponds to the **Auto grid** option in the UI. Panel size and position are automatically set based on column and row parameters.
|
||||
|
||||
**Panel grouping options**
|
||||
|
||||
These options control the grouping of panels:
|
||||
|
||||
- [RowsLayoutKind](#rowslayoutkind) - Groups panels into rows.
|
||||
- [TabsLayoutKind](#tabslayoutkind) - Groups panels into tabs.
|
||||
|
||||
## `GridLayoutKind`
|
||||
|
||||
The grid layout allows you to manually size and position grid items by setting the height, width, x, and y of each item.
|
||||
This layout corresponds to the **Custom** option in the UI.
|
||||
|
||||
Following is the JSON for a default grid layout, a grid layout item, and a grid layout row:
|
||||
|
||||
```json
|
||||
"kind": "GridLayout",
|
||||
"spec": {
|
||||
"items": [
|
||||
{
|
||||
"kind": "GridLayoutItem",
|
||||
"spec": {
|
||||
"element": {...},
|
||||
"height": 0,
|
||||
"width": 0,
|
||||
"x": 0,
|
||||
"y": 0
|
||||
}
|
||||
},
|
||||
{
|
||||
"kind": "GridLayoutRow",
|
||||
"spec": {
|
||||
"collapsed": false,
|
||||
"elements": [],
|
||||
"title": "",
|
||||
"y": 0
|
||||
}
|
||||
},
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
`GridLayoutKind` consists of:
|
||||
|
||||
- kind: "GridLayout"
|
||||
- spec: GridLayoutSpec
|
||||
- items: GridLayoutItemKind` or GridLayoutRowKind`
|
||||
- GridLayoutItemKind
|
||||
- kind: "GridLayoutItem"
|
||||
- spec: [GridLayoutItemSpec](#gridlayoutitemspec)
|
||||
- GridLayoutRowKind
|
||||
- kind: "GridLayoutRow"
|
||||
- spec: [GridLayoutRowSpec](#gridlayoutrowspec)
|
||||
|
||||
### `GridLayoutItemSpec`
|
||||
|
||||
The following table explains the usage of the grid layout item JSON fields:
|
||||
|
||||
| Name | Usage |
|
||||
| ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| x | integer. Position of the item x-axis. |
|
||||
| y | integer. Position of the item y-axis. |
|
||||
| width | Width of the item in pixels. |
|
||||
| height | Height of the item in pixels. |
|
||||
| element | `ElementReference`. Reference to a [`PanelKind`](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/observability-as-code/schema-v2/panel-schema/) from `dashboard.spec.elements` expressed as JSON Schema reference. |
|
||||
| repeat? | [RepeatOptions](#repeatoptions). Configured repeat options, if any |
|
||||
|
||||
#### `RepeatOptions`
|
||||
|
||||
The following table explains the usage of the repeat option JSON fields:
|
||||
|
||||
| Name | Usage |
|
||||
| ---------- | ---------------------------------------------------- |
|
||||
| mode | `RepeatMode` - "variable" |
|
||||
| value | string |
|
||||
| direction? | Options are `h` for horizontal and `v` for vertical. |
|
||||
| maxPerRow? | integer |
|
||||
|
||||
### `GridLayoutRowSpec`
|
||||
|
||||
The following table explains the usage of the grid layout row JSON fields:
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
|
||||
| Name | Usage |
|
||||
| ---- | ----- |
|
||||
| y | integer. Position of the row y-axis |
|
||||
| collapsed | bool. Whether or not the row is collapsed |
|
||||
| title | Row title |
|
||||
| elements | [`[...GridLayoutItemKind]`](#gridlayoutitemspec). Grid items in the row will have their y value be relative to the row's y value. This means a panel positioned at `y: 0` in a row with `y: 10` will be positioned at `y: 11` (row header has a height of 1) in the dashboard. |
|
||||
| repeat? | [RowRepeatOptions](#rowrepeatoptions) Configured row repeat options, if any</p> |
|
||||
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
#### `RowRepeatOptions`
|
||||
|
||||
| Name | Usage |
|
||||
| ----- | ------------------------- |
|
||||
| mode | `RepeatMode` - "variable" |
|
||||
| value | string |
|
||||
|
||||
## `AutoGridLayoutKind`
|
||||
|
||||
With an auto grid, Grafana sizes and positions your panels for the best fit based on the column and row constraints that you set.
|
||||
This layout corresponds to the **Auto grid** option in the UI.
|
||||
|
||||
Following is the JSON for a default auto grid layout and a grid layout item:
|
||||
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
```json
|
||||
"kind": "AutoGridLayout",
|
||||
"spec": {
|
||||
"columnWidthMode": "standard",
|
||||
"fillScreen": false,
|
||||
"items": [
|
||||
{
|
||||
"kind": "AutoGridLayoutItem",
|
||||
"spec": {
|
||||
"element": {...},
|
||||
}
|
||||
}
|
||||
],
|
||||
"maxColumnCount": 3,
|
||||
"rowHeightMode": "standard"
|
||||
}
|
||||
```
|
||||
|
||||
`AutoGridLayoutKind` consists of:
|
||||
|
||||
- kind: "AutoGridLayout"
|
||||
- spec: [AutoGridLayoutSpec](#autogridlayoutspec)
|
||||
|
||||
### `AutoGridLayoutSpec`
|
||||
|
||||
The following table explains the usage of the auto grid layout JSON fields:
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
|
||||
| Name | Usage |
|
||||
| ---- | ----- |
|
||||
| maxColumnCount? | number. Default is `3`. |
|
||||
| columnWidthMode | Options are: `narrow`, `standard`, `wide`, and `custom`. Default is `standard`. |
|
||||
| columnWidth? | number |
|
||||
| rowHeightMode | Options are: `short`, `standard`, `tall`, and `custom`. Default is `standard`. |
|
||||
| rowHeight? | number |
|
||||
| fillScreen? | bool. Default is `false`. |
|
||||
| items | `AutoGridLayoutItemKind`. Consists of:<ul><li>kind: "AutoGridLayoutItem"</li><li>spec: [AutoGridLayoutItemSpec](#autogridlayoutitemspec)</li></ul> |
|
||||
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
#### `AutoGridLayoutItemSpec`
|
||||
|
||||
The following table explains the usage of the auto grid layout item JSON fields:
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
|
||||
| Name | Usage |
|
||||
| ---- | ----- |
|
||||
| element | `ElementReference`. Reference to a [`PanelKind`](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/observability-as-code/schema-v2/panel-schema/) from `dashboard.spec.elements` expressed as JSON Schema reference. |
|
||||
| repeat? | [AutoGridRepeatOptions](#autogridrepeatoptions). Configured repeat options, if any. |
|
||||
| conditionalRendering? | `ConditionalRenderingGroupKind`. Rules for hiding or showing panels, if any. Consists of:<ul><li>kind: "ConditionalRenderingGroup"</li><li>spec: [ConditionalRenderingGroupSpec](#conditionalrenderinggroupspec)</li></ul> |
|
||||
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
##### `AutoGridRepeatOptions`
|
||||
|
||||
The following table explains the usage of the auto grid repeat option JSON fields:
|
||||
|
||||
| Name | Usage |
|
||||
| ----- | ------------------------- |
|
||||
| mode | `RepeatMode` - "variable" |
|
||||
| value | String |
|
||||
|
||||
##### `ConditionalRenderingGroupSpec`
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
|
||||
| Name | Usage |
|
||||
| ---- | ----- |
|
||||
| visibility | Options are `show` and `hide` |
|
||||
| condition | Options are `and` and `or` |
|
||||
| items | Options are:<ul><li>ConditionalRenderingVariableKind<ul><li>kind: "ConditionalRenderingVariable"</li><li>spec: [ConditionalRenderingVariableSpec](#conditionalrenderingvariablespec)</li></ul></li><li>ConditionalRenderingDataKind<ul><li>kind: "ConditionalRenderingData"</li><li>spec: [ConditionalRenderingDataSpec](#conditionalrenderingdataspec)</li></ul></li><li>ConditionalRenderingTimeRangeSizeKind<ul><li>kind: "ConditionalRenderingTimeRangeSize"</li><li>spec: [ConditionalRenderingTimeRangeSizeSpec](#conditionalrenderingtimerangesizespec)</li></ul></li></ul> |
|
||||
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
###### `ConditionalRenderingVariableSpec`
|
||||
|
||||
| Name | Usage |
|
||||
| -------- | ------------------------------------ |
|
||||
| variable | string |
|
||||
| operator | Options are `equals` and `notEquals` |
|
||||
| value | string |
|
||||
|
||||
###### `ConditionalRenderingDataSpec`
|
||||
|
||||
| Name | Type |
|
||||
| ----- | ---- |
|
||||
| value | bool |
|
||||
|
||||
###### `ConditionalRenderingTimeRangeSizeSpec`
|
||||
|
||||
| Name | Type |
|
||||
| ----- | ------ |
|
||||
| value | string |
|
||||
|
||||
## `RowsLayoutKind`
|
||||
|
||||
The `RowsLayoutKind` is one of two options that you can use to group panels.
|
||||
You can nest any other kind of layout inside a layout row.
|
||||
Rows can also be nested in auto grids or tabs.
|
||||
|
||||
Following is the JSON for a default rows layout row:
|
||||
|
||||
```json
|
||||
"kind": "RowsLayout",
|
||||
"spec": {
|
||||
"rows": [
|
||||
{
|
||||
"kind": "RowsLayoutRow",
|
||||
"spec": {
|
||||
"layout": {
|
||||
"kind": "GridLayout", // Can also be AutoGridLayout or TabsLayout
|
||||
"spec": {...}
|
||||
},
|
||||
"title": ""
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
`RowsLayoutKind` consists of:
|
||||
|
||||
- kind: RowsLayout
|
||||
- spec: RowsLayoutSpec
|
||||
- rows: RowsLayoutRowKind
|
||||
- kind: RowsLayoutRow
|
||||
- spec: [RowsLayoutRowSpec](#rowslayoutrowspec)
|
||||
|
||||
### `RowsLayoutRowSpec`
|
||||
|
||||
The following table explains the usage of the rows layout row JSON fields:
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
|
||||
| Name | Usage |
|
||||
| ---- | ----- |
|
||||
| title? | Title of the row. |
|
||||
| collapse | bool. Whether or not the row is collapsed. |
|
||||
| hideHeader? | bool. Whether the row header is hidden or shown. |
|
||||
| fullScreen? | bool. Whether or not the row takes up the full screen. |
|
||||
| conditionalRendering? | `ConditionalRenderingGroupKind`. Rules for hiding or showing rows, if any. Consists of:<ul><li>kind: "ConditionalRenderingGroup"</li><li>spec: [ConditionalRenderingGroupSpec](#conditionalrenderinggroupspec)</li></ul> |
|
||||
| repeat? | [RowRepeatOptions](#rowrepeatoptions). Configured repeat options, if any. |
|
||||
| layout | Supported layouts are:<ul><li>[GridLayoutKind](#gridlayoutkind)</li><li>[RowsLayoutKind](#rowslayoutkind)</li><li>[AutoGridLayoutKind](#autogridlayoutkind)</li><li>[TabsLayoutKind](#tabslayoutkind)</li></ul> |
|
||||
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
## `TabsLayoutKind`
|
||||
|
||||
The `TabsLayoutKind` is one of two options that you can use to group panels.
|
||||
You can nest any other kind of layout inside a tab.
|
||||
Tabs can also be nested in auto grids or rows.
|
||||
|
||||
Following is the JSON for a default tabs layout tab and a tab:
|
||||
|
||||
```json
|
||||
"kind": "TabsLayout",
|
||||
"spec": {
|
||||
"tabs": [
|
||||
{
|
||||
"kind": "TabsLayoutTab",
|
||||
"spec": {
|
||||
"layout": {
|
||||
"kind": "GridLayout", // Can also be AutoGridLayout or RowsLayout
|
||||
"spec": {...}
|
||||
},
|
||||
"title": "New tab"
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
`TabsLayoutKind` consists of:
|
||||
|
||||
- kind: TabsLayout
|
||||
- spec: TabsLayoutSpec
|
||||
- tabs: TabsLayoutTabKind
|
||||
- kind: TabsLayoutTab
|
||||
- spec: [TabsLayoutTabSpec](#tabslayouttabspec)
|
||||
|
||||
### `TabsLayoutTabSpec`
|
||||
|
||||
The following table explains the usage of the tabs layout tab JSON fields:
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
|
||||
| Name | Usage |
|
||||
| ---- | ----- |
|
||||
| title? | The title of the tab. |
|
||||
| layout | Supported layouts are:<ul><li>[GridLayoutKind](#gridlayoutkind)</li><li>[RowsLayoutKind](#rowslayoutkind)</li><li>[AutoGridLayoutKind](#autogridlayoutkind)</li><li>[TabsLayoutKind](#tabslayoutkind)</li></ul> |
|
||||
| conditionalRendering? | `ConditionalRenderingGroupKind`. Rules for hiding or showing panels, if any. Consists of:<ul><li>kind: "ConditionalRenderingGroup"</li><li>spec: [ConditionalRenderingGroupSpec](#conditionalrenderinggroupspec)</li></ul> |
|
||||
|
||||
<!-- prettier-ignore-end -->
|
||||
@@ -0,0 +1,68 @@
|
||||
---
|
||||
description: A reference for the JSON library panel schema used with Observability as Code.
|
||||
keywords:
|
||||
- configuration
|
||||
- as code
|
||||
- as-code
|
||||
- dashboards
|
||||
- git integration
|
||||
- git sync
|
||||
- github
|
||||
- library panel
|
||||
labels:
|
||||
products:
|
||||
- cloud
|
||||
- enterprise
|
||||
- oss
|
||||
menuTitle: LibraryPanelKind schema
|
||||
title: LibraryPanelKind
|
||||
weight: 300
|
||||
canonical: https://grafana.com/docs/grafana/latest/as-code/observability-as-code/schema-v2/librarypanel-schema/
|
||||
aliases:
|
||||
- ../../../observability-as-code/schema-v2/librarypanel-schema/ # /docs/grafana/next/observability-as-code/schema-v2/librarypanel-schema/
|
||||
---
|
||||
|
||||
# `LibraryPanelKind`
|
||||
|
||||
A library panel is a reusable panel that you can use in any dashboard.
|
||||
When you make a change to a library panel, that change propagates to all instances of where the panel is used.
|
||||
Library panels streamline reuse of panels across multiple dashboards.
|
||||
|
||||
Following is the default library panel element JSON:
|
||||
|
||||
```json
|
||||
"kind": "LibraryPanel",
|
||||
"spec": {
|
||||
"id": 0,
|
||||
"libraryPanel": {
|
||||
name: "",
|
||||
uid: "",
|
||||
}
|
||||
"title": ""
|
||||
}
|
||||
```
|
||||
|
||||
The `LibraryPanelKind` consists of:
|
||||
|
||||
- kind: "LibraryPanel"
|
||||
- spec: [LibraryPanelKindSpec](#librarypanelkindspec)
|
||||
- libraryPanel: [LibraryPanelRef](#librarypanelref)
|
||||
|
||||
## `LibraryPanelKindSpec`
|
||||
|
||||
The following table explains the usage of the library panel element JSON fields:
|
||||
|
||||
| Name | Usage |
|
||||
| ------------ | ------------------------------------------------ |
|
||||
| id | Panel ID for the library panel in the dashboard. |
|
||||
| libraryPanel | [`LibraryPanelRef`](#librarypanelref) |
|
||||
| title | Title for the library panel in the dashboard. |
|
||||
|
||||
### `LibraryPanelRef`
|
||||
|
||||
The following table explains the usage of the library panel reference JSON fields:
|
||||
|
||||
| Name | Usage |
|
||||
| ---- | ------------------ |
|
||||
| name | Library panel name |
|
||||
| uid | Library panel uid |
|
||||
@@ -0,0 +1,66 @@
|
||||
---
|
||||
description: A reference for the JSON links schema used with Observability as Code.
|
||||
keywords:
|
||||
- configuration
|
||||
- as code
|
||||
- as-code
|
||||
- dashboards
|
||||
- git integration
|
||||
- git sync
|
||||
- github
|
||||
- links
|
||||
labels:
|
||||
products:
|
||||
- cloud
|
||||
- enterprise
|
||||
- oss
|
||||
menuTitle: links schema
|
||||
title: links
|
||||
weight: 500
|
||||
canonical: https://grafana.com/docs/grafana/latest/as-code/observability-as-code/schema-v2/links-schema/
|
||||
aliases:
|
||||
- ../../../observability-as-code/schema-v2/links-schema/ # /docs/grafana/next/observability-as-code/schema-v2/links-schema/
|
||||
---
|
||||
|
||||
# `links`
|
||||
|
||||
The `links` schema is the configuration for links with references to other dashboards or external websites.
|
||||
Following are the default JSON fields:
|
||||
|
||||
```json
|
||||
"links": [
|
||||
{
|
||||
"asDropdown": false,
|
||||
"icon": "",
|
||||
"includeVars": false,
|
||||
"keepTime": false,
|
||||
"tags": [],
|
||||
"targetBlank": false,
|
||||
"title": "",
|
||||
"tooltip": "",
|
||||
"type": "link",
|
||||
},
|
||||
],
|
||||
```
|
||||
|
||||
## `DashboardLink`
|
||||
|
||||
The following table explains the usage of the dashboard link JSON fields.
|
||||
The table includes default and other fields:
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
|
||||
| Name | Usage |
|
||||
| ----------- | --------------------------------------- |
|
||||
| title | string. Title to display with the link. |
|
||||
| type | `DashboardLinkType`. Link type. Accepted values are:<ul><li>dashboards - To refer to another dashboard</li><li>link - To refer to an external resource</li></ul> |
|
||||
| icon | string. Icon name to be displayed with the link. |
|
||||
| tooltip | string. Tooltip to display when the user hovers their mouse over it. |
|
||||
| url? | string. Link URL. Only required/valid if the type is link. |
|
||||
| tags | string. List of tags to limit the linked dashboards. If empty, all dashboards will be displayed. Only valid if the type is dashboards. |
|
||||
| asDropdown | bool. If true, all dashboards links will be displayed in a dropdown. If false, all dashboards links will be displayed side by side. Only valid if the type is dashboards. Default is `false`. |
|
||||
| targetBlank | bool. If true, the link will be opened in a new tab. Default is `false`. |
|
||||
| includeVars | bool. If true, includes current template variables values in the link as query params. Default is `false`. |
|
||||
| keepTime | bool. If true, includes current time range in the link as query params. Default is `false`. |
|
||||
|
||||
<!-- prettier-ignore-end -->
|
||||
@@ -0,0 +1,305 @@
|
||||
---
|
||||
description: A reference for the JSON panel schema used with Observability as Code.
|
||||
keywords:
|
||||
- configuration
|
||||
- as code
|
||||
- as-code
|
||||
- dashboards
|
||||
- git integration
|
||||
- git sync
|
||||
- github
|
||||
- panels
|
||||
labels:
|
||||
products:
|
||||
- cloud
|
||||
- enterprise
|
||||
- oss
|
||||
menuTitle: PanelKind schema
|
||||
title: PanelKind
|
||||
weight: 200
|
||||
canonical: https://grafana.com/docs/grafana/latest/as-code/observability-as-code/schema-v2/panel-schema/
|
||||
aliases:
|
||||
- ../../../observability-as-code/schema-v2/panel-schema/ # /docs/grafana/next/observability-as-code/schema-v2/panel-schema/
|
||||
---
|
||||
|
||||
# `PanelKind`
|
||||
|
||||
The panel element contains all the information about the panel including the visualization type, panel and visualization configuration, queries, and transformations.
|
||||
There's a panel element for each panel contained in the dashboard.
|
||||
|
||||
Following is the default panel element JSON:
|
||||
|
||||
```json
|
||||
"kind": "Panel",
|
||||
"spec": {
|
||||
"data": {
|
||||
"kind": "QueryGroup",
|
||||
"spec": {...},
|
||||
"description": "",
|
||||
"id": 0,
|
||||
"links": [],
|
||||
"title": "",
|
||||
"vizConfig": {
|
||||
"kind": "",
|
||||
"spec": {...},
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
The `PanelKind` consists of:
|
||||
|
||||
- kind: "Panel"
|
||||
- spec: [PanelSpec](#panelspec)
|
||||
|
||||
## `PanelSpec`
|
||||
|
||||
The following table explains the usage of the panel element JSON fields:
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
|
||||
| Name | Usage |
|
||||
| ------------ | --------------------------------------------------------------------- |
|
||||
| data | `QueryGroupKind`, which includes queries and transformations. Consists of:<ul><li>kind: "QueryGroup"</li><li>spec: [QueryGroupSpec](#querygroupspec)</li></ul> |
|
||||
| description | The panel description. |
|
||||
| id | The panel ID. |
|
||||
| links | Links with references to other dashboards or external websites. |
|
||||
| title | The panel title. |
|
||||
| vizConfig | `VizConfigKind`. Includes visualization type, field configuration options, and all other visualization options. Consists of:<ul><li>kind: string. Plugin ID.</li><li>spec: [VizConfigSpec](#vizconfigspec)</li></ul> |
|
||||
| transparent? | bool. Controls whether or not the panel background is transparent. |
|
||||
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
### `QueryGroupSpec`
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
|
||||
| Name | Usage |
|
||||
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
||||
| queries | `PanelQueryKind`. Consists of:<ul><li>kind: PanelQuery</li><li>spec: [PanelQuerySpec](#panelqueryspec)</li></ul> |
|
||||
| transformations | `TransformationKind`. Consists of:<ul><li>kind: string. The transformation ID.</li><li>spec: [DataTransformerConfig](#datatransformerconfig)</li></ul> |
|
||||
| queryOptions | [`QueryOptionsSpec`](#queryoptionsspec) |
|
||||
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
#### `PanelQuerySpec`
|
||||
|
||||
| Name | Usage |
|
||||
| ----------- | --------------------------------- |
|
||||
| query | [`DataQueryKind`](#dataquerykind) |
|
||||
| datasource? | [`DataSourceRef`](#datasourceref) |
|
||||
|
||||
##### `DataQueryKind`
|
||||
|
||||
| Name | Type |
|
||||
| ---- | ------ |
|
||||
| kind | string |
|
||||
| spec | string |
|
||||
|
||||
##### `DataSourceRef`
|
||||
|
||||
| Name | Usage |
|
||||
| ----- | ---------------------------------- |
|
||||
| type? | string. The plugin type-id. |
|
||||
| uid? | The specific data source instance. |
|
||||
|
||||
#### `DataTransformerConfig`
|
||||
|
||||
Transformations allow you to manipulate data returned by a query before the system applies a visualization.
|
||||
Using transformations you can: rename fields, join time series data, perform mathematical operations across queries, or use the output of one transformation as the input to another transformation.
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
|
||||
| Name | Usage |
|
||||
| --------- | ------------------------------------------- |
|
||||
| id | string. Unique identifier of transformer. |
|
||||
| disabled? | bool. Disabled transformations are skipped. |
|
||||
| filter? | [`MatcherConfig`](#matcherconfig). Optional frame matcher. When missing it will be applied to all results. |
|
||||
| topic? | `DataTopic`. Where to pull `DataFrames` from as input to transformation. Options are: `series`, `annotations`, and `alertStates`. |
|
||||
| options | Options to be passed to the transformer. Valid options depend on the transformer id. |
|
||||
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
##### `MatcherConfig`
|
||||
|
||||
Matcher is a predicate configuration.
|
||||
Based on the configuration a set of field or values, it's filtered to apply an override or transformation.
|
||||
It comes with in id (to resolve implementation from registry) and a configuration that’s specific to a particular matcher type.
|
||||
|
||||
| Name | Usage |
|
||||
| -------- | -------------------------------------------------------------------------------------- |
|
||||
| id | string. The matcher id. This is used to find the matcher implementation from registry. |
|
||||
| options? | The matcher options. This is specific to the matcher implementation. |
|
||||
|
||||
#### `QueryOptionsSpec`
|
||||
|
||||
| Name | Type |
|
||||
| ----------------- | ------- |
|
||||
| timeFrom? | string |
|
||||
| maxDataPoints? | integer |
|
||||
| timeShift? | string |
|
||||
| queryCachingTTL? | integer |
|
||||
| interval? | string |
|
||||
| cacheTimeout? | string |
|
||||
| hideTimeOverride? | bool |
|
||||
|
||||
### `VizConfigSpec`
|
||||
|
||||
| Name | Type/Definition |
|
||||
| ------------- | --------------------------------------- |
|
||||
| pluginVersion | string |
|
||||
| options | string |
|
||||
| fieldConfig | [FieldConfigSource](#fieldconfigsource) |
|
||||
|
||||
#### `FieldConfigSource`
|
||||
|
||||
The data model used in Grafana, namely the _data frame_, is a columnar-oriented table structure that unifies both time series and table query results.
|
||||
Each column within this structure is called a field.
|
||||
A field can represent a single time series or table column.
|
||||
Field options allow you to change how the data is displayed in your visualizations.
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
|
||||
| Name | Type/Definition |
|
||||
| ---------- | ------------------------------------- |
|
||||
| defaults | [`FieldConfig`](#fieldconfig). Defaults are the options applied to all fields. |
|
||||
| overrides | The options applied to specific fields overriding the defaults. |
|
||||
| matcher | [`MatcherConfig`](#matcherconfig). Optional frame matcher. When missing it will be applied to all results. |
|
||||
| properties | `DynamicConfigValue`. Consists of:<ul><li>`id` - string</li><li>value?</li></ul> |
|
||||
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
##### `FieldConfig`
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
|
||||
| Name | Type/Definition |
|
||||
| ------------------ | --------------------------------------- |
|
||||
| displayName? | string. The display value for this field. This supports template variables where empty is auto. |
|
||||
| displayNameFromDS? | string. This can be used by data sources that return an explicit naming structure for values and labels. When this property is configured, this value is used rather than the default naming strategy. |
|
||||
| description? | string. Human readable field metadata. |
|
||||
| path? | string. An explicit path to the field in the data source. When the frame meta includes a path, this will default to `${frame.meta.path}/${field.name}`. When defined, this value can be used as an identifier within the data source scope, and may be used to update the results. |
|
||||
| writeable? | bool. True if the data source can write a value to the path. Auth/authz are supported separately. |
|
||||
| filterable? | bool. True if the data source field supports ad-hoc filters. |
|
||||
| unit? | string. Unit a field should use. The unit you select is applied to all fields except time. You can use the unit's ID available in Grafana or a custom unit. [Available units in Grafana](https://github.com/grafana/grafana/blob/main/packages/grafana-data/src/valueFormats/categories.ts). As custom units, you can use the following formats:<ul><li>`suffix:<suffix>` for custom unit that should go after value.</li><li>`prefix:<prefix>` for custom unit that should go before value.</li><li> `time:<format>` for custom date time formats type for example</li><li>`time:YYYY-MM-DD`</li><li>`si:<base scale><unit characters>` for custom SI units. For example: `si: mF`. You can specify both a unit and the source data scale, so if your source data is represented as milli (thousands of) something, prefix the unit with that SI scale character.</li><li>`count:<unit>` for a custom count unit.</li><li>`currency:<unit>` for custom a currency unit.</li></ul> |
|
||||
| decimals? | number. Specify the number of decimals Grafana includes in the rendered value. If you leave this field blank, Grafana automatically truncates the number of decimals based on the value. For example 1.1234 will display as 1.12 and 100.456 will display as 100. To display all decimals, set the unit to `string`. |
|
||||
| min? | number. The minimum value used in percentage threshold calculations. Leave empty for auto calculation based on all series and fields. |
|
||||
| max? | number. The maximum value used in percentage threshold calculations. Leave empty for auto calculation based on all series and fields. |
|
||||
| mappings? | `[...ValueMapping]`. Convert input values into a display string. Options are: [`ValueMap`](#valuemap), [`RangeMap`](#rangemap), [`RegexMap`](#rangemap), [`SpecialValueMap`](#specialvaluemap). |
|
||||
| thresholds? | `ThresholdsConfig`. Map numeric values to states. Consists of:<ul><li>`mode` - `ThresholdsMode`. Options are: `absolute` and `percentage`.</li><li>`steps` - `[...Threshold]`</li></ul> |
|
||||
| color? | [`FieldColor`](#fieldcolor). Panel color configuration. |
|
||||
| links? | `[...]`. The behavior when clicking a result. |
|
||||
| noValue? | string. Alternative to an empty string. |
|
||||
| custom? | `{...}`. Specified by the `FieldConfig` field in panel plugin schemas. |
|
||||
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
###### `ValueMap`
|
||||
|
||||
Maps text values to a color or different display text and color.
|
||||
For example, you can configure a value mapping so that all instances of the value 10 appear as Perfection! rather than the number.
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
|
||||
| Name | Usage |
|
||||
| ------- | -------- |
|
||||
| type | `MappingType` & "value". `MappingType` options are: `value`, `range`, `regex`, and `special`. |
|
||||
| options | string. [`ValueMappingResult`](#valuemappingresult). Map with `<value_to_match>`: `ValueMappingResult`. For example: `{ "10": { text: "Perfection!", color: "green" } }`. |
|
||||
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
###### `RangeMap`
|
||||
|
||||
Maps numerical ranges to a display text and color.
|
||||
For example, if a value is within a certain range, you can configure a range value mapping to display Low or High rather than the number.
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
|
||||
| Name | Usage |
|
||||
| ------- | ---------------------------------------------------------------------------------------------------- |
|
||||
| type | `MappingType` & "range". `MappingType` options are: `value`, `range`, `regex`, and `special`. |
|
||||
| options | Range to match against and the result to apply when the value is within the range. Spec:<ul><li>`from` - `float64` or `null`. Min value of the range. It can be null which means `-Infinity`.</li><li>`to` - `float64` or `null`. Max value of the range. It can be null which means `+Infinity`.</li><li>`result` - [`ValueMappingResult`](#valuemappingresult) |
|
||||
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
###### `RegexMap`
|
||||
|
||||
Maps regular expressions to replacement text and a color.
|
||||
For example, if a value is `www.example.com`, you can configure a regex value mapping so that Grafana displays www and truncates the domain.
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
|
||||
| Name | Usage |
|
||||
| ------- | --------------------------------------------------------------------------------------------- |
|
||||
| type | `MappingType` & "regex". `MappingType` options are: `value`, `range`, `regex`, and `special`. |
|
||||
| options | Regular expression to match against and the result to apply when the value matches the regex. Spec:<ul><li>`pattern` - string. Regular expression to match against.</li><li>`result` - [`ValueMappingResult`](#valuemappingresult) |
|
||||
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
###### `SpecialValueMap`
|
||||
|
||||
Maps special values like Null, NaN (not a number), and boolean values like true and false to a display text and color.
|
||||
See `SpecialValueMatch` in the following table to see the list of special values.
|
||||
For example, you can configure a special value mapping so that null values appear as N/A.
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
|
||||
| Name | Usage |
|
||||
| ------- | ----------------------------------------------------------------------------------------------- |
|
||||
| type | `MappingType` & "special". `MappingType` options are: `value`, `range`, `regex`, and `special`. |
|
||||
| options | Spec:<ul><li>`match` - `SpecialValueMatch`. Special value to match against. Types are:<ul><li>true</li><li>false</li><li>null</li><li>nan</li><li>empty</li></ul> </li><li>`result` - [`ValueMappingResult`](#valuemappingresult) |
|
||||
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
###### `ValueMappingResult`
|
||||
|
||||
Result used as replacement with text and color when the value matches.
|
||||
|
||||
| Name | Usage |
|
||||
| ----- | ----------------------------------------------------------------------------- |
|
||||
| text | string. Text to display when the value matches. |
|
||||
| color | string. Color to use when the value matches. |
|
||||
| icon | string. Icon to display when the value matches. Only specific visualizations. |
|
||||
| index | int32. Position in the mapping array. Only used internally. |
|
||||
|
||||
###### `FieldColor`
|
||||
|
||||
Map a field to a color.
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
|
||||
| Name | Usage |
|
||||
| ----------- | -------------------------------------------------------------------- |
|
||||
| mode | [`FieldColorModeId`](#fieldcolormodeid). The main color scheme mode. |
|
||||
| FixedColor? | string. The fixed color value for fixed or shades color modes. |
|
||||
| seriesBy? | `FieldColorSeriesByMode`. Some visualizations need to know how to assign a series color from by value color schemes. Defines how to assign a series color from "by value" color schemes. For example for an aggregated data points like a timeseries, the color can be assigned by the min, max or last value. Options are: `min`, `max`, and `last`. |
|
||||
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
###### `FieldColorModeId`
|
||||
|
||||
Color mode for a field.
|
||||
You can specify a single color, or select a continuous (gradient) color schemes, based on a value.
|
||||
Continuous color interpolates a color using the percentage of a value relative to min and max.
|
||||
Accepted values are:
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
|
||||
| Name | Description |
|
||||
| --- | ---- |
|
||||
| thresholds | From thresholds. Informs Grafana to take the color from the matching threshold. |
|
||||
| palette-classic | Classic palette. Grafana will assign color by looking up a color in a palette by series index. Useful for graphs and pie charts and other categorical data visualizations. |
|
||||
| palette-classic-by-name | Classic palette (by name). Grafana will assign color by looking up a color in a palette by series name. Useful for Graphs and pie charts and other categorical data visualizations |
|
||||
| continuous-GrYlRd | Continuous Green-Yellow-Red palette mode |
|
||||
| continuous-RdYlGr | Continuous Red-Yellow-Green palette mode |
|
||||
| continuous-BlYlRd | Continuous Blue-Yellow-Red palette mode |
|
||||
| continuous-YlRd | Continuous Yellow-Red palette mode |
|
||||
| continuous-BlPu | Continuous Blue-Purple palette mode |
|
||||
| continuous-YlBl | Continuous Yellow-Blue palette mode |
|
||||
| continuous-blues | Continuous Blue palette mode |
|
||||
| continuous-reds | Continuous Red palette mode |
|
||||
| continuous-greens | Continuous Green palette mode |
|
||||
| continuous-purples | Continuous Purple palette mode |
|
||||
| shades | Shades of a single color. Specify a single color, useful in an override rule. |
|
||||
| fixed | Fixed color mode. Specify a single color, useful in an override rule. |
|
||||
|
||||
<!-- prettier-ignore-end -->
|
||||
@@ -0,0 +1,87 @@
|
||||
---
|
||||
description: A reference for the JSON timesettings schema used with Observability as Code.
|
||||
keywords:
|
||||
- configuration
|
||||
- as code
|
||||
- as-code
|
||||
- dashboards
|
||||
- git integration
|
||||
- git sync
|
||||
- github
|
||||
- time settings
|
||||
labels:
|
||||
products:
|
||||
- cloud
|
||||
- enterprise
|
||||
- oss
|
||||
menuTitle: timesettings schema
|
||||
title: timesettings
|
||||
weight: 600
|
||||
canonical: https://grafana.com/docs/grafana/latest/as-code/observability-as-code/schema-v2/timesettings-schema/
|
||||
aliases:
|
||||
- ../../../observability-as-code/schema-v2/timesettings-schema/ # /docs/grafana/next/observability-as-code/schema-v2/timesettings-schema/
|
||||
---
|
||||
|
||||
# `timeSettings`
|
||||
|
||||
The `TimeSettingsSpec` defines the default time configuration for the time picker and the refresh picker for the specific dashboard.
|
||||
|
||||
Following is the JSON for default time settings:
|
||||
|
||||
```json
|
||||
"timeSettings": {
|
||||
"autoRefresh": "",
|
||||
"autoRefreshIntervals": [
|
||||
"5s",
|
||||
"10s",
|
||||
"30s",
|
||||
"1m",
|
||||
"5m",
|
||||
"15m",
|
||||
"30m",
|
||||
"1h",
|
||||
"2h",
|
||||
"1d"
|
||||
],
|
||||
"fiscalYearStartMonth": 0,
|
||||
"from": "now-6h",
|
||||
"hideTimepicker": false,
|
||||
"timezone": "browser",
|
||||
"to": "now"
|
||||
},
|
||||
```
|
||||
|
||||
`timeSettings` consists of:
|
||||
|
||||
- [TimeSettingsSpec](#timesettingsspec)
|
||||
|
||||
## `TimeSettingsSpec`
|
||||
|
||||
The following table explains the usage of the time settings JSON fields:
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
|
||||
| Name | Usage |
|
||||
| ---- | ----- |
|
||||
| timezone? | string. Timezone of dashboard. Accepted values are IANA TZDB zone ID, `browser`, or `utc`. Default is `browser`. |
|
||||
| from | string. Start time range for dashboard. Accepted values are relative time strings like `now-6h` or absolute time strings like `2020-07-10T08:00:00.000Z`. Default is `now-6h`. |
|
||||
| to | string. End time range for dashboard. Accepted values are relative time strings like `now-6h` or absolute time strings like `2020-07-10T08:00:00.000Z`. Default is `now`. |
|
||||
| autoRefresh | string. Refresh rate of dashboard. Represented by interval string. For example: `5s`, `1m`, `1h`, `1d`. No default. In schema v1: `refresh`. |
|
||||
| autoRefreshIntervals | string. Interval options available in the refresh picker drop-down menu. The default array is `["5s", "10s", "30s", "1m", "5m", "15m", "30m", "1h", "2h", "1d"]`. |
|
||||
|quickRanges? | Selectable options available in the time picker drop-down menu. Has no effect on provisioned dashboard. Defined in the [`TimeRangeOption`](#timerangeoption) spec. In schema v1: `timepicker.quick_ranges`, not exposed in the UI. |
|
||||
| hideTimepicker | bool. Whether or not the time picker is visible. Default is `false`. In schema v1: `timepicker.hidden`. |
|
||||
| weekStart? | Day when the week starts. Expressed by the name of the day in lowercase. For example: `monday`. Options are `saturday`, `monday`, and `sunday`. |
|
||||
| fiscalYearStartMonth | The month that the fiscal year starts on. `0` = January, `11` = December |
|
||||
| nowDelay? | string. Override the "now" time by entering a time delay. Use this option to accommodate known delays in data aggregation to avoid null values. In schema v1: `timepicker.nowDelay`. |
|
||||
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
### `TimeRangeOption`
|
||||
|
||||
The following table explains the usage of the time range option JSON fields:
|
||||
|
||||
| Name | Usage |
|
||||
| ------- | ---------------------------------- |
|
||||
| display | string. Default is `Last 6 hours`. |
|
||||
| from | string. Default is `now-6h`. |
|
||||
| to | string. Default is `now`. |
|
||||
@@ -0,0 +1,501 @@
|
||||
---
|
||||
description: A reference for the JSON variables schema used with Observability as Code.
|
||||
keywords:
|
||||
- configuration
|
||||
- as code
|
||||
- as-code
|
||||
- dashboards
|
||||
- git integration
|
||||
- git sync
|
||||
- github
|
||||
- variables
|
||||
labels:
|
||||
products:
|
||||
- cloud
|
||||
- enterprise
|
||||
- oss
|
||||
menuTitle: variables schema
|
||||
title: variables
|
||||
weight: 700
|
||||
canonical: https://grafana.com/docs/grafana/latest/as-code/observability-as-code/schema-v2/variables-schema/
|
||||
aliases:
|
||||
- ../../../observability-as-code/schema-v2/variables-schema/ # /docs/grafana/next/observability-as-code/schema-v2/variables-schema/
|
||||
---
|
||||
|
||||
# `variables`
|
||||
|
||||
The available variable types described in the following sections:
|
||||
|
||||
- [QueryVariableKind](#queryvariablekind)
|
||||
- [TextVariableKind](#textvariablekind)
|
||||
- [ConstantVariableKind](#constantvariablekind)
|
||||
- [DatasourceVariableKind](#datasourcevariablekind)
|
||||
- [IntervalVariableKind](#intervalvariablekind)
|
||||
- [CustomVariableKind](#customvariablekind)
|
||||
- [SwitchVariableKind](#switchvariablekind)
|
||||
- [GroupByVariableKind](#groupbyvariablekind)
|
||||
- [AdhocVariableKind](#adhocvariablekind)
|
||||
|
||||
## `QueryVariableKind`
|
||||
|
||||
Following is the JSON for a default query variable:
|
||||
|
||||
```json
|
||||
"variables": [
|
||||
{
|
||||
"kind": "QueryVariable",
|
||||
"spec": {
|
||||
"current": {
|
||||
"text": "",
|
||||
"value": ""
|
||||
},
|
||||
"hide": "dontHide",
|
||||
"includeAll": false,
|
||||
"multi": false,
|
||||
"name": "",
|
||||
"options": [],
|
||||
"query": defaultDataQueryKind(),
|
||||
"refresh": "never",
|
||||
"regex": "",
|
||||
"skipUrlSync": false,
|
||||
"sort": "disabled"
|
||||
}
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
`QueryVariableKind` consists of:
|
||||
|
||||
- kind: "QueryVariable"
|
||||
- spec: [QueryVariableSpec](#queryvariablespec)
|
||||
|
||||
### `QueryVariableSpec`
|
||||
|
||||
The following table explains the usage of the query variable JSON fields:
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
|
||||
| Name | Usage |
|
||||
| ------------ | ---------------------------------------------- |
|
||||
| name | string. Name of the variable. |
|
||||
| current | "Text" and a "value" or [`VariableOption`](#variableoption) |
|
||||
| label? | string |
|
||||
| hide | `VariableHide`. Options are: `dontHide`, `hideLabel`, and `hideVariable`. |
|
||||
| refresh | `VariableRefresh`. Options are `never`, `onDashboardLoad`, and `onTimeChanged`. |
|
||||
| skipUrlSync | bool. Default is `false`. |
|
||||
| description? | string |
|
||||
| datasource? | [`DataSourceRef`](#datasourceref) |
|
||||
| query | `DataQueryKind`. Consists of:<ul><li>kind: string</li><li>spec: string</li></ul> |
|
||||
| regex | string |
|
||||
| sort | `VariableSort`. Options are:<ul><li>disabled</li><li>alphabeticalAsc</li><li>alphabeticalDesc</li><li>numericalAsc</li><li>numericalDesc</li><li>alphabeticalCaseInsensitiveAsc</li><li>alphabeticalCaseInsensitiveDesc</li><li>naturalAsc</li><li>naturalDesc</li></ul> |
|
||||
| definition? | string |
|
||||
| options | [`VariableOption`](#variableoption) |
|
||||
| multi | bool. Default is `false`. |
|
||||
| includeAll | bool. Default is `false`. |
|
||||
| allValue? | string |
|
||||
| placeholder? | string |
|
||||
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
#### `VariableOption`
|
||||
|
||||
| Name | Usage |
|
||||
| -------- | -------------------------------------------- |
|
||||
| selected | bool. Whether or not the option is selected. |
|
||||
| text | string. Text to be displayed for the option. |
|
||||
| value | string. Value of the option. |
|
||||
|
||||
#### `DataSourceRef`
|
||||
|
||||
| Name | Usage |
|
||||
| ----- | ---------------------------------- |
|
||||
| type? | string. The plugin type-id. |
|
||||
| uid? | The specific data source instance. |
|
||||
|
||||
## `TextVariableKind`
|
||||
|
||||
Following is the JSON for a default text variable:
|
||||
|
||||
```json
|
||||
"variables": [
|
||||
{
|
||||
"kind": "TextVariable",
|
||||
"spec": {
|
||||
"current": {
|
||||
"text": "",
|
||||
"value": ""
|
||||
},
|
||||
"hide": "dontHide",
|
||||
"name": "",
|
||||
"query": "",
|
||||
"skipUrlSync": false
|
||||
}
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
`TextVariableKind` consists of:
|
||||
|
||||
- kind: TextVariableKind
|
||||
- spec: [TextVariableSpec](#textvariablespec)
|
||||
|
||||
### `TextVariableSpec`
|
||||
|
||||
The following table explains the usage of the query variable JSON fields:
|
||||
|
||||
| Name | Usage |
|
||||
| ------------ | -------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| name | string. Name of the variable. |
|
||||
| current | "Text" and a "value" or `VariableOption`. Refer to the [`VariableOption` definition](#variableoption) under `QueryVariableKind`. |
|
||||
| query | string |
|
||||
| label? | string |
|
||||
| hide | `VariableHide`. Options are: `dontHide`, `hideLabel`, and `hideVariable`. |
|
||||
| skipUrlSync | bool. Default is `false`. |
|
||||
| description? | string |
|
||||
|
||||
## `ConstantVariableKind`
|
||||
|
||||
Following is the JSON for a default constant variable:
|
||||
|
||||
```json
|
||||
"variables": [
|
||||
{
|
||||
"kind": "ConstantVariable",
|
||||
"spec": {
|
||||
"current": {
|
||||
"text": "",
|
||||
"value": ""
|
||||
},
|
||||
"hide": "hideVariable",
|
||||
"name": "",
|
||||
"query": "",
|
||||
"skipUrlSync": true
|
||||
}
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
`ConstantVariableKind` consists of:
|
||||
|
||||
- kind: "ConstantVariable"
|
||||
- spec: [ConstantVariableSpec](#constantvariablespec)
|
||||
|
||||
### `ConstantVariableSpec`
|
||||
|
||||
The following table explains the usage of the constant variable JSON fields:
|
||||
|
||||
| Name | Usage |
|
||||
| ------------ | -------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| name | string. Name of the variable. |
|
||||
| query | string |
|
||||
| current | "Text" and a "value" or `VariableOption`. Refer to the [`VariableOption` definition](#variableoption) under `QueryVariableKind`. |
|
||||
| label? | string |
|
||||
| hide | `VariableHide`. Options are: `dontHide`, `hideLabel`, and `hideVariable`. |
|
||||
| skipUrlSync | bool. Default is `false`. |
|
||||
| description? | string |
|
||||
|
||||
## `DatasourceVariableKind`
|
||||
|
||||
Following is the JSON for a default data source variable:
|
||||
|
||||
```json
|
||||
"variables": [
|
||||
{
|
||||
"kind": "DatasourceVariable",
|
||||
"spec": {
|
||||
"current": {
|
||||
"text": "",
|
||||
"value": ""
|
||||
},
|
||||
"hide": "dontHide",
|
||||
"includeAll": false,
|
||||
"multi": false,
|
||||
"name": "",
|
||||
"options": [],
|
||||
"pluginId": "",
|
||||
"refresh": "never",
|
||||
"regex": "",
|
||||
"skipUrlSync": false
|
||||
}
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
`DatasourceVariableKind` consists of:
|
||||
|
||||
- kind: "DatasourceVariable"
|
||||
- spec: [DatasourceVariableSpec](#datasourcevariablespec)
|
||||
|
||||
### `DatasourceVariableSpec`
|
||||
|
||||
The following table explains the usage of the data source variable JSON fields:
|
||||
|
||||
| Name | Usage |
|
||||
| ------------ | -------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| name | string. Name of the variable. |
|
||||
| pluginId | string |
|
||||
| refresh | `VariableRefresh`. Options are `never`, `onDashboardLoad`, and `onTimeChanged`. |
|
||||
| regex | string |
|
||||
| current | `Text` and a `value` or `VariableOption`. Refer to the [`VariableOption` definition](#variableoption) under `QueryVariableKind`. |
|
||||
| options | `VariableOption`. Refer to the [`VariableOption` definition](#variableoption) under `QueryVariableKind`. |
|
||||
| multi | bool. Default is `false`. |
|
||||
| includeAll | bool. Default is `false`. |
|
||||
| allValue? | string |
|
||||
| label? | string |
|
||||
| hide | `VariableHide`. Options are: `dontHide`, `hideLabel`, and `hideVariable`. |
|
||||
| skipUrlSync | bool. Default is `false`. |
|
||||
| description? | string |
|
||||
|
||||
## `IntervalVariableKind`
|
||||
|
||||
Following is the JSON for a default interval variable:
|
||||
|
||||
```json
|
||||
"variables": [
|
||||
{
|
||||
"kind": "IntervalVariable",
|
||||
"spec": {
|
||||
"auto": false,
|
||||
"auto_count": 0,
|
||||
"auto_min": "",
|
||||
"current": {
|
||||
"text": "",
|
||||
"value": ""
|
||||
},
|
||||
"hide": "dontHide",
|
||||
"name": "",
|
||||
"options": [],
|
||||
"query": "",
|
||||
"refresh": "never",
|
||||
"skipUrlSync": false
|
||||
}
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
`IntervalVariableKind` consists of:
|
||||
|
||||
- kind: "IntervalVariable"
|
||||
- spec: [IntervalVariableSpec](#intervalvariablespec)
|
||||
|
||||
### `IntervalVariableSpec`
|
||||
|
||||
The following table explains the usage of the interval variable JSON fields:
|
||||
|
||||
| Name | Usage |
|
||||
| ------------ | -------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| name | string. Name of the variable. |
|
||||
| query | string |
|
||||
| current | `Text` and a `value` or `VariableOption`. Refer to the [`VariableOption` definition](#variableoption) under `QueryVariableKind`. |
|
||||
| options | `VariableOption`. Refer to the [`VariableOption` definition](#variableoption) under `QueryVariableKind`. |
|
||||
| auto | bool. Default is `false`. |
|
||||
| auto_count | integer. Default is `0`. |
|
||||
| refresh | `VariableRefresh`. Options are `never`, `onDashboardLoad`, and `onTimeChanged`. |
|
||||
| label? | string |
|
||||
| hide | `VariableHide`. Options are: `dontHide`, `hideLabel`, and `hideVariable`. |
|
||||
| skipUrlSync | bool. Default is `false` |
|
||||
| description? | string |
|
||||
|
||||
## `CustomVariableKind`
|
||||
|
||||
Following is the JSON for a default custom variable:
|
||||
|
||||
```json
|
||||
"variables": [
|
||||
{
|
||||
"kind": "CustomVariable",
|
||||
"spec": {
|
||||
"current": defaultVariableOption(),
|
||||
"hide": "dontHide",
|
||||
"includeAll": false,
|
||||
"multi": false,
|
||||
"name": "",
|
||||
"options": [],
|
||||
"query": "",
|
||||
"skipUrlSync": false
|
||||
}
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
`CustomVariableKind` consists of:
|
||||
|
||||
- kind: "CustomVariable"
|
||||
- spec: [CustomVariableSpec](#customvariablespec)
|
||||
|
||||
### `CustomVariableSpec`
|
||||
|
||||
The following table explains the usage of the custom variable JSON fields:
|
||||
|
||||
| Name | Usage |
|
||||
| ------------ | -------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| name | string. Name of the variable. |
|
||||
| query | string |
|
||||
| current | `Text` and a `value` or `VariableOption`. Refer to the [`VariableOption` definition](#variableoption) under `QueryVariableKind`. |
|
||||
| options | `VariableOption`. Refer to the [`VariableOption` definition](#variableoption) under `QueryVariableKind`. |
|
||||
| multi | bool. Default is `false`. |
|
||||
| includeAll | bool. Default is `false`. |
|
||||
| allValue? | string |
|
||||
| label? | string |
|
||||
| hide | `VariableHide`. Options are: `dontHide`, `hideLabel`, and `hideVariable`. |
|
||||
| skipUrlSync | bool. Default is `false`. |
|
||||
| description? | string |
|
||||
|
||||
## `SwitchVariableKind`
|
||||
|
||||
Following is the JSON for a default switch variable:
|
||||
|
||||
```json
|
||||
"variables": [
|
||||
{
|
||||
"kind": "SwitchVariable",
|
||||
"spec": {
|
||||
"current": "false",
|
||||
"enabledValue": "true",
|
||||
"disabledValue": "false",
|
||||
"hide": "dontHide",
|
||||
"name": "",
|
||||
"skipUrlSync": false
|
||||
}
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
`SwitchVariableKind` consists of:
|
||||
|
||||
- kind: "SwitchVariable"
|
||||
- spec: [SwitchVariableSpec](#switchvariablespec)
|
||||
|
||||
### `SwitchVariableSpec`
|
||||
|
||||
The following table explains the usage of the switch variable JSON fields:
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
|
||||
| Name | Usage |
|
||||
| -------------- | -------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| name | string. Name of the variable. |
|
||||
| current | string. Current value of the switch variable (either `enabledValue` or `disabledValue`). |
|
||||
| enabledValue | string. Value when the switch is in the enabled state. |
|
||||
| disabledValue | string. Value when the switch is in the disabled state. |
|
||||
| label? | string |
|
||||
| hide | `VariableHide`. Options are: `dontHide`, `hideLabel`, and `hideVariable`. |
|
||||
| skipUrlSync | bool. Default is `false`. |
|
||||
| description? | string |
|
||||
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
## `GroupByVariableKind`
|
||||
|
||||
Following is the JSON for a default group by variable:
|
||||
|
||||
```json
|
||||
"variables": [
|
||||
{
|
||||
"kind": "GroupByVariable",
|
||||
"spec": {
|
||||
"current": {
|
||||
"text": [
|
||||
""
|
||||
],
|
||||
"value": [
|
||||
""
|
||||
]
|
||||
},
|
||||
"datasource": {},
|
||||
"hide": "dontHide",
|
||||
"multi": false,
|
||||
"name": "",
|
||||
"options": [],
|
||||
"skipUrlSync": false
|
||||
}
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
`GroupByVariableKind` consists of:
|
||||
|
||||
- kind: "GroupByVariable"
|
||||
- spec: [GroupByVariableSpec](#groupbyvariablespec)
|
||||
|
||||
### `GroupByVariableSpec`
|
||||
|
||||
The following table explains the usage of the group by variable JSON fields:
|
||||
|
||||
| Name | Usage |
|
||||
| ------------ | -------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| name | string. Name of the variable |
|
||||
| datasource? | `DataSourceRef`. Refer to the [`DataSourceRef` definition](#datasourceref) under `QueryVariableKind`. |
|
||||
| current | `Text` and a `value` or `VariableOption`. Refer to the [`VariableOption` definition](#variableoption) under `QueryVariableKind`. |
|
||||
| options | `VariableOption`. Refer to the [`VariableOption` definition](#variableoption) under `QueryVariableKind`. |
|
||||
| multi | bool. Default is `false`. |
|
||||
| label? | string |
|
||||
| hide | `VariableHide`. Options are: `dontHide`, `hideLabel`, and `hideVariable`. |
|
||||
| skipUrlSync | bool. Default is `false`. |
|
||||
| description? | string. |
|
||||
|
||||
## `AdhocVariableKind`
|
||||
|
||||
Following is the JSON for a default ad hoc variable:
|
||||
|
||||
```json
|
||||
"variables": [
|
||||
{
|
||||
"kind": "AdhocVariable",
|
||||
"spec": {
|
||||
"baseFilters": [],
|
||||
"defaultKeys": [],
|
||||
"filters": [],
|
||||
"hide": "dontHide",
|
||||
"name": "",
|
||||
"skipUrlSync": false
|
||||
}
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
`AdhocVariableKind` consists of:
|
||||
|
||||
- kind: "AdhocVariable"
|
||||
- spec: [AdhocVariableSpec](#adhocvariablespec)
|
||||
|
||||
### `AdhocVariableSpec`
|
||||
|
||||
The following table explains the usage of the ad hoc variable JSON fields:
|
||||
|
||||
| Name | Usage |
|
||||
| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| name | string. Name of the variable. |
|
||||
| datasource? | `DataSourceRef`. Consists of:<ul><li>type? - string. The plugin type-id.</li><li>uid? - string. The specific data source instance.</li></ul> |
|
||||
| baseFilters | [AdHocFilterWithLabels](#adhocfilterswithlabels) |
|
||||
| filters | [AdHocFilterWithLabels](#adhocfilterswithlabels) |
|
||||
| defaultKeys | [MetricFindValue](#metricfindvalue) |
|
||||
| label? | string |
|
||||
| hide | `VariableHide`. Options are: `dontHide`, `hideLabel`, and `hideVariable`. |
|
||||
| skipUrlSync | bool. Default is `false`. |
|
||||
| description? | string |
|
||||
|
||||
#### `AdHocFiltersWithLabels`
|
||||
|
||||
The following table explains the usage of the ad hoc variable with labels JSON fields:
|
||||
|
||||
| Name | Type |
|
||||
| ------------ | ------------- |
|
||||
| key | string |
|
||||
| operator | string |
|
||||
| value | string |
|
||||
| values? | `[...string]` |
|
||||
| keyLabel | string |
|
||||
| valueLabels? | `[...string]` |
|
||||
| forceEdit? | bool |
|
||||
|
||||
#### `MetricFindValue`
|
||||
|
||||
The following table explains the usage of the metric find value JSON fields:
|
||||
|
||||
| Name | Type |
|
||||
| ----------- | ---------------- |
|
||||
| text | string |
|
||||
| value? | string or number |
|
||||
| group? | string |
|
||||
| expandable? | bool |
|
||||
Reference in New Issue
Block a user