Splunk® Enterprise

Search Reference

Download manual as PDF

This documentation does not apply to the most recent version of Splunk. Click here for the latest version.
Download topic as PDF

geostats

Description

Use the 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 by clause.

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 binspanlat, binspanlong, and 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.

Syntax

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

Required arguments

stats-agg-term
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.
stats-func
Syntax: avg() | c() | count() | dc() | distinct_count() | earliest() | estdc() | estdc_error() | exactperc<int>() | first() | last() | latest() | list() | max() | median() | min() | mode() | p<in>() | perc<int>() | range() | stdev() | stdevp() | sum() | sumsq() | upperperc<int>() | values() | var() | varp()
Description: Functions used with the geostats command. Each time you invoke the geostats command, you can use more than one function. However, you can only use one by clause.

For a list of statistical functions with descriptions and examples, see Statistical and charting functions.

Optional arguments

binspanlat
Syntax: binspanlat=<float>
Description: The size of the bins in latitude degrees at the lowest zoom level.
Default: 22.5. With default binspanlong=45.0, leads to a grid size of 8x8.
binspanlong
Syntax: binspanlong=<float>
Description: The size of the bins in longitude degrees at the lowest zoom level.
Default: 45.0. With the default binspanlat=22.5, leads to a grid size of 8x8.
by-clause
Syntax: BY <field>
Description: The name of the field to group by.
globallimit
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
locallimit
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.
latfield
Syntax: latfield=<field>
Description: Specify a field from the pre-search that represents the latitude coordinates to use in your analysis.
Defaults: lat
longfield
Syntax: longfield=<field>
Description: Specify a field from the pre-search that represents the longitude coordinates to use in your analysis.
Default: lon
maxzoomlevel
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.
outlatfield
Syntax: outlatfield=<string>
Description: Specify a name for the latitude field in your geostats output data.
Default: latitude
outlongfield
Syntax: outlongfield=<string>
Description: Specify a name for the longitude field in your geostats output data.
Default: longitude
translatetoxy
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

Usage

To display the information on a map, you must first run a reporting search with the geostats command and save the search as a report or to a dashboard. Then edit the Simple XML to include the <map> visualization element. For more information, see:

Functions and memory usage

Some functions are inherently more expensive, from a memory standpoint, than other functions. For example, the distinct_count function requires far more memory than the count function. The values and list functions also can consume a lot of memory.

If you are using the distinct_count function without a split-by field or with a low-cardinality split-by by field, consider replacing the distinct_count function with the the estdc function (estimated distinct count). The estdc function might result in significantly lower memory usage and run times.

Examples

Example 1:

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 on your Splunk instance, 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.

Compute the count of each product sold by a vendor and display the information on a map.

sourcetype=vendor_* | 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:

[26/Sep/2015: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 into Splunk and the lookups defined, but not automatic.

This search produces a statistics table:

Searchref geostats ex1.png

After you run the search, save it to a dashboard. Here, the dashboard is named "Geostats example" and the panel is named "Vendor and Product Map". Then, select Edit source to edit the XML to change the table element to a map element:

Searchref geostats ex1b.png

Now, when you view the dashboard you should see the information on a world map. Here, it is zoomed in and the mouse is over the pie chart for a region in the northeastern USA:

Searchref geostats ex1c.png

Zoom in and out to see more details on the map. You can read more about the <map> element and its available options in the Simple XML Reference.

Example 2:

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

Example 3:

Cluster events by default latitude and longitude fields "lat" and "lon" respectively. Calculate the count of such events

... | geostats count

See also

iplocation, stats, xyseries

Answers

Have questions? Visit Splunk Answers and see what questions and answers the Splunk community has about using the geostats command.

PREVIOUS
gentimes
  NEXT
head

This documentation applies to the following versions of Splunk® Enterprise: 6.0, 6.0.1, 6.0.2, 6.0.3, 6.0.4, 6.0.5, 6.0.6, 6.0.7, 6.0.8, 6.0.9, 6.0.10, 6.0.11, 6.0.12, 6.0.13, 6.0.14, 6.0.15, 6.2.13, 6.2.14, 6.2.15


Comments

Thank you Jetie for your comment. The system was updated in 6.1 to automatically display the table of information on the Statistics tab and the map on the Visualizations tab. I've updated the topic in Version 6.1+ which you can see here: http://docs.splunk.com/Documentation/Splunk/latest/SearchReference/Geostats

Lstewart splunk, Splunker
November 18, 2015

I think the instructions to save the search as a dashboard and then edit the xml to see the map is for an older version of Splunk. I think it now shows the map on the visualization tab if you have the geostats command. I'm on verison 6.2.

Jetie
October 22, 2015

Please note that "globallimit" limits the GLOBAL number of categories, not the local number of categories to add to each pie-chart.
This in Splunk 6.2.1

Marcoscala
May 15, 2015

Lower values for binspanlat and binspanlong will cause the chart to stop displayin,<br />So far, I experienced issue under binspanlat=23 binspanlong=33

Ykherian
October 1, 2014

Was this documentation topic helpful?

Enter your email address, and someone from the documentation team will respond to you:

Please provide your comments here. Ask a question or make a suggestion.

You must be logged into splunk.com in order to post comments. Log in now.

Please try to keep this discussion focused on the content covered in this documentation topic. If you have a more general question about Splunk functionality or are experiencing a difficulty with Splunk, consider posting a question to Splunkbase Answers.

0 out of 1000 Characters