diff --git a/README.md b/README.md index 9dbf569..bb09848 100644 --- a/README.md +++ b/README.md @@ -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=""}[$__interval]) == 1) * +``` + +If there was no such status (``) 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