Skip to content

Commit f90505a

Browse files
danielleedaniellee
committed
add latitude, longitude and metric fields to table options
This allows a user to map these fields for those datasources that do not allow aliases for fields.
1 parent d390b4a commit f90505a

17 files changed

+646
-274
lines changed

‎README.md‎

Lines changed: 28 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -129,7 +129,7 @@ The Group By clause should be the country code and an alias is needed too. The a
129129

130130
![Influx Query for Countries](https://raw.githubusercontent.com/grafana/worldmap-panel/master/src/images/influx-query.png)
131131

132-
#### Elasticseach Query for Countries
132+
#### Elasticsearch Query for Countries
133133

134134
Use a Group By clause on the field containing the country code and a Then by clause with Date Histogram by `@timestamp` (or corresponding date field).
135135

@@ -139,7 +139,7 @@ Use a Group By clause on the field containing the country code and a Then by cla
139139

140140
Under the Worldmap tab, choose either the `countries` or `states` option.
141141

142-
![Worldmap Options for Countries](/src/images/countries-option.png)
142+
![Worldmap Options for Countries](https://raw.githubusercontent.com/grafana/worldmap-panel/master/src/images/countries-option.png)
143143

144144
Using a JSON endpoint to return a custom list of locations:
145145

@@ -176,17 +176,32 @@ Three fields need to be provided by the ElasticSearch query:
176176
Supported Databases:
177177

178178
- InfluxDB
179+
- Elasticsearch
180+
- MySQL, Postgres, MSSQL
181+
- Any database that can return data in Table Format
182+
183+
If a datasource can return Table Data then on the Metrics tab in Grafana choose the `FORMAT AS` Table option.
179184

180-
An example of Table Data would using InfluxDB and then formatting the data returned from the metric query as Table.
185+
### Table Data with a Geohash Column
181186

182187
Similar to the Elasticsearch query above, 3 fields are expected (2 of them are mandatory)
183188

184-
- a field named *metric*
185-
- a geohash tag named *geohash*
186-
- an optional location name (shown in the mouse over). This location name has to be specified in the Worldmap settings tab too.
189+
- A *metric* field. This is used to give the circle a value and determines how large the circle is.
190+
- A *geohash* field. This is used to calculate where the circle should be drawn.
191+
- an optional location name field (shown in the mouse over). Used to label each circle on the map. If it is empty then the geohash value is used as the label.
192+
193+
The field mappings have to be specified on the Worldmap settings tab.
187194

188195
![Example influxdb query](https://cloud.githubusercontent.com/assets/434655/16535977/8cd520be-3fec-11e6-8dc9-2ecf7b16ad5f.png)
189196

197+
### Table Data with Latitude and Longitude Columns
198+
199+
The Table Data format also works with two columns for latitude and longitude instead of a geohash column.
200+
201+
- A *metric* field. This is used to give the circle a value and determines how large the circle is.
202+
- Latitude/Longitude Fields. These are used to calculate where the circle should be drawn.
203+
- an optional location name field (shown in the mouse over). Used to label each circle on the map. If it is empty then the geohash value is used as the label.
204+
190205
## JSON result as the Data Source
191206

192207
Supported Databases:
@@ -197,17 +212,18 @@ It supports any datasource capable of generating a JSON response with a a custo
197212

198213
### Map Data Options
199214

200-
**Location Data**
215+
#### Location Data
201216

202217
There are four ways to provide data for the worldmap panel:
218+
203219
- *countries*: This is a list of all the countries in the world. It works by matching a country code (US, FR, AU) to a node alias in a time series query.
204220
- *states*: Similar to countries but for the states in USA e.g. CA for California
205221
- *geohash*: An ElasticSearch query that returns geohashes.
206222
- *json*: A json endpoint that returns custom json. Examples of the format are the [countries data used in first option](https://github.com/grafana/worldmap-panel/blob/master/src/data/countries.json) or [this list of cities](https://github.com/grafana/worldmap-panel/blob/master/src/data/probes.json).
207223
- *jsonp*: A jsonp endpoint that returns custom json wrapped as jsonp. Use this if you are having problems with CORS.
208-
- *table*: This expects the metric query to return data points with a field named geohash. This field should contain a string in the [geohash form](https://www.elastic.co/guide/en/elasticsearch/guide/current/geohashes.html). For example: London -> "gcpvh3zgu992".
224+
- *table*: This expects the metric query to return data points with a field named geohash or two fields/columns named `latitude` and `longitude`. This field should contain a string in the [geohash form](https://www.elastic.co/guide/en/elasticsearch/guide/current/geohashes.html). For example: London -> "gcpvh3zgu992".
209225

210-
**Aggregation**
226+
#### Aggregation
211227

212228
If you chose *countries* or *table* as the source of the location data then you can choose an aggregation here: avg, total etc.
213229

@@ -219,10 +235,11 @@ Or just remove the 1 from the Max Data Point field and use the consolidation fun
219235

220236
![Graphite Max Data Points](https://raw.githubusercontent.com/grafana/worldmap-panel/master/src/images/graphite-maxdatapoints.png)
221237

222-
**ES Metric/Location Name/geo_point Field**
238+
#### ES Metric/Location Name/geo_point Field
223239

224240
Three fields need to be provided by the ElasticSearch query. They are text fields and should be the field names from the query under the Metrics tab.
225-
- Metric is one of Count, Average, Sum etc.
241+
242+
- The Metric in Elasticsearch is one of `Count`, `Average`, `Sum` etc.
226243
- Location Name is the field that gives the circle a name. If it is blank, then the geohash value is shown in the popover instead of the location.
227244
- geo_point is the GeoHashGrid field that provides the geohash value.
228245

‎dist/README.md‎

Lines changed: 149 additions & 48 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,85 @@
1-
## Worldmap Panel Plugin for Grafana
1+
# Worldmap Panel Plugin for Grafana
22

3-
The Worldmap Panel is a tile map of the world that can be overlaid with circles representing data points from a query. It can be used with time series metrics, with geohash data from Elasticsearch or Table Data.
3+
The Worldmap Panel is a tile map of the world that can be overlaid with circles representing data points from a query. It can be used with time series metrics, with geohash data from Elasticsearch or data in the Table format.
44

55
![Worldmap](https://raw.githubusercontent.com/grafana/worldmap-panel/54f83cfdc7339fee02df00933422c35630677330/src/images/worldmap-world.png)
66

7-
There are currently two ways to connect data with points on a map. Either by matching a tag or series name to a country code/state code (e.g. SE for Sweden, TX for Texas) or by using geohashes to map against geographic coordinates.
7+
## How The Worldmap Works (Theory and Examples)
8+
9+
The Worldmap panel needs two sources of data:
10+
11+
- a location (latitude and longitude)
12+
- data that has a link to a location
13+
14+
The data comes from a database query: Prometheus, InfluxDB, Graphite, Elasticsearch, MySQL etc. It can be in the Time Series format or in the Table format.
15+
16+
### Time Series Format
17+
18+
If it is in the **Time Series format** then the metric name needs to match a key from a list of locations. That key is usually a country code or city name. The list of locations can come from a file or an HTTP endpoint.
19+
20+
The list of locations can be provided in several ways:
21+
22+
- json files with locations and their coordinates (the plugin includes list for countries and US states)
23+
- json endpoints that return a list of locations and their coordinates
24+
25+
Time Series data contains a timestamp, a metric name and a numeric value. In other words, a typical query for a time series database. Here is some time series data from Graphite:
26+
27+
```json
28+
[
29+
{"target": "SE", "datapoints": [[183255.0, 1529755200]]},
30+
{"target": "US", "datapoints": [[192224.0, 1529755200]]}
31+
]
32+
```
33+
34+
Location data should be in the JSON format and should be an array of JSON objects with four properties:
35+
36+
```json
37+
[
38+
{
39+
"key": "SE",
40+
"latitude": 60.128161,
41+
"longitude": 18.643501,
42+
"name": "Sweden"
43+
},
44+
{
45+
"key": "US",
46+
"latitude": 37.09024,
47+
"longitude": -95.712891,
48+
"name": "United States"
49+
}
50+
]
51+
```
52+
53+
The Worldmap will then match the metric name (target in the example data) with a key field from the location data. With this example data there will be two circles drawn on the map, one for Sweden and one for the United States with values 183255 and 192224.
54+
55+
### Table Format
56+
57+
If the data is in the **Table format** then it should have a column that is a geohash or two columns that contain the latitude and longitude (together with the columns for the data).
58+
59+
Table data is tabular data with columns and rows. Here is an example of Table data from InfluxDB:
60+
61+
```json
62+
"series": [
63+
{
64+
"name": "logins.count",
65+
"tags": {
66+
"geohash": "9wvfgzurfzb"
67+
},
68+
"columns": [
69+
"time",
70+
"metric"
71+
],
72+
"values": [
73+
[
74+
1529762933815,
75+
75.654324173059
76+
]
77+
]
78+
}
79+
]
80+
```
81+
82+
This query contains both data (the value `75.654324173059`) and a location (the geohash `9wvfgzurfzb` which is in Colorado). So using these, the Worldmap panel will draw one circle in Colorado, USA with the value 75.654324173059.
883

984
## Time Series Data as the Data Source
1085

@@ -14,35 +89,47 @@ Supported Databases:
1489
- InfluxDB
1590
- OpenTSDB
1691
- Prometheus
92+
- MySQL
93+
- Postgres
94+
- MSSQL
1795
- Elasticsearch
1896

19-
Included location data:
97+
The following location files are included in the plugin:
2098

2199
- Countries (2 letter codes)
22100
- Countries (3 letter codes)
23101
- US states
24102

25-
This works by matching country codes (like US or GB or FR) or US state codes (TX or NY) to a node or a wildcard in a metric namespace. If there is a match in the list of countries or states then a circle will be drawn at the location.
103+
Alternatively, you can provide your own location lists by using:
104+
105+
- A JSON endpoint that returns a list of locations
106+
- A JSONP endpoint that returns a list of locations
107+
108+
This works by matching country codes (like US or GB or FR) or US state codes (TX or NY) to a metric name. If a metric name matches a country in the list of countries then a circle will be drawn at that location.
26109

27110
If you want to match to other data than countries or states, then you will have to provide custom location data. The current way to do that is via a JSON endpoint that returns a json file with location data (See Map Data Options)
28111

29112
The size of the circle depends on the value of the matched metric. Circle size is relative e.g. if you have 3 countries with values 1, 2 and 3 or 100, 200 and 300 then you will get one small circle, one medium circle and one large circle.
30113

31-
#### Query Examples
114+
### Time Series - Graphite and InfluxDB
115+
116+
Here are some examples of Time Series Queries
32117

33-
#### Graphite Query for Countries
118+
#### Graphite Query
34119

35120
Use the aliasByNode function to point to the field containing the country code. See the image below for an example of a graphite query.
36121

37122
![Graphite Query for Countries](https://raw.githubusercontent.com/grafana/worldmap-panel/master/src/images/worldmap-timeseries-query.png)
38123

39-
#### Influx Query for Countries
124+
Example dashboard for Worldmap with Graphite queries on [the Grafana play site](http://localhost:3000/d/000000003/worldmap-panels?panelId=8&fullscreen&edit&orgId=1).
125+
126+
#### InfluxDB Query
40127

41128
The Group By clause should be the country code and an alias is needed too. The alias should be in the form `$tag_<field name>`.
42129

43130
![Influx Query for Countries](https://raw.githubusercontent.com/grafana/worldmap-panel/master/src/images/influx-query.png)
44131

45-
#### Elasticseach Query for Countries
132+
#### Elasticsearch Query for Countries
46133

47134
Use a Group By clause on the field containing the country code and a Then by clause with Date Histogram by `@timestamp` (or corresponding date field).
48135

@@ -84,72 +171,59 @@ Three fields need to be provided by the ElasticSearch query:
84171

85172
![Elasticsearch Query for Worldmap](https://raw.githubusercontent.com/grafana/worldmap-panel/master/src/images/es-options.png)
86173

87-
88174
## Table Data as the Data Source
89175

90176
Supported Databases:
91177

92178
- InfluxDB
179+
- Elasticsearch
180+
- MySQL, Postgres, MSSQL
181+
- Any database that can return data in Table Format
93182

94-
An example of Table Data would using InfluxDB and then formatting the data returned from the metric query as Table.
95-
96-
Similar to the Elasticsearch query above, 3 fields are expected (2 of them are mandatory)
97-
98-
- a field named *metric*
99-
- a geohash tag named *geohash*
100-
- an optional location name (shown in the mouse over). This location name has to be specified in the Worldmap settings tab too.
101-
102-
![Example influxdb query](https://cloud.githubusercontent.com/assets/434655/16535977/8cd520be-3fec-11e6-8dc9-2ecf7b16ad5f.png)
103-
104-
## JSON result as the Data Source
105-
106-
107-
Supported Databases:
108-
109-
- Warp&nbsp;10 via [grafana-warp10-datasource](https://github.com/cityzendata/grafana-warp10) plugin
110-
111-
It supports any datasource capable of generating a JSON response with a a custom list of locations (the same format that for the JSON enpoint).
112-
113-
### Map Visual Option Settings
183+
If a datasource can return Table Data then on the Metrics tab in Grafana choose the `FORMAT AS` Table option.
114184

115-
**Center**
185+
### Table Data with a Geohash Column
116186

117-
This settings configures the default center of the map. There are 5 centers to choose from or you can choose a custom center or last GeoHash center..For a custom center there are two fields: latitude and longitude. Examples of values are 37.09024, -95.712891 for the center of the US or 55.378051, -3.435973 for Great Britain. Last GeoHash center will centered the map on the last GeoHash received from the data.
187+
Similar to the Elasticsearch query above, 3 fields are expected (2 of them are mandatory)
118188

189+
- A *metric* field. This is used to give the circle a value and determines how large the circle is.
190+
- A *geohash* field. This is used to calculate where the circle should be drawn.
191+
- an optional location name field (shown in the mouse over). Used to label each circle on the map. If it is empty then the geohash value is used as the label.
119192

120-
**Initial Zoom**
193+
The field mappings have to be specified on the Worldmap settings tab.
121194

122-
The initial zoom factor for the map. This is a value between 1 and 18 where 1 is the most zoomed out.
123-
124-
**Min Circle Size**
195+
![Example influxdb query](https://cloud.githubusercontent.com/assets/434655/16535977/8cd520be-3fec-11e6-8dc9-2ecf7b16ad5f.png)
125196

126-
This is minimum size for a circle in pixels.
197+
### Table Data with Latitude and Longitude Columns
127198

128-
**Max Circle Size**
199+
The Table Data format also works with two columns for latitude and longitude instead of a geohash column.
129200

130-
This is the maximum size for a circle in pixels. Depending on the zoom level you might want a larger or smaller max circle size to avoid overlapping.
201+
- A *metric* field. This is used to give the circle a value and determines how large the circle is.
202+
- Latitude/Longitude Fields. These are used to calculate where the circle should be drawn.
203+
- an optional location name field (shown in the mouse over). Used to label each circle on the map. If it is empty then the geohash value is used as the label.
131204

132-
**Unit**
205+
## JSON result as the Data Source
133206

134-
The Unit is shown in the popover when you hover over a circle. There are two fields the singular form and the plural form. E.g. visit/visits or error/errors
207+
Supported Databases:
135208

136-
**Show Legend**
209+
- Warp&nbsp;10 via [grafana-warp10-datasource](https://github.com/cityzendata/grafana-warp10) plugin
137210

138-
Shows/hide the legend on the bottom left that shows the threshold ranges and their associated colors.
211+
It supports any datasource capable of generating a JSON response with a a custom list of locations (the same format that for the JSON enpoint).
139212

140213
### Map Data Options
141214

142-
**Location Data**
215+
#### Location Data
143216

144217
There are four ways to provide data for the worldmap panel:
218+
145219
- *countries*: This is a list of all the countries in the world. It works by matching a country code (US, FR, AU) to a node alias in a time series query.
146220
- *states*: Similar to countries but for the states in USA e.g. CA for California
147221
- *geohash*: An ElasticSearch query that returns geohashes.
148222
- *json*: A json endpoint that returns custom json. Examples of the format are the [countries data used in first option](https://github.com/grafana/worldmap-panel/blob/master/src/data/countries.json) or [this list of cities](https://github.com/grafana/worldmap-panel/blob/master/src/data/probes.json).
149223
- *jsonp*: A jsonp endpoint that returns custom json wrapped as jsonp. Use this if you are having problems with CORS.
150-
- *table*: This expects the metric query to return data points with a field named geohash. This field should contain a string in the [geohash form](https://www.elastic.co/guide/en/elasticsearch/guide/current/geohashes.html). For example: London -> "gcpvh3zgu992".
224+
- *table*: This expects the metric query to return data points with a field named geohash or two fields/columns named `latitude` and `longitude`. This field should contain a string in the [geohash form](https://www.elastic.co/guide/en/elasticsearch/guide/current/geohashes.html). For example: London -> "gcpvh3zgu992".
151225

152-
**Aggregation**
226+
#### Aggregation
153227

154228
If you chose *countries* or *table* as the source of the location data then you can choose an aggregation here: avg, total etc.
155229

@@ -161,13 +235,40 @@ Or just remove the 1 from the Max Data Point field and use the consolidation fun
161235

162236
![Graphite Max Data Points](https://raw.githubusercontent.com/grafana/worldmap-panel/master/src/images/graphite-maxdatapoints.png)
163237

164-
**ES Metric/Location Name/geo_point Field**
238+
#### ES Metric/Location Name/geo_point Field
165239

166240
Three fields need to be provided by the ElasticSearch query. They are text fields and should be the field names from the query under the Metrics tab.
167-
- Metric is one of Count, Average, Sum etc.
241+
242+
- The Metric in Elasticsearch is one of `Count`, `Average`, `Sum` etc.
168243
- Location Name is the field that gives the circle a name. If it is blank, then the geohash value is shown in the popover instead of the location.
169244
- geo_point is the GeoHashGrid field that provides the geohash value.
170245

246+
### Map Visual Option Settings
247+
248+
**Center**
249+
250+
This settings configures the default center of the map. There are 5 centers to choose from or you can choose a custom center or last GeoHash center..For a custom center there are two fields: latitude and longitude. Examples of values are 37.09024, -95.712891 for the center of the US or 55.378051, -3.435973 for Great Britain. Last GeoHash center will centered the map on the last GeoHash received from the data.
251+
252+
**Initial Zoom**
253+
254+
The initial zoom factor for the map. This is a value between 1 and 18 where 1 is the most zoomed out.
255+
256+
**Min Circle Size**
257+
258+
This is minimum size for a circle in pixels.
259+
260+
**Max Circle Size**
261+
262+
This is the maximum size for a circle in pixels. Depending on the zoom level you might want a larger or smaller max circle size to avoid overlapping.
263+
264+
**Unit**
265+
266+
The Unit is shown in the popover when you hover over a circle. There are two fields the singular form and the plural form. E.g. visit/visits or error/errors
267+
268+
**Show Legend**
269+
270+
Shows/hide the legend on the bottom left that shows the threshold ranges and their associated colors.
271+
171272
### Threshold Options
172273

173274
Thresholds control the color of the circles.

0 commit comments

Comments
 (0)