Grafana Worldmap Panel

April 30, 2020

Introduction

Grafana Worldmap is a free-of-cost panel used to display time-series metrics over a world map. Users can choose to visualize their data based on cities, states, countries or any other segregation they like as long as they have a coordinate for each datapoint. Each datapoint is represented in the form of circles that vary in size depending on the value of data and can be color coded as per thresholds.

Why use Grafana Worldmap Panel?

Worldmap is used to represent time-series metrics over the tile map of the world. They are essential for businesses with geographically significant data. For example, businesses having multiple points of sale would use Grafana Worldmap to compare important metrics based on region.

Let’s consider a US based retailer selling books online. The company would often need to see their sales based on cities or their webpage responses by states, where each poor performer and outperformer is easily distinguishable. Similarly, a Telecom Operator serving worldwide customers may need to picture their throughput based on countries in a way that is easier to visualize. In all such cases, Worldmap serves as a great solution and helps provide a quick glimpse of how each region is performing, easily color coding the outliers.

If you want to try out using Worldmap on your own, the best way is to sign up for the MetricFire free trial, where you can use their Hosted Grafana right in the platform.

How to Install Worldmap?

Wordmap is not out-of-box installed with the default Grafana package. Users would have to explicitly install the plugin. On local instances, much like other plugins, this plugin is also installed using a simple command over the Grafana CLI tool. Open the CLI and follow the below steps to install and start using Worldmap.

  1. Run the below command to install Worldmap. (Grafana 3.0 or higher is necessary to use this plugin).

           grafana-cli plugins install grafana-worldmap-panel

  1. Once installed, the panel is now added to your /var/lib/Grafana/plugins directory.
  2. Restart Grafana and the panels will start showing up in your dashboard.
  3. After restart, you can directly use it in your dashboards using the Choose Visualization option.

Alternatively, users may also choose to manually download and unzip the package into the plugin directory /var/lib/Grafana/plugins. You can download the package by navigating to the Grafana page and clicking on download the .zip file.

Data Sources and Usage:

Worldmap plugin has two basic requirements:

  1. Data – This is the metric value that results from a database query and determines the circle size on the map.
  2. Location - This is the location to which we tie the data from point 1. Location information could either be in the form of Latitude and Longitude or as geohash. The panel looks at these coordinates to determine which points should be circled on the map.

Worldmap allows the input data source, resulting from a database query, to be in two different formats:

  1. Time Series – Series of datapoints indexed in time order.
  2. Table Format – Datapoints formatted in rows and columns.

With each of the two data formats, there comes a variety of options on how the plugin fulfills the second basic requirement i.e. Location.

 

Time Series as Data Source:

Supported databases are:

  • Graphite
  • InfluxDB
  • Prometheus
  • Elasticsearch
  • OpenTSDB
  • MySQL
  • Postgres
  • MSSQL

Users using any of the supported databases can simply choose to display their time-series data using the location files provided by the plugin. The plugin comes with 3 in-built location files as below:

  1. countries.json – JSON List of countries with 2 letter codes. Example: ‘CA’ for Canada, ‘GB’ for United Kingdom and ‘US’ for United States.
  2. countries_3letter.json - JSON List of countries with 3 letter codes. Example: ‘USA’ for United states, ‘GBR’ for United Kingdom and ‘ARE’ for United Arab Emirates.
  3. states.json – JSON List of US states with 2 letter codes. Example: ‘AZ’ for Arizona, ‘NY’ for New York and ‘CA’ for California.

 

However, to use the above location files, the query result must contain a target value that exactly matches the key from the location file.

If you have locations that aren’t part of these files, the plugin allows you to provide JSON/JSONP endpoints. Both the endpoints should return a list of locations in an acceptable format. For example, the link here returns a list of some major locations in a format that the plugin accepts. Each location should contain a key, latitude and longitude value and location name. At this moment, the plugin doesn’t allow uploading custom endpoint files.

For example: With Graphite as data source, a typical time-series datapoint looks like this:

<p>CODE:https://gist.github.com/denshirenji/41e429a8b81aad498bef42d8a128856f.js</p>

And the accepted json format is as follows:

<p>CODE:https://gist.github.com/denshirenji/244fdc6e3697d38d2586d7543d05a82a.js</p>

