jsteele/grafana-statusmap
2
0
Fork 0
mirror of https://github.com/timberjoegithub/grafana-statusmap.git synced 2026-07-22 15:53:09 +00:00
Code Issues Packages Projects Releases Wiki Activity

README general text update

Browse Source
This commit is contained in:
Dmitry Shurupov
2018-09-19 18:42:41 +07:00
parent 0ea6916490
commit 37affc2a38
1 changed files with 53 additions and 33 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+53 -33
View File
@@ -4,11 +4,11 @@
## Features
* Group values into rows and buckets by query's legend
* Grouping values into rows and buckets using legend from query
* User defined color mapping
* Multiple values in bucket display in tooltip
* Interval shaping to better visual representation
* Represent null values as empty bucket or as zero value
* 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
@@ -17,28 +17,49 @@
## Installation
Plugin can be installed with git:
Plugin can be installed via Git:
```
git clone git@github.com:flant/grafana-statusmap.git /var/lib/grafana/plugins/flant-statusmap-panel
```
Or you can download ZIP archive of this repo and unpack it into /var/lib/grafana/plugins directory.
Alternatively, you can download [ZIP archive](https://github.com/flant/grafana-statusmap/archive/master.zip)
of this repo and unpack it into /var/lib/grafana/plugins directory.
## Motivation
This plugin emerges from our needs to visually represent history of changes for a set of objects
with discrete statuses.
_Objects_ can be hosts, Kubernetes pods or coffee makers and _discrete statuses_ are a set
of predefined values: something like `ok` = 0, `off` = 1, `fail` = 2.
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
Discrete statuses requires some setup in prometheus to get all available statuses over time.
If metric has values 0 and 1 and status is stored in label then it's ok. But if there are 5 statuses
and metric has possible values (0,1,2,3,4) then it should be transformed into previous form with this rule:
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
@@ -47,55 +68,53 @@ and metric has possible values (0,1,2,3,4) then it should be transformed into pr
```
This rule will transform metric `coffee_maker_status` with value `3` into this new metric:
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 for each status. And these metrics can be aggregated
to get all available statuses over time.
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
Each possible status value corresponds to a separate query. Each query should have similar legend for grouping.
First of all, each possible status value corresponds to a separate query. Each query should have
similar legend for grouping:
![Query setup](https://raw.githubusercontent.com/flant/grafana-statusmap/master/src/img/queries-example.png)
Next define color mapping for status values in __Discrete__ color mode.
Then, color mapping for status values should be defined in __Discrete__ color mode:
![Color mapping](https://raw.githubusercontent.com/flant/grafana-statusmap/master/src/img/color-mapping.png)
__Spectrum__ and __Opacity__ color modes works as in a [Heatmap](https://grafana.com/plugins/heatmap) plugin.
Note: __Spectrum__ and __Opacity__ color modes function the same way they do in [Heatmap](https://grafana.com/plugins/heatmap) plugin.
### More options
![Bucket options](https://raw.githubusercontent.com/flant/grafana-statusmap/master/src/img/options-bucket.png)
__Multiple values__ check determine multiple values display mode. If check is unset then multiple values
for one bucket treated as error. If check is on then color for bucket determined
by value with least index in color mapping.
__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.
![Color mapping](https://raw.githubusercontent.com/flant/grafana-statusmap/master/src/img/multiple-values-error.png)
__Null values__ can be treated as empty buckets or displayed as color of 0 value.
__Null values__ can be treated as empty buckets or displayed with the color of `0` value.
![Color mapping](https://raw.githubusercontent.com/flant/grafana-statusmap/master/src/img/null-as-empty.png)
__Min width__ and __spacing__ are determine minimal bucket width and spacing between buckets.
__Rounding__ is for round edges.
__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](https://raw.githubusercontent.com/flant/grafana-statusmap/master/src/img/min-width-spacing-rounding.png)
## Development
The easy way to test and develop plugin is to run Grafana instance in docker with following command in the directory containing the plugin.
This will expose the local plugin on your machine to the Grafana container.
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 \
@@ -104,7 +123,8 @@ docker run --rm -it -v $PWD:/var/lib/grafana/plugins/flant-statusmap-panel \
grafana/grafana:5.1.3
```
Now run `grunt` to compile dist directory and start changes watcher:
This will expose local plugin from your machine to Grafana container. Now run `grunt` to compile
dist directory and start changes watcher:
```
grunt watch
@@ -112,9 +132,9 @@ grunt watch
## Acknowledgements
Idea of a plugin comes from Dmitry Stolyarov [@distol](https://github.com/distol), initial version written by Sergey Gnuskov [@gsmetal](https://github.com/gsmetal) and final changes made by Ivan Mikheykin [@diafour](https://github.com/diafour).
The first public release of this plugin has been fully prepared by [Flant](https://flant.com/) engineers. Idea comes from Dmitry Stolyarov ([@distol](https://github.com/distol)), initial version is written by Sergey Gnuskov ([@gsmetal](https://github.com/gsmetal)) and final changes are made by Ivan Mikheykin ([@diafour](https://github.com/diafour)).
This plugin is based on a "Heatmap" panel by Grafana and inspired by ideas from Carpet plot, Discrete panel, Status Panel, Status Dot, Status By Group.
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