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:

builder := dashboard.New(
    "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{}, grafanaHost, grafanaAPIToken)

// 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, builder); 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

Overview

Package 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.

builder := dashboard.New(
	"Awesome dashboard",
	grabana.VariableAsInterval(
		"interval",
		interval.Values([]string{"30s", "1m", "5m", "10m", "30m", "1h", "6h", "12h"}),
	),
	grabana.VariableAsQuery(
		"status",
		query.DataSource("prometheus-default"),
		query.Request("label_values(prometheus_http_requests_total, code)"),
		query.Sort(query.NumericalAsc),
	),
	grabana.Row(
		"Prometheus",
		row.WithGraph(
			"HTTP Rate",
			graph.WithPrometheusTarget(
				"rate(promhttp_metric_handler_requests_total[$interval])",
				prometheus.Legend("{{handler}} - {{ code }}"),
			),
		),
		row.WithTable(
			"Threads",
			table.WithPrometheusTarget("go_threads"),
			table.HideColumn("Time"),
			table.AsTimeSeriesAggregations([]table.Aggregation{
				{Label: "AVG", Type: table.AVG},
				{Label: "Current", Type: table.Current},
			}),
		),
		row.WithSingleStat(
			"Heap Allocations",
			singlestat.Unit("bytes"),
			singlestat.WithPrometheusTarget("go_memstats_heap_alloc_bytes"),
		),
	),
	grabana.Row(
		"Some text, because it might be useful",
		row.WithText(
			"Some awesome html?",
			text.HTML("<b>lalalala</b>"),
		),
	),
)

For a more information visit https://github.com/K-Phoen/grabana

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) DeleteDashboard(ctx context.Context, uid string) error
  • func (client *Client) FindOrCreateFolder(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 dashboard.Builder) (*Dashboard, error)
• type Dashboard
• type Folder

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

func (client *Client) DeleteDashboard(ctx context.Context, uid string) error

DeleteDashboard deletes a dashboard given its UID.

func (*Client) FindOrCreateFolder

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

FindOrCreateFolder returns the folder by its name or creates it if it doesn't exist.

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 dashboard.Builder) (*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 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/