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.
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.
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.
grafana-cli plugins install grafana-worldmap-panel
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.
Worldmap plugin has two basic requirements:
Worldmap allows the input data source, resulting from a database query, to be in two different formats:
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.
Supported databases are:
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:
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:
And the accepted json format is as follows:
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.
Supported Databases are:
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:
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.
Configure the below settings on the Grafana panel to generate a circular plot over San Francisco city showing 5 errors.
The plugin also allows using Geo-point data type as input but with restrictions of only geohash indexing format. The only supported Database is:
To plot a geo-point data type expressed as geohash, the Elasticsearch query needs to provide 3 fields:
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.
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.