Merge pull request #50 from K-Phoen/docs

Docs

.alexrc

@@ -0,0 +1,3 @@
+{
+  "allow": ["color"]
+}

.github/workflows/ci.yaml

@@ -17,6 +17,28 @@ jobs:
           golangci_lint_flags: "--config=.golangci.yaml"
           reporter: github-pr-review
 
+  doc:
+    name: Documentation
+    runs-on: ubuntu-18.04
+
+    steps:
+      - uses: actions/checkout@v2
+        with:
+          depth: 1
+
+      - uses: nosborn/github-action-markdown-cli@master
+        with:
+          files: ./content/
+
+      - uses: K-Phoen/action-misspell@master
+        with:
+          github_token: ${{ github.token }}
+          reporter: github-pr-review
+          locale: "US"
+
+      - name: alexjs
+        uses: theashraf/alex-action@master
+
   tests:
     name: Tests
     runs-on: ubuntu-18.04

.markdownlint.json

@@ -0,0 +1,8 @@
+{
+  "default": true,
+  "no-inline-html": false,
+  "no-hard-tabs": false,
+  "no-trailing-punctuation": false,
+  "no-bare-urls": false,
+  "line-length": false
+}

README.md

@@ -4,17 +4,17 @@
 
 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.
+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
 
-## Example
+## Dashboard as code
 
 Dashboard configuration:
 
@@ -48,20 +48,11 @@ 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)
+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 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)
@@ -71,6 +62,74 @@ if _, err := client.UpsertDashboard(ctx, folder, builder); err != nil {
 
 For a more complete example, see the [`example`](./cmd/example/) directory.
 
+## Dashboard as YAML
+
+Dashboard configuration:
+
+```yaml
+# 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:
+
+```go
+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](doc/index.md) to discover what Grabana can do for
+you.
+
+
 ## License
 
 This library is under the [MIT](LICENSE) license.

decoder/graph.go

