grabana

README

Grabana

Grabana provides a developer-friendly way of creating Grafana dashboards.

If you are looking for a way to version your dashboards configuration or automate tedious and error-prone creation of dashboards, this library is meant for you.

Design goals

• provide an understandable abstraction over dashboards configuration
• expose a developer-friendly API
• allow IDE assistance and auto-completion

Example

Dashboard configuration:

dashboard := grabana.NewDashboardBuilder(
    "Awesome dashboard",
    grabana.AutoRefresh("5s"),
    grabana.Tags([]string{"generated"}),
    grabana.VariableAsInterval(
        "interval",
        interval.Values([]string{"30s", "1m", "5m", "10m", "30m", "1h", "6h", "12h"}),
    ),
    grabana.Row(
        "Prometheus",
        row.WithGraph(
            "HTTP Rate",
            graph.DataSource("prometheus-default"),
            graph.WithPrometheusTarget(
                "rate(prometheus_http_requests_total[30s])",
                prometheus.Legend("{{handler}} - {{ code }}"),
            ),
        ),
    ),
)

Dashboard creation:

ctx := context.Background()
client := grabana.NewClient(&http.Client{}, os.Args[1], os.Args[2])

// create the folder holding the dashboard for the service
folder, err := client.GetFolderByTitle(ctx, "Test Folder")
if err != nil && err != grabana.ErrFolderNotFound {
    fmt.Printf("Could not create folder: %s\n", err)
    os.Exit(1)
}
if folder == nil {
    folder, err = client.CreateFolder(ctx, "Test Folder")
    if err != nil {
        fmt.Printf("Could not create folder: %s\n", err)
        os.Exit(1)
    }

    fmt.Printf("Folder created (id: %d, uid: %s)\n", folder.ID, folder.UID)
}

if _, err := client.UpsertDashboard(ctx, folder, dashboard); err != nil {
    fmt.Printf("Could not create dashboard: %s\n", err)
    os.Exit(1)
}

For a more complete example, see the example directory.

License

This library is under the MIT license.

Documentation

Index

• Variables
• type Client
  • func NewClient(http *http.Client, host string, apiToken string) *Client
  • func (client *Client) CreateFolder(ctx context.Context, name string) (*Folder, error)
  • func (client *Client) GetAlertChannelByName(ctx context.Context, name string) (*alert.Channel, error)
  • func (client *Client) GetFolderByTitle(ctx context.Context, title string) (*Folder, error)
  • func (client *Client) UpsertDashboard(ctx context.Context, folder *Folder, builder DashboardBuilder) (*Dashboard, error)
• type Dashboard
• type DashboardBuilder
  • func NewDashboardBuilder(title string, options ...DashboardBuilderOption) DashboardBuilder
• type DashboardBuilderOption
  • func AutoRefresh(interval string) DashboardBuilderOption
  • func DefaultTooltip() DashboardBuilderOption
  • func Editable() DashboardBuilderOption
  • func ReadOnly() DashboardBuilderOption
  • func Row(title string, options ...row.Option) DashboardBuilderOption
  • func SharedCrossHair() DashboardBuilderOption
  • func Tags(tags []string) DashboardBuilderOption
  • func TagsAnnotation(annotation TagAnnotation) DashboardBuilderOption
  • func VariableAsConst(name string, options ...constant.Option) DashboardBuilderOption
  • func VariableAsCustom(name string, options ...custom.Option) DashboardBuilderOption
  • func VariableAsInterval(name string, options ...interval.Option) DashboardBuilderOption
  • func VariableAsQuery(name string, options ...query.Option) DashboardBuilderOption
• type Folder
• type TagAnnotation

Variables

var ErrAlertChannelNotFound = errors.New("alert channel not found")

ErrAlertChannelNotFound is returned when the given alert notification channel can not be found.

var ErrFolderNotFound = errors.New("folder not found")

ErrFolderNotFound is returned when the given folder can not be found.

Types

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client represents a Grafana HTTP client.

func NewClient

func NewClient(http *http.Client, host string, apiToken string) *Client

NewClient creates a new Grafana HTTP client.