The plugin here maps the target ‘CA’ from the datapoint with the key ‘CA’ from the location list. Then using the corresponding values of latitude and longitude, it visualizes the value of 151 with a corresponding circle size on the map right over Canada.

If you would like to try this out on your local Graphite database, type the below commands to enter a dummy value:

echo "worldmap.location.data.CA 25 `date +%s`" | nc localhost 2003

On your Grafana Dashboard, enter the below configs and you will see the value 25 is circled over Canada. For multiple locations on a single map, change ‘CA’ to ‘*’. The alias function is necessary since based on this value the plugin tries to map it with the location list or JSON output.

 

For using the default location list, select location data as ‘countries’, ‘countries_3letter’, or states. Set aggregation as min, max, avg, count or total.

 

To provide json resulting endpoints, select Location Data as ‘json endpoint’ or ‘jsonp endpoint’, and provide the endpoint. And as we already mentioned earlier, for the map to identify the location correctly the query result must contain a target value that exactly matches the key from the location file or the json output.

 

 

Table Format as Data Source

Supported Databases are:

  • InfluxDB
  • Elasticsearch
  • MySQL, Postgres, MSSQL
  • Any other database returning table formatted data.

The Worldmap plugin allows using the above databases as input source where queries return table formatted data in the form of rows and columns. The datapoints must provide additional locational data using a single geohash column or two columns of latitude and longitude values.

For both the formats the field requirements are similar:

  1. Metric: Name of the metric, the value of the which represents the circle size on the map.
  2. Geohash/Latitude-Longitude field: Depending upon whether you have geohash value or latitude longitude values, this field calculates where the circle would be drawn.
  3. Location Name (optional): This field is used to assign user-friendly names to the geohash values on the map.

For example, typical table formatted data from InfluxDB would look like this. The data contains a metric value of 5 and a geohash value representing San Francisco.

<p>CODE:https://gist.github.com/denshirenji/3f308fa59e9fabf71e572e9852ef4311.js</p>

Configure the below settings on the Grafana panel to generate a circular plot over San Francisco city showing 5 errors.



Geohash as Data Source

The plugin also allows using Geo-point data type as input but with restrictions of only geohash indexing format. The only supported Database is:

  • Elasticsearch

To plot a geo-point data type expressed as geohash, the Elasticsearch query needs to provide 3 fields:

  1. Metric: Its free text and should match the aggregation used (Count, Average, Sum, Unique Count etc.)
  2. Location Name (Optional): geohash value is shown if not selected.
  3. Geo_point field that provides geohash value.


WorldMap Panel Options:

  1. Data Options:
    a. Location data
    : The plugin allows below formats for location data. Users can choose depending on the query data source as discussed above.



b. Aggregation: The plugin allows aggregation methods such as min, max, average, count and total. Users can choose to change aggregation depending on their requirements.


  1. Visual Options:
    a. Center: Shows what location to select as map center.
    b. Initial Zoom:
    Shows Zoom levels on map.
    c. Min Circle Size:
    Minimum value of circle to be plotted on map.
    d. Max Circle Size:
    Maximum size of circle to be plotted on map.
    e. Sticky Labels:
    When ON, the location label stays on map after hovering.
    f. Decimals:
    Number of decimal values allowed for metrics.
    g. Unit:
    Define Units for metric values. Allows choice of separate singular and plural values. E.g. Error/Errors.
    h. Show legend:
    When ON, shows the threshold values selected for colour coding.
    i. Mouse Wheel Zoom:
    Allows to zoom using mouse wheel.
    j. Threshold Options:
    The threshold options are similar to any typical Grafana plugin. Users can choose to define their comma separated values of threshold and color code them accordingly.

Summary

To conclude, Worldmap panel serves a very useful purpose in the world of monitoring. It’s a boon to dev-ops and NOC teams working for large businesses, especially multi-store. These teams can easily visualize their location-based metrics coming from different regions of the world using small to large circles representing cities, countries or any location worldwide. The threshold settings adds to its benefit by color coding values, notifying users of any faulty datapoint or degrading performance, all in one map of the Earth.

Get to know more about other useful plugins and our Favorite Grafana Dashboards here

Get on to the MetricFire free trial and get started visualizing your data. Also, you can always book a demo and talk with us directly about your monitoring needs. Happy Monitoring!!


Related Posts

GET FREE MONITORING FOR 14 DAYS