geostats command to generate statistics to display geographic data and summarize the data on maps.
The command generates statistics which are clustered into geographical bins to be rendered on a world map.
The events are clustered based on latitude and longitude fields in the events. Statistics are then evaluated on the generated clusters. The statistics can be grouped or split by fields using a
For map rendering and zooming efficiency, the
geostats command generates clustered statistics at a variety of zoom levels in one search, the visualization selecting among them. The quantity of zoom levels is controlled by the
maxzoomlevel options. The initial granularity is selected by the
binspanlat and the
binspanlong. At each level of zoom, the number of bins is doubled in both dimensions for a total of 4 times as many bins for each zoom in.
geostats [translatetoxy=<bool>] [latfield=<string>] [longfield=<string>] [globallimit=<int>] [locallimit=<int>] [outputlatfield=<string>] [outputlongfield=<string>] [ binspanlat=<float> binspanlong=<float> ] [maxzoomlevel=<int>] <stats-agg-term>... [<by-clause>]
- Syntax: <stats-func> ( <evaled-field> | <wc-field> ) [AS <wc-field>]
- Description: A statistical aggregation function. Use the AS clause to place the result into a new field with a name that you specify.
- Syntax: avg() | c() | count() | dc() | distinct_count() | earliest() | estdc() | estdc_error() | exactperc<int>() | first() | last() | latest() | list() | max() | median() | min() | mode() | p<int>() | perc<int>() | range() | stdev() | stdevp() | sum() | sumsq() | upperperc<int>() | values() | var() | varp()
- Description: Functions used with the
geostatscommand. Each time you invoke the
geostatscommand, you can specify more than one function. However, you can only use one
For a list of statistical functions with descriptions and examples, see Statistical and charting functions.
- Syntax: binspanlat=<float>
- Description: The size of the bins in latitude degrees at the lowest zoom level.
- Default: 22.5. If the default values for
binspanlongare used, a grid size of 8x8 is generated.
- Syntax: binspanlong=<float>
- Description: The size of the bins in longitude degrees at the lowest zoom level.
- Default: 45.0. If the default values for
binspanlongare used, a grid size of 8x8 is generated.
- Syntax: BY <field>
- Description: The name of the field to group by.
- Syntax: globallimit=<int>
- Description: Controls the number of named categories to add to each pie-chart. There is one additional category called "OTHER" under which all other split-by values are grouped. Setting globallimit=0 removes all limits and all categories are rendered. Currently the grouping into "OTHER" only works intuitively for count and additive statistics.
- Default: 10
- Syntax: locallimit=<int>
- Description: Specifies the limit for series filtering. When you set
locallimit=N, the top N values are filtered based on the sum of each series. If
locallimit=0, no filtering occurs.
- Syntax: latfield=<field>
- Description: Specify a field from the pre-search that represents the latitude coordinates to use in your analysis.
- Defaults: lat
- Syntax: longfield=<field>
- Description: Specify a field from the pre-search that represents the longitude coordinates to use in your analysis.
- Default: lon
- Syntax: maxzoomlevel=<int>
- Description: The maximum level to be created in the quad tree.
- Default: 9. Specifies that 10 zoom levels are created, 0-9.
- Syntax: outputlatfield=<string>
- Description: Specify a name for the latitude field in your geostats output data.
- Default: latitude
- Syntax: outputlongfield=<string>
- Description: Specify a name for the longitude field in your geostats output data.
- Default: longitude
- Syntax: translatetoxy=<bool>
- Description: If true, geostats produces one result per each locationally binned location. This mode is appropriate for rendering on a map. If false, geostats produces one result per category (or tuple of a multiply split dataset) per locationally binned location. Essentially this causes the data to be broken down by category. This mode cannot be rendered on a map.
- Default: true
To display the information on a map, you must run a reporting search with the
If you are using a
lookup command before the
geostats command, see Optimizing your lookup search.
Memory and maximum results
limits.conf file, the
maxresultrows setting in the
[searchresults] stanza specifies the maximum number of results to return. The default value is 50,000. Increasing this limit can result in more memory usage.
max_mem_usage_mb setting in the
[default] stanza is used to limit how much memory the
geostats command uses to keep track of information. If the
geostats command reaches this limit, the command stops adding the requested fields to the search results. You can increase the limit, contingent on the available system memory.
If you are using Splunk Cloud and want to change either of these limits, file a Support ticket.
1. Use the default settings and calculate the count
Cluster events by default latitude and longitude fields "lat" and "lon" respectively. Calculate the count of the events.
... | geostats count
2. Specify the latfield and longfield and calculate the average of a field
Compute the average rating for each gender after clustering/grouping the events by "eventlat" and "eventlong" values.
... | geostats latfield=eventlat longfield=eventlong avg(rating) by gender
3. Count each product sold by a vendor and display the information on a map
Note: This example uses the Buttercup Games data (tutorialdata.zip) and lookup files (prices.csv
and vendors.csv) from the Search Tutorial. To use this example with your Splunk deployment, you must complete the steps in the Use field lookups section of the tutorial for both the
prices.csv and the
vendors.csv files. You can skip the step in the tutorial that makes the lookups automatic.
This search uses the
stats command to narrow down the number of events that the
geostats commands have to process.
Use the following search to compute the count of each product sold by a vendor and display the information on a map.
sourcetype=vendor_* | stats count by Code VendorID | lookup prices_lookup Code OUTPUTNEW product_name | table product_name VendorID | lookup vendors_lookup VendorID | geostats latfield=VendorLatitude longfield=VendorLongitude count by product_name
In this case, the sourcetype=vendor_sales and each of the events looks like this:
[05/Apr/2017:18:24:02] VendorID=5036 Code=B AcctID=6024298300471575
The prices_lookup is used to match the Code field in each event to a product_name in the table. The vendors_lookup is used to output all the fields in vendors.csv: Vendor, VendorCity, VendorID, VendorLatitude, VendorLongitude, VendorStateProvince, VendorCountry that match the VendorID in each event.
Note: In this search, the .csv files are uploaded and the lookups are defined but are not automatic.
This search produces a table displayed on the Statistics tab:
On the Visualizations tab, you should see the information on a world map. In the screen shot below, the mouse pointer is over the pie chart for a region in the northeastern part of the United States.
Zoom in and out to see more details on the map.
Have questions? Visit Splunk Answers and see what questions and answers the Splunk community has about using the geostats command.
This documentation applies to the following versions of Splunk® Enterprise: 6.5.2, 6.5.3, 6.5.4, 6.5.5, 6.5.6, 6.5.7, 6.6.0, 6.6.1, 6.6.2, 6.6.3, 6.6.4, 6.6.5, 7.0.0, 7.0.1