Region Maps and Gauges in Kibana

With version 5.5, two new visualization types made their way into Kibana, Region Maps and Gauge charts. Admittingly, our attentive readers may interject that calling them “new” is somewhat overstating it. Indeed, early users of Kibana may recognize the Region Map visualization from v3, and the gauge charts already have a presence as one of the chart types in the experimental Time Series Visual Builder. Nonetheless, these Visualizations deserve some exposure, so without further ado, here they are. (Again!)

Region Maps

Region Maps, sometimes called Choropleth maps, use a color gradient to symbolize the value of a metric, where lighter colors indicate lower values and darker colors indicate higher values.

Linking a terms aggregation to a vector layer

These maps are configured by matching the results of a Terms aggregation, to features in a GeoJSON FeatureCollection based on a shared property.

The field of the term-aggregation must match a property value in the shape layer. For example, in a map of world countries this field would have a value of country name or an ISO country identifier. In the example below, we are running a term aggregation on the geo.src field on a logstash index. This is a two-digit ISO country identifier that can be produced by the GeoIp filter plugin. We are counting the number of requests.

This terms-aggregation can now be joined to the world layer. Here we are using the default ‘World Countries’ file that is available from the Elastic Maps Service and match it to that geo.dest field with the two letter abbreviation field from our Terms aggregation

This configuration will produce the following map:

If items from the term-aggregation cannot be joined to a feature in the Geojson layer, Kibana will show a warning. These warnings can be turned off by turning off the visualization:regionmap:showWarnings setting.

Adding your own data layers

Kibana comes readily available with layers of world countries and USA states based on data from Natural Earth . Both these layers are served with the Elastic Maps Service, which is a freely available data service hosted by Elastic supporting Kibana’s mapping visualizations.

You can have Kibana use your own GeoJSON layers as well. Configure this by linking them in the kibana.yml. Any layer that is reachable on the network over http can be linked. If the files are hosted on a differnet domain than Kibana, this does require that the service hosting these files are CORS enabled.

regionmap:
  layers:
     - name: "NYC City Council Districts (self-hosted)"
       url: "http://localhost/nyc_citycouncil.geojson"
       fields:
          - name: "CounDist"
            description: "Council District Number"
     - name: "NYC Boroughs (self-hosted)"
       url: "http://localhost/nyc_boroughs.geojson"
       fields:
          - name: "name"
            description: "Borough Name"

In Kibana, these are then added to the drop down list. It would look something like:

When you CORS enable the server, also make sure you echo all request header names submitted by the Kibana application in the Access-Control-Allow-Headers header-property of the server’s response. Depending on your server technology (Apache, NGINX, IIS, …), this may require some custom configuration. If you prefer to explicitly list the allowed headers, ensure the kbn-version header is part of the server’s response. This header is present on every request coming from the Kibana application.

The region map is subject to the same zoom limitations as the Coordinate Map. To remove the restriction on the number of zoom levels, install X-Pack Basic for free alongside Kibana and Elasticsearch.

Gauge and Goal charts

Gauge and Goal charts look very similar, but they are used for different purposes. The Goal chart is used to track your progress toward a fixed goal. Let’s say you are counting your website visitors and you are trying to hit 1M visitors. This is the perfect use case for a Goal chart.

A Gauge chart on the other hand is used to track the current value. A well known use case for gauges to show speed or RPM in your car. Using an example from the Elastic world, gauges would be suitable for tracking your server response times. You know something about the value you are tracking like its minimum and maximum;. You can also think of your values in ranges: values within the green range are good, values in the yellow range are still ok and values in the red range are bad.

Looking forward to 6.x

In the upcoming major v6 release of Kibana, there are some internal changes to the Visualize code-base (https://github.com/elastic/kibana/pull/11786). These changes have no impact on end-users of Kibana, but are of interest for plugin developers as they require minor edits to register a plugin with Kibana. There are two main reason for this change. One is to increase flexbility in the rendering-technologies a visualization can use. Users are no longer limited to angular, but will be able to use React or plain old JS as well. The other is to separate out the editor that configures the visualization from the actual visualization itself. A coming blog post will provide more information about upgrading plugins from v5 and taking advantage of the new API features.