@@ -175,11 +175,11 @@ func (a graphAlert) toOptions() ([]alert.Option, error) {
 }
 
 type alertThreshold struct {
-	HasNoValue   bool
+	HasNoValue   bool `yaml:"has_no_value"`
 	Above        *float64
 	Below        *float64
-	OutsideRange [2]float64
-	WithinRange  [2]float64
+	OutsideRange [2]float64 `yaml:"outside_range"`
+	WithinRange  [2]float64 `yaml:"within_range"`
 }
 
 func (threshold alertThreshold) toOption() (alert.ConditionOption, error) {

doc/annotations_yaml.md

@@ -0,0 +1,19 @@
+# Annotations
+
+> Annotations provide a way to mark points on the graph with rich events. When
+> you hover over an annotation you can get event description and event tags.
+> The text field can include links to other systems with more detail.
+>
+> — https://grafana.com/docs/grafana/latest/reference/annotations/
+
+```yaml
+tags_annotations:
+  - name: Deployments
+    datasource: "-- Grafana --"
+    color: "#5794F2"
+    tags: ["deploy", "production"]
+```
+
+## That was it!
+
+[Return to the index to explore the other possibilities of the module](index.md)

doc/dashboard_options_yaml.md

@@ -0,0 +1,15 @@
+# Dashboard options
+
+Generic options describing the dashboard's behavior.
+
+```yaml
+title: Awesome dashboard
+editable: true
+shared_crosshair: true
+tags: [generated, yaml]
+auto_refresh: 10s
+```
+
+## That was it!
+
+[Return to the index to explore the other possibilities of the module](index.md)

doc/graph_panels_yaml.md

@@ -0,0 +1,59 @@
+# Graph panels
+
+> The main panel in Grafana is named Graph. It provides a very rich set of
+> graphing options.
+>
+> — https://grafana.com/docs/grafana/latest/features/panels/graph/
+
+```yaml
+rows:
+  - name: "Graph panels row"
+    panels:
+      - graph:
+        title: HTTP Rate
+        height: 400px
+        span: 16
+        datasource: prometheus-default
+        targets:
+          - prometheus:
+              query: "rate(promhttp_metric_handler_requests_total[$interval])"
+              legend: "{{handler}} - {{ code }}"
+        axes:
+          left: { unit: short, min: 0, label: Requests }
+          right: { hidden: true }
+
+      - graph:
+        title: Heap allocations
+        height: 400px
+        span: 16
+        datasource: prometheus-default
+        targets:
+          - prometheus:
+              query: "go_memstats_heap_alloc_bytes"
+              legend: "{{job}}"
+              ref: A
+        alert:
+          title: Too many heap allocations
+          evaluate_every: 1m
+          for: 1m
+          # ID of the notification channel
+          notify: 1
+          message: "Wow, a we're allocating a lot."
+          # Valid values are: no_data, alerting, keep_state, ok
+          on_no_data: alerting
+          # Valid values are: alerting, keep_state
+          on_execution_error: alerting
+          if:
+            - operand: and
+              # valid `func` values are: avg, sum, count, last, min, max, median, diff, percent_diff
+              value: {func: avg, ref: A, from: 1m, to: now}
+              threshold: {above: 23000000}
+              # threshold: {has_no_value: true}
+              # threshold: {below: 23000000}
+              # threshold: {outside_range: [23000000, 26000000]}
+              # threshold: {within_range: [23000000, 26000000]}
+```
+
+## That was it!
+
+[Return to the index to explore the other possibilities of the module](index.md)

doc/index.md

@@ -0,0 +1,18 @@
+# Getting started with Grabana
+
+## Dashboards as code
+
+* [Example](../cmd/example/)
+* [GoDoc](https://pkg.go.dev/github.com/K-Phoen/grabana?tab=doc)
+
+## Dashboards as YAML
+
+* [Unmarshalling a YAML file](unmarshalling_yaml.md)
+* [Realistic example](../cmd/yaml/example.yaml)
+* [Dashboard options](dashboard_options_yaml.md)
+* [Variables](variables_yaml.md)
+* [Annotations](annotations_yaml.md)
+* [Text panels](text_panels_yaml.md)
+* [Table panels](table_panels_yaml.md)
+* [Graph panels](graph_panels_yaml.md)
+* [Singlestat panels](singlestat_panels_yaml.md)

doc/singlestat_panels_yaml.md

@@ -0,0 +1,33 @@
+# Singlestat panels
+
+> The Singlestat Panel allows you to show the one main summary stat of a SINGLE
+> series. It reduces the series into a single number (by looking at the max,
+> min, average, or sum of values in the series). Singlestat also provides
+> thresholds to color the stat or the Panel background. It can also translate
+> the single number into a text value, and show a sparkline summary of the series.
+>
+> — https://grafana.com/docs/grafana/latest/features/panels/singlestat/
+
+```yaml
+rows:
+  - name: "Graph panels row"
+    panels:
+      - single_stat:
+          title: Heap Allocations
+          span: 12
+          height: 400px
+          datasource: prometheus-default
+          targets:
+            - prometheus:
+                query: 'go_memstats_heap_alloc_bytes{job="prometheus"}'
+          unit: bytes
+          thresholds: ["26000000", "28000000"]
+          # valie values are: value, background
+          color: ["value"]
+          # valid values are: bottom, full
+          sparkline: bottom
+```
+
+## That was it!
+
+[Return to the index to explore the other possibilities of the module](index.md)

doc/table_panels_yaml.md

@@ -0,0 +1,33 @@
+# Table panels
+
+> The table panel is very flexible, supporting both multiple modes for time
+> series as well as for table, annotation and raw JSON data. It also provides
+> date formatting and value formatting and coloring options.
+>
+> — https://grafana.com/docs/grafana/latest/features/panels/table_panel/
+
+```yaml
+rows:
+  - name: "Table panels row"
+    panels:
+      - table:
+        title: Threads
+        span: 12
+        height: 400px
+        datasource: prometheus-default
+        targets:
+          - prometheus:
+              query: "go_threads"
+        # hides the column having a label matching the given pattern.
+        hidden_columns: ["Time"]
+        time_series_aggregations:
+          - label: AVG
+            # valid types are: avg, count, current, min, max
+            type: avg
+          - label: Current
+            type: current
+```
+
+## That was it!
+
+[Return to the index to explore the other possibilities of the module](index.md)

doc/text_panels_yaml.md

@@ -0,0 +1,27 @@
+# Text panels
+
+> The text panel lets you make information and description panels etc. for your
+> dashboards.
+>
+> — https://grafana.com/docs/grafana/latest/features/panels/text/
+
+```yaml
+rows:
+  - name: "Text panels row"
+    panels:
+      - text:
+          title: Some awesome text?
+          span: 6
+          height: 400px
+          markdown: "Markdown syntax help: [commonmark.org/help](https://commonmark.org/help/)\n${percentile}"
+
+      - text:
+          title: Some awesome html?
+          span: 3
+          height: 200px
+          html: "Some <b>awesome</b> html?"
+```
+
+## That was it!
+
+[Return to the index to explore the other possibilities of the module](index.md)