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 data point. Each data point comes in the form of circles that vary in size depending on the value of data and can get color-coded as per thresholds.

            

Why use Grafana Worldmap Panel?

Grafana Worldmap represents time-series metrics over the tilemap 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 on 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 also gets 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

2. Once installed, the panel is now in your /var/lib/Grafana/plugins directory.
3. Restart Grafana and the panels will start showing up in your dashboard.
4. After restarting, 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 data points 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 three in-built location files as below:

1. countries.json – JSON List of countries with two-letter codes. Example: "CA" for Canada, "GB" for the United Kingdom, and "US" for the United States.
2. countries_3letter.json - JSON List of countries with three-letter codes. Example: "USA" for the United States, "GBR" for the United Kingdom, and "ARE" for the United Arab Emirates.
3. states.json – JSON List of US states with two-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 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 the data source, a typical time-series data point looks like this:

                            

{“target”: “CA”, “datapoints”: [[151, 1584836485]]}, where "CA" represents Canada, 151 is the metric value and 1584836485 is the epoch timestamp.

 

And the accepted json format is as follows:

{
“key”: “CA”,
“latitude”: 56.130366,
“longitude”: -106.346771,
“name”: “Canada”
}

         

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 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.

  

                

Speaking of Graphite—test out MetricFire's top-of-industry Hosted Graphite service. Designed as a counter to the limitations of hosted Prometheus, our hosted Graphite services are the ideal choice to keep tabs on Kubernetes and other key applications and systems.

                       

Why try our Hosted Graphite Service? With our Hosted Graphite, you get better redundancy storage, improved control (by APIs), and tagged metrics for better analysis. Find out more about Hosted Graphite from MetricFire here.

                                  

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 sources where queries return table-formatted data in the form of rows and columns. The data points must provide additional locational data using a single geohash column or two columns of latitude and longitude values.

                        

For both formats, the field requirements are similar:

1. Metric: Name of the metric, the value of 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 is drawn.
3. Location Name (optional): This field assigns 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.

               

"series": [
  {
    "name": "errors.count",
    "tags": {
      "geohash": "9q8yym901hw"
        },
    "columns": [
      "time",
      "metric"
        ],
    "values": [
        [
    	1585004732,
        5.0
        ]
        ]
  }
]

 ‍              

Configure the below settings on the Grafana panel to generate a circular plot over San Francisco city showing five 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 three fields:

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

                     

WorldMap Panel Options:

1. Data Options:
   a. Location data: The plugin allows the 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.

 

 

2. Visual Options:
   a. Center: Shows what location to select as a map center.
   b. Initial Zoom: Shows Zoom levels on the map.
   c. Min Circle Size: Minimum value of circle to get plotted on the map.
   d. Max Circle Size: Maximum size of the circle to get plotted on the map.
   e. Sticky Labels: When ON, the location label stays on the 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 color-coding.
   i. Mouse Wheel Zoom: Allows to zoom using the 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, the 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 add to its benefit by color-coding values, notifying users of any faulty data point 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!