README
¶
Grabana
Grabana provides a developer-friendly way of creating Grafana dashboards.
Whether you prefer writing code or YAML, 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
Dashboard as code
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.FindOrCreateFolder(ctx, "Test Folder")
if err != nil {
fmt.Printf("Could not find or create folder: %s\n", err)
os.Exit(1)
}
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.
Dashboard as YAML
Dashboard configuration:
# dashboard.yaml
title: Awesome dashboard
editable: true
tags: [generated]
auto_refresh: 5s
variables:
- interval:
name: interval
label: Interval
values: ["30s", "1m", "5m", "10m", "30m", "1h", "6h", "12h"]
rows:
- name: Prometheus
panels:
- graph:
title: HTTP Rate
height: 400px
datasource: prometheus-default
targets:
- prometheus:
query: "rate(promhttp_metric_handler_requests_total[$interval])"
legend: "{{handler}} - {{ code }}"
Dashboard creation:
content, err := ioutil.ReadFile("dashboard.yaml")
if err != nil {
fmt.Fprintf(os.Stderr, "Could not read file: %s\n", err)
os.Exit(1)
}
dashboard, err := decoder.UnmarshalYAML(bytes.NewBuffer(content))
if err != nil {
fmt.Fprintf(os.Stderr, "Could not parse file: %s\n", err)
os.Exit(1)
}
ctx := context.Background()
client := grabana.NewClient(&http.Client{}, grafanaHost, grafanaAPIToken)
// create the folder holding the dashboard for the service
folder, err := client.FindOrCreateFolder(ctx, "Test Folder")
if err != nil {
fmt.Printf("Could not find or create folder: %s\n", err)
os.Exit(1)
}
if _, err := client.UpsertDashboard(ctx, folder, builder); err != nil {
fmt.Printf("Could not create dashboard: %s\n", err)
os.Exit(1)
}
Going further
Check out the documentation to discover what Grabana can do for you.
License
This library is under the MIT license.
Documentation
¶
Overview ¶
Package grabana provides a developer-friendly way of creating Grafana dashboards.
Whether you prefer writing **code or YAML**, 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",
dashboard.VariableAsInterval(
"interval",
interval.Values([]string{"30s", "1m", "5m", "10m", "30m", "1h", "6h", "12h"}),
),
dashboard.VariableAsQuery(
"status",
query.DataSource("prometheus-default"),
query.Request("label_values(prometheus_http_requests_total, code)"),
query.Sort(query.NumericalAsc),
),
dashboard.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"),
),
),
dashboard.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 (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
Constants ¶
This section is empty.
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.
Functions ¶
This section is empty.
Types ¶
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client represents a Grafana HTTP client.
func (*Client) CreateFolder ¶
CreateFolder creates a dashboard folder. See https://grafana.com/docs/grafana/latest/reference/dashboard_folders/
func (*Client) DeleteDashboard ¶ added in v0.5.2
DeleteDashboard deletes a dashboard given its UID.
func (*Client) FindOrCreateFolder ¶ added in v0.5.3
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 ¶
GetFolderByTitle finds a folder, given its title.
Source Files
Directories