Skip to content

Latest commit

 

History

History
379 lines (279 loc) · 10.4 KB

cfg.md

File metadata and controls

379 lines (279 loc) · 10.4 KB
Raw

Configuration file

First of all there are dashboard examples here

The configuration file format is JSON and is splitted in two main blocks, datasources and dashboard.

{
  "version": "v1",
  "datasources": [],
  "dashboard": {}
}

Datasources

This main block contains a list of the datasources being used by the dashboard, depending on the datasource type it will have different options. The dashboard widgets will reference the datasource by the id.

  "datasources": [
    {
      "id": "ds1",
      "prometheus": {
        "address": "http://127.0.0.1:9090"
      }
    },
    {
      "id": "ds2",
      "prometheus": {
        "address": "http://127.0.0.1:9091"
      }
    },
    {
      "id": "ds3",
      "graphite": {
        "address": "http://127.0.0.1:7123"
      }
    }
  ],

Types

Prometheus

This will gather metrics from Prometheus.

Options:

  • address: Address to Prometheus API

Graphite

This will gather metrics from Graphite API backends.

Options:

  • address: Address to Graphite API

[InfluxDB]

This will gather metrics from InfluxDB backends.

Options:

  • address: Address to InfluxDB API
  • database: Database to use
  • username: Username for basic auth
  • password: Password for basic auth
  • insecure: True to allow insecure https

Dashboard

The dashboard contains the dashboard configuration and is composed of multiple smaller configuration blocks.

  "dashboard": {
    "grid": {},
    "variables": [],
    "widgets": []
  }

Grid

The grid has configuration of how the grid of the dashboard will behave.

"grid": {
    "fixedWidgets": true,
    "maxWidth": 100
}

maxWidth

Set the scale of the widgets width, by default is 100, so the widgets should have a width based on 100 by default.

For example, 100 means all the row and 50 means half of the row, if you change the maxWith you will need to change the width of the widgets.

fixedWidgets

The grid has 2 wais of behave, adaptive and fixed, by default this setting is false so it means that the grid is adaptive.

Adaptive grids ignore widget's gridPos.x and gridPos.y and only check the width of the widget (gridPos.w), this means that it will fill the row until the next widget doesn't fit on that row and will create a new row.

Fixed grids need that the widget have the x, y and w, are more flexible because you can leave spaces between widgets but need all the data so the widget can be placed on the grid.

Variables

Some strings on the dashboard can be templated (for now only queries and graph labels), here comes the utility of the variables.

Variables are variables that have dynamic values depending on how and when the dashboard has been loaded, there are of different types.

Default variables

These are variables that grafterm loads automatically on the dashboard and can be used by the templating system:

  • __range: The range duration the dashboard is loading.
  • __refresInterval: The dashboard refresh interval selected.

Constant

Constant variables are constants, they don't change, are used to set the value on one place and use it on many queries, for example environment.

"variables": [
    {
        "name": "env",
        "constant": {
            "value": "production"
        }
    }
]

Interval

Interval sets on a variable a dynamic interval based on the range loaded using optional steps value. This is handy to have smoother graphs when the range is big because based on the steps the interval would be bigger also and would remove the spikes

"variables": [
    {
        "name": "interval",
        "interval": {
            "steps": 50
        }
    }
]

Widgets

All widgets have some common settings and then custom settings that differ one from the others depending on the kind of widget.

Common

"widgets": [
    {
        "title": "Some widget",
        "gridPos": {
            "x": 0,
            "y": 0,
            "w": 5,
        }
    }
]
title

The tittle of the widget.

gridPos

This argument describes the where and size of the widget. if using adaptive grid x and y will be ignored. check Grid section to know how this works.

Gauge

This widget is for realtime metrics, doens't show a range of metrics it shows the last point in time (now) of the metric, this means that only accepts one query.

It has fixed minimum and maximum values to be rendered on the terminal and can work as a percentage based widget (from 0% to 100%).

It can have configured the thresholds so it changes the color of the widget based on them.

{
  "gauge": {
    "query": {},
    "percentValue": true,
    "max": 60,
    "min": 0,
    "thresholds": [
      {
        "color": "#37872D"
      },
      {
        "color": "#FA6400",
        "startValue": 50
      },
      {
        "color": "#C4162A",
        "startValue": 75
      }
    ]
  }
}
percentValue

If true it will show the percent value based on the max setting. For example if max: 60 then a value of 60 would show 100%.

If false it will show the value itself. For example if max: 60 would show 60 as value but the widget would render the gauge bar at the highest point.

thresholds

Is a list of thresholds, if no startValue it will be taken as the base color, if no more thresholds this will be the color of the widget. If more thresholds are on the list then it will set the color based on the range of the thresholds from startValue until the next startValue.

Singlestat

The singlestat acts similar to the Gauge, it's realtime and accepts thresholds but id renders the value itself and not a visual representation of fixed boundaries.

"singlestat": {
    "query": {},
    "unit": "bytes",
    "decimals": 3,
    "valueText": "{{.value}}",
    "thresholds": [
        {
            "color": "#299c46"
        },
        {
            "color": "#FF780A",
            "startValue": 350
        },
        {
            "color": "#d44a3a",
            "startValue": 600
        }
    ]
}
valueText

This is what will be rendered on the singlestat panel, is a go template and the value of the metric is accessible in .value. By default it will print the metric value as it is ({{.value}})

Examples:

  • Print with 2 decimals: {{ printf "%.2f" .value }}
  • Print DOWN if value <1 and UP on >=1: {{ if (lt .value 1.0) }}DOWN{{else}}UP{{end}}
unit

Will convert the value to the unit text representation. Check unit section in this same doc.

decimals

The number of decimals used for the representation when the unit format is used.

Graph

This widget graphs different metric series in a range. It accepts multiple queries that will be aggregated on the same graph. A single query can be rendered with multiple series (depending on the returned results).

"graph": {
    "visualization": {
        "legend": {
            "disable": false,
            "rightSide": true
        },
        "yAxis": {
          "unit": "seconds",
          "decimals": 0
        },
        "seriesOverride": [
            {
                "regex": "p99",
                "color": "#c15c17",
                "nullPointMode": "connected"
            },
            {
                "regex": "p95",
                "color": "#f2c96d",
                "nullPointMode": "zero"
            },
            {
                "regex": "p50",
                "color": "#f9ba8f"
            }
        ]
    },
    "queries": []
}
visualization.legend

The legend of the graph visualization can be enabled or disabled. It's enabled by default and can be set on the right of the graph, by default it's on the bottom of it.

visualization.seriesOverride

Each of the graph series can be override based on the legend displayed using a regex, this means that multiple series can be override using the same options.

The setting that can be override at this moment are:

  • color: The color of the displayed series.
  • nullPointMode: This will fill the datapoints on the graph that are missing with different strategies, this setting is useful for graphs that don't have sufficent metrics or are very spaced. The strategies are:
    • connected: Will use an already near known value and use this.
    • zero: Will fill the data point value with 0s.
visualization.yAxis

In this block the settings that represent the format of the y axis are customized.

  • unit: Will convert the value to the unit text representation. Check unit section in this same doc.
  • decimals: The number of decimals used for the representation when the unit format is used.

Templating

Templating of strings use golang built in template. You can use variables of different kinds on different parts of the dashboard.

Examples of using templating system:

  • "{{ .backend }}"
  • sum(rate(http_request_duration_seconds_count[{{.interval}}]))

Query

Query acts differently depending on the widget. If the widget is a real-time widget or a range based widget.

Is composed of a datasource, a legend representation and an expression. The expression will be used on the datasource referenced and the legend will represent the different metrics obtained.

{
  "datasourceID": "ds",
  "expr": "sum(rate(http_request_duration_seconds_count[{{.interval}}])) by (code)",
  "legend": "{{ .code }}"
}

The legend has the ability to use templating and has inside loaded the metric labels obtained by the datasource kind.

Units

Some widgets have unit formatting support, these are the ones that can be used:

  • ``(Default): It will fallback to short.
  • short: Will make the values in short format, e.g:
    • 1000:1 K
    • 1000000: 1 Mil
  • none: The value as it is.
  • percent: Will add a % prefix, e.g:
    • 100: 100%
    • 20: 20%
  • ratio: Conversion values from 0-1 to percent format, e.g:
    • 0.5: 50%
    • 2.1: 210%
  • seconds: Will convert to a single unit pretty duration form, is based on second unit, e.g:
    • 300: 5m
    • 10: 10s
    • 0.3: 300ms
    • 61200: 17h
    • 432000: 5d
  • reqps: Will add the reqps suffix.
  • bytes: based value in bytes will convert to a pretty format, e.g:
    • 1024: 1 KiB
    • 1.405e+8: 134 MiB
    • 4.508e+13: 41 TiB

Units come in combination with the decimals settings.