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

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

Types

type Client

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

func NewClient

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

func (*Client) CreateFolder

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

func (*Client) GetAlertChannelByName

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

func (*Client) GetFolderByTitle

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

func (*Client) UpsertDashboard

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

type Dashboard

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

type DashboardBuilder

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

func NewDashboardBuilder

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

type DashboardBuilderOption

type DashboardBuilderOption func(dashboard *DashboardBuilder)

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 graph as editable.

func ReadOnly

func ReadOnly() DashboardBuilderOption

ReadOnly marks the graph 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"`
}

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