Getting Started

This guide will help you get started with dash. Detailed instructions on how to create datasource and dashboards or how to use the explore mode can be found in the wiki.

Installation

The dash binaries are available at the releases page for macOS, Linux and Windows. You can download the binary for your operating system and directly run it. You can also follow below steps to download dash and place it in your PATH.

VERSION=1.0.0
GOOS=$(go env GOOS)
GOARCH=$(go env GOARCH)
wget https://github.com/ricoberger/dash/releases/download/$VERSION/dash-$GOOS-$GOARCH
sudo install -m 755 dash-$GOOS-$GOARCH /usr/local/bin/dashboard

Create a Datasource

By default, dash will look for the configuration folder which contains your datasources and dashboards in your HOME directory. This setting can be overwritten with the --config.dir flag.

To create the configuration folder run the following:

mkdir ~/.dash
mkdir ~/.dash/datasources
mkdir ~/.dash/dashboards

Now you can create your first datasource:

tee ~/.dash/datasources/prometheus.yaml <<EOF
type: Prometheus
name: Prometheus
url: http://demo.robustperception.io:9090
EOF

That's it, now you can use your datasource. Try the following command to get all node_load1 datapoints for your configured datasource:

dashboard explore --query 'node_load1'

Note: The example datasource uses the Prometheus Live Demo from Robust Perception. Check out there blog for some awesome insights into Prometheus.

Create a Dashboard

Dashboards must be places in the ~/.dash/dashboards folder. To create a simple dashboard for the node_exporter metrics run the following command:

tee ~/.dash/dashboards/node_exporter.yaml <<EOF
name: Node Exporter
defaultDatasource: prometheus
variables:
  - name: instance
    query: node_uname_info
    label: instance
rows:
  - height: 30
    graphs:
      - width: 25
        type: gauge
        title: CPU Busy
        queries:
          - query: (((count(count(node_cpu_seconds_total{instance=~"{{.instance}}"}) by (cpu))) - avg(sum by (mode)(irate(node_cpu_seconds_total{mode='idle', instance=~"{{.instance}}"}[5m])))) * 100) / count(count(node_cpu_seconds_total{instance=~"{{.instance}}"}) by (cpu))
        options:
          thresholds: [85,95]
          colors: ["green", "yellow", "red"]
      - width: 25
        type: gauge
        title: RAM Used
        queries:
          - query: 100 - ((node_memory_MemAvailable_bytes{instance=~"{{.instance}}"} * 100) / node_memory_MemTotal_bytes{instance=~"{{.instance}}"})
        options:
          thresholds: [80,90]
          colors: ["green", "yellow", "red"]
      - width: 25
        type: gauge
        title: SWAP Used
        queries:
          - query: ((node_memory_SwapTotal_bytes{instance=~"{{.instance}}"} - node_memory_SwapFree_bytes{instance=~"{{.instance}}"}) / (node_memory_SwapTotal_bytes{instance=~"{{.instance}}"} )) * 100
        options:
          thresholds: [80,90]
          colors: ["green", "yellow", "red"]
      - width: 25
        type: gauge
        title: Root FS Used
        queries:
          - query: 100 - ((node_filesystem_avail_bytes{instance=~"{{.instance}}",mountpoint="/",fstype!="rootfs"} * 100) / node_filesystem_size_bytes{instance=~"{{.instance}}",mountpoint="/",fstype!="rootfs"})
        options:
          thresholds: [80,90]
          colors: ["green", "yellow", "red"]

  - height: 70
    graphs:
      - width: 99
        type: linechart
        title: CPU Basic
        queries:
          - query: sum by (instance,mode)(irate(node_cpu_seconds_total{mode="system", instance=~"{{.instance}}"}[5m])) * 100
            label: "Busy System"
          - query: sum by (instance,mode)(irate(node_cpu_seconds_total{mode='user', instance=~"{{.instance}}"}[5m])) * 100
            label: "Busy User"
          - query: sum by (instance,mode)(irate(node_cpu_seconds_total{mode='iowait', instance=~"{{.instance}}"}[5m])) * 100
            label: "Busy Iowait"
          - query: sum by (instance,mode)(irate(node_cpu_seconds_total{mode=~".*irq", instance=~"{{.instance}}"}[5m])) * 100
            label: "Busy IRQs"
          - query: sum (irate(node_cpu_seconds_total{mode!='idle',mode!='user',mode!='system',mode!='iowait',mode!='irq',mode!='softirq', instance=~"{{.instance}}"}[5m])) * 100
            label: "Busy Other"
          - query: sum by (mode)(irate(node_cpu_seconds_total{mode='idle', instance=~"{{.instance}}"}[5m])) * 100
            label: "Idle"
        options:
          legend: "right"
EOF

When the dashboard was created run the following to start dash and to refresh the dashboard every 5 seconds:

dashboard --config.refresh 5s

Command-Line Options and Flags

dash supports multiple command-line options and flags:

• Run dash without any options to enter the dashboard view: dashboard
• Run dash with the explore option to enter the explore mode: dashboard explore
• Run dash with the version option to print the version information for dash: dashboard version

The following global flags are available:

• --config.dir string: Location of the datasources and dashboards folder. (default ~/.dash)
• --config.interval string: Interval to retrieve data for. (default 1h)
• --config.refresh string: Time between refreshs of the dashboard. (default 5m)
• --debug: Log debug information.

The explore mode also supports the --query flag:

• --query string: Query which should be executed.

More information to the available options can be found at the Options page. Information for the navigation in the dashboard and explore mode can be found at the Key Mapping page.