observability-lib

README

Observability-lib

This library enables creating Grafana dashboards and alerts with go code.

It provides abstractions to create grafana resources :

• Dashboards
• Alerts
• Contact Points
• Notification Policies
• Notification Templates

Folder Structure

The observability-lib is structured as follows:

observability-lib/
    api/ # Grafana HTTP API Client to interact with resources
    cmd/ # CLI to interact deploy or generateJSON from dashboards defined in folder below
    dashboards/ # Dashboards definitions
    grafana/ # grafana-foundations-sdk abstraction to manipulate grafana resources

Documentation

Godoc generated documentation is available here

Quickstart

Creating a dashboard

main.go

package main

import "github.com/goplugin/plugin-common/observability-lib/grafana"

func main() {
	builder := grafana.NewBuilder(&grafana.BuilderOptions{
	    Name:       "Dashboard Name",
	    Tags:       []string{"tags1", "tags2"},
	    Refresh:    "30s",
	    TimeFrom:   "now-30m",
	    TimeTo:     "now",
	})
	
	builder.AddVars(grafana.NewQueryVariable(&grafana.QueryVariableOptions{
	    VariableOption: &grafana.VariableOption{
	        Label: "Environment",
	        Name:  "env",
	    },
	    Datasource: "Prometheus",
	    Query:      `label_values(up, env)`,
	}))
	
	builder.AddRow("Summary")
	
	builder.AddPanel(grafana.NewStatPanel(&grafana.StatPanelOptions{
	    PanelOptions: &grafana.PanelOptions{
	        Datasource:  "Prometheus",
	        Title:       "Uptime",
	        Description: "instance uptime",
	        Span:        12,
	        Height:      4,
	        Decimals:    2,
	        Unit:        "s",
	        Query: []grafana.Query{
	            {
	                Expr:   `uptime_seconds`,
	                Legend: `{{ pod }}`,
	            },
	        },
	    },
	    ColorMode:   common.BigValueColorModeNone,
	    TextMode:    common.BigValueTextModeValueAndName,
	    Orientation: common.VizOrientationHorizontal,
	}))
	
	db, err := builder.Build()
	if err != nil {
	    return nil, err
	}
	json, err := db.GenerateJSON()
	if err != nil {
	    return nil, err
	}
	fmt.Println(string(json))
}

More advanced examples can be found in the dashboards folder :

• DON OCR
• Capabilities
• Node General
• Node Components
• Kubernetes Resources
• NOP OCR Health

Cmd Usage

The CLI can be used to :

• Deploy dashboards and alerts to grafana
• Generate JSON from dashboards defined in the dashboards folder

func NewDashboard(props *Props) in each dashboards packages is called from cmd to deploy or generate JSON from the dashboard.

Example to deploy a dashboard to grafana instance using URL and token:

make build
./observability-lib deploy \
  --dashboard-name DashboardName \
  --dashboard-folder FolderName \
  --grafana-url $GRAFANA_URL \
  --grafana-token $GRAFANA_TOKEN \
  --type core-node \
  --platform kubernetes \
  --metrics-datasource Prometheus

To see how to get a grafana token you can check this page

Example to generate JSON from a dashboard defined in the dashboards folder:

make build
./observability-lib generate \
  --dashboard-name DashboardName \
  --type core-node-components \
  --platform kubernetes

Makefile Usage

To build the observability library, run the following command:

make build

To run the tests, run the following command:

make test

To run the linter, run the following command:

make lint

To run the CLI

make run