func (*Client) CreateFolder

func (client *Client) CreateFolder(ctx context.Context, name string) (*Folder, error)

CreateFolder creates a dashboard folder. See https://grafana.com/docs/grafana/latest/reference/dashboard_folders/

func (*Client) GetAlertChannelByName

func (client *Client) GetAlertChannelByName(ctx context.Context, name string) (*alert.Channel, error)

GetAlertChannelByName finds an alert notification channel, given its name.

func (*Client) GetFolderByTitle

func (client *Client) GetFolderByTitle(ctx context.Context, title string) (*Folder, error)

GetFolderByTitle finds a folder, given its title.

func (*Client) UpsertDashboard

func (client *Client) UpsertDashboard(ctx context.Context, folder *Folder, builder DashboardBuilder) (*Dashboard, error)

UpsertDashboard creates or replaces a dashboard, in the given folder.

type Dashboard

type Dashboard struct {
	ID  uint   `json:"id"`
	UID string `json:"uid"`
	URL string `json:"url"`
}

Dashboard represents a Grafana dashboard.

type DashboardBuilder

type DashboardBuilder struct {
	// contains filtered or unexported fields
}

DashboardBuilder is the main builder used to configure dashboards.

func NewDashboardBuilder

func NewDashboardBuilder(title string, options ...DashboardBuilderOption) DashboardBuilder

NewDashboardBuilder creates a new dashboard builder.

type DashboardBuilderOption

type DashboardBuilderOption func(dashboard *DashboardBuilder)

DashboardBuilderOption represents an option that can be used to configure a dashboard.

func AutoRefresh

func AutoRefresh(interval string) DashboardBuilderOption

AutoRefresh defines the auto-refresh interval for the dashboard.

func DefaultTooltip

func DefaultTooltip() DashboardBuilderOption

DefaultTooltip configures the graph tooltip NOT to be shared across panels.

func Editable

func Editable() DashboardBuilderOption

Editable marks the dashboard as editable.

func ReadOnly

func ReadOnly() DashboardBuilderOption

ReadOnly marks the dashboard as non-editable.

func Row

func Row(title string, options ...row.Option) DashboardBuilderOption

Row adds a row to the dashboard.

func SharedCrossHair

func SharedCrossHair() DashboardBuilderOption

SharedCrossHair configures the graph tooltip to be shared across panels.

func Tags

func Tags(tags []string) DashboardBuilderOption

Tags adds the given set of tags to the dashboard.

func TagsAnnotation

func TagsAnnotation(annotation TagAnnotation) DashboardBuilderOption

TagsAnnotation adds a new source of annotation for the dashboard.

func VariableAsConst

func VariableAsConst(name string, options ...constant.Option) DashboardBuilderOption

VariableAsConst adds a templated variable, defined as a set of constant values. See https://grafana.com/docs/grafana/latest/reference/templating/#variable-types

func VariableAsCustom

func VariableAsCustom(name string, options ...custom.Option) DashboardBuilderOption

VariableAsCustom adds a templated variable, defined as a set of custom values. See https://grafana.com/docs/grafana/latest/reference/templating/#variable-types

func VariableAsInterval

func VariableAsInterval(name string, options ...interval.Option) DashboardBuilderOption

VariableAsInterval adds a templated variable, defined as an interval. See https://grafana.com/docs/grafana/latest/reference/templating/#variable-types

func VariableAsQuery

func VariableAsQuery(name string, options ...query.Option) DashboardBuilderOption

VariableAsQuery adds a templated variable, defined as a query. See https://grafana.com/docs/grafana/latest/reference/templating/#variable-types

type Folder

type Folder struct {
	ID    uint   `json:"id"`
	UID   string `json:"uid"`
	Title string `json:"title"`
}

Folder represents a dashboard folder. See https://grafana.com/docs/grafana/latest/reference/dashboard_folders/

type TagAnnotation

type TagAnnotation struct {
	Name       string
	Datasource string
	IconColor  string
	Tags       []string
}

TagAnnotation describes an annotation represented as a Tag. See https://grafana.com/docs/grafana/latest/reference/annotations/#query-by-tag