grafana-statusmap/README.md

Statusmap panel for Grafana

Features

• Grouping values into rows and buckets using legend from query
• User defined color mapping
• Multiple values in bucket can be displayed via tooltip
• Increasing rows/buckets' interval for better visual representation
• Representing null values as empty bucket or zero value

Supported environment

• Prometheus datasource
• Tested with Grafana 5.1.3

Installation

Plugin can be installed via Git:

git clone git@github.com:flant/grafana-statusmap.git /var/lib/grafana/plugins/flant-statusmap-panel

Alternatively, you can download ZIP archive of this repo and unpack it into /var/lib/grafana/plugins directory.

Motivation

We had a desperate need to show a set of timeseries statuses over time period, so we can see a history of changes for objects' statuses. Since we maintain a lot of Kubernetes clusters (and related infrastructure), our main cases for that are visualization of servers & Kubernetes pods health states as well as HTTP services health checks. We've tried a variety of Grafana plugins available (they are listed in Acknowledgements below) but none of them could provide the features and visualization really close to what we've been looking for.

Objects being visualized with this plugin may be different: not only IT components (e.g. server hosts and Kubernetes pods) but just anything you can imagine like coffee makers on the picture above. These objects should have discrete statuses which are sets of predefined values, e.g. ok = 0, off = 1, fail = 2, etc.

Configuration

Prometheus

To work with data from Prometheus you will need to setup discrete statuses of your objects. Here are requirements to store these statuses in metrics:

• metrics should have two values: 0 and 1;
• there should be a label with status' value.

When it's done, you can collect all the data via query, e.g.:

(max_over_time(coffee_maker_status{status="<STATUS_VALUE>"}[$__interval]) == 1) * <STATUS_VALUE>

If there was no such status (<STATUS_VALUE>) during query's interval, Prometheus will return nothing. Otherwise, status' value will be returned.

For example, if you have 5 statuses and metric has possible values (0,1,2,3,4) then it should be transformed into previous form with this rule:

- record: coffee_maker_status:discrete
  expr: |
    count_values("status", coffee_maker_status)

This rule will transform coffee_maker_status metric with value 3 into new metric:

coffee_maker_status:discrete{status="3"} 1

Now, Prometheus has 0 and 1 values for each status as required. These metrics can be aggregated, so you will get all available statuses over time.

Panel

First of all, each possible status value corresponds to a separate query. Each query should have similar legend for grouping:

Then, color mapping for status values should be defined in Discrete color mode:

Note: Spectrum and Opacity color modes function the same way they do in Heatmap plugin.

More options

Multiple values checkbox determine multiple values display mode:

• If it's off, multiple values for one bucket are treated as error;
• If it's on, color for bucket would be determined by the value having least index in color mapping.

Null values can be treated as empty buckets or displayed with the color of 0 value.

Min width and spacing are used to specify minimal bucket width and spacing between buckets. Rounding may be used to round edges.

Development

To test and improve the plugin you can run Grafana instance in Docker using following command (in the directory containing the plugin):

docker run --rm -it -v $PWD:/var/lib/grafana/plugins/flant-statusmap-panel \
           -p 3000:3000 --name grafana.docker \
           --env=GF_USERS_DEFAULT_THEME=light \
           grafana/grafana:5.1.3

This will expose local plugin from your machine to Grafana container. Now run grunt to compile dist directory and start changes watcher:

grunt watch

Acknowledgements

The first public release of this plugin has been fully prepared by Flant engineers. Idea comes from Dmitry Stolyarov (@distol), initial version is written by Sergey Gnuskov (@gsmetal) and final changes are made by Ivan Mikheykin (@diafour).

This plugin is based on "Heatmap" panel by Grafana and inspired by ideas from Carpet plot, Discrete panel, Status Panel, Status Dot, Status By Group.

Changelog

v0.0.1

• First public release