Grafana panel plugin to visualize status of multiple objects over time
Switch branches/tags
Nothing to show
Clone or download
diafour Merge pull request #15 from flant/fix_render
Fix panel rendering timeout
Latest commit bccc332 Oct 18, 2018

README.md

Statusmap panel for Grafana

Statusmap sample panel

Statusmap sample panel with dark theme

Features

  • Grouping values into rows and buckets using legend from query
  • User defined color mapping
  • Multiple values in bucket are 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 with GF_INSTALL_PLUGINS="flant-statusmap-panel" or you can use Git and clone this repo:

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 visualize a set of timeseries statuses over time period, so we can see a history of changes for objects' status. 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.

NB: You can find more details about our journey of creating the plugin in this post.

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 for your objects. Requirements to store these statuses in metrics are as follows:

  • 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 would return nothing. Otherwise, status' value will be returned.

For example, if you have 5 types of statuses and a metric (coffee_maker_status) with 5 allowed values (0, 1, 2, 3, 4), you should transform this metric using following rule:

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

That's how coffee_maker_status metric with value 3 will be transformed into new metric:

coffee_maker_status:discrete{status="3"} 1

Now, when Prometheus has 0 and 1 values for each status, all these metrics can be aggregated, so you will get all available statuses of your objects over time.

Panel

First of all, an individual query for each possible status' value should be created. Each query should also have similar legend for grouping:

Query setup

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

Color mapping

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

More options

Bucket options

Multiple values checkbox specifies how they should be displayed:

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

Color mapping

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

Color mapping

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

Min width, spacing, rounding

Development

To test and improve the plugin you can run Grafana instance in Docker using following command (in the directory containing Statusmap 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 made by Flant engineers. The whole idea has come from Dmitry Stolyarov (@distol), initial version has been written by Sergey Gnuskov (@gsmetal) and final changes has been made by Ivan Mikheykin (@diafour).

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

Changelog

v0.0.2
  • Install with GF_INSTALL_PLUGINS
  • Fix legend overlap
v0.0.1
  • First public release