stats
This search command creates an aggregate representation of data in the form of a table of statistics and a corresponding chart based on the field or fields specified. The command also supports the optional group by parameter, to apply aggregate functions on the distinct value of a specified field. For example, you can plot the aggregate count of data occurring from a particular host depending on the data-collector names. Similarly, you can run other aggregate functions such as sum, avg, min, and max to find the sum, average, minimum (smallest), and maximum (highest) values of a field.
This command is similar to the timechart command, except that it does not represent data on the basis of a specified time span; instead, it provides an aggregate representation.
This topic contains the following information:
For a list of all search commands, see Search-commands.
Related topics
Syntax
stats (<aggregate-function>)+
stats (<aggregate-function> [as <alias>])+
stats (<aggregate-function>)+ [by <field>]
stats (<aggregate-function> [as <alias>])+ [by <field>]
In the preceding syntax, the following definitions apply:
- + indicates one or more similar expressions separated by a comma (,) or space.
<aggregate-function> refers to the aggregate function used for creating the chart; for example, count, sum, or average.
The following table describes the aggregate functions that can be used in the command syntax:
Function
Syntax
Description
Count
count (<field>)
Uses field name as an argument and returns the number of occurrences of that field in the search results.
Sum
sum (<field>)
Uses field name as an argument and returns the sum of values of that field in the search results.
Average
avg (<field>)
Uses field name as an argument and returns the average of values of that field in the search results.
Minimum
min (<field>)
Uses field name as an argument and returns the smallest value of that field.
Maximum
max (<field>)
Uses field name as an argument and returns the highest value of that field.
where, <field> can be a field name or a tag name
- [as <alias>]) refers to the as parameter used for optionally renaming a field with an alternate field name (an alias).
- [by <field>] refers to a group by parameter that is optionally used in conjunction with the aggregate functions, to group the result set by the specified field.
Short examples
Example 1: Return the number of occurrences of the RequestType field in the search results.
... | stats count(RequestType)
Example 2: Return the number of occurrences of the RequestType field grouped by the ClientIp field.
... | stats count(RequestType) by ClientIp
Example 3: Return the number of occurrences of the events field and the sum of the values of the bytes-read field in the search results.
... | stats count(events) as Count, sum(bytes-read) as Total
Example 4: Return the number of occurrences of the events field and the sum of the values of the bytes-read field, grouped by the HOST field.
Example 5: Return the sum of values and the average of values of the ResponseSize field, grouped by the ClientIp field.
... | stats sum(ResponseSize), avg(ResponseSize) by ClientIp
Example 6: Return the minimum (smallest), maximum (highest), and average of the ResponseSize field values, grouped by the ClientIp field.
... | stats min(ResponseSize), max(ResponseSize), avg(ResponseSize) by ClientIp
Long examples
The following sample data and sample indexed data (displayed on the Search tab) will help you understand the examples of using the stats command.
- Sample data
- Sample indexed data
- count
- count with by parameter
- sum and avg with by parameter
- min
- max
- min with by parameter
- min, max, and avg
Sample data
10.1.1.140 - - [11/Jul/2013:15:01:52 -0700] "GET /themes/ComBeta/images/bullet.png |
10.1.1.140 - - [11/Jul/2013:15:02:52 -0700] "GET /themes/ComBeta/images/bullet.png |
10.1.1.141 - - [11/Jul/2013:15:03:52 -0700] "PUT /themes/ComBeta/images/bullet.png |
10.1.1.141 - - [11/Jul/2013:15:04:52 -0700] "POST /themes/ComBeta/images/bullet.png |
Sample indexed data
10.1.1.141 - - [11/Jul/2013:15:04:52 -0700] "POST /themes/ComBeta/images/bullet.png HOST=local.bmc.com |ResponseSize=100|COLLECTOR_NAME=u4 |ClientIp=10.1.1.141 |ResponseCode=200 |RequestType=POST|RequestURL=/themes/ComBeta/images/bullet.png |
10.1.1.141 - - [11/Jul/2013:15:03:52 -0700] "PUT /themes/ComBeta/images/bullet.png HOST=local.bmc.com |ResponseSize=200|COLLECTOR_NAME=u4 |ClientIp=10.1.1.141 |ResponseCode=201 |RequestType=PUT|RequestURL=/themes/ComBeta/images/bullet.png |
10.1.1.140 - - [11/Jul/2013:15:02:52 -0700] "GET /themes/ComBeta/images/bullet.png HOST=local.bmc.com |ResponseSize=150|COLLECTOR_NAME=u4 |ClientIp=10.1.1.140 |ResponseCode=201 |RequestType=GET|RequestURL=/themes/ComBeta/images/bullet.png |
10.1.1.140 - - [11/Jul/2013:15:01:52 -0700] "GET /themes/ComBeta/images/bullet.png HOST=local.bmc.com |ResponseSize=100|COLLECTOR_NAME=u4 |ClientIp=10.1.1.140 |ResponseCode=404 |RequestType=GET|RequestURL=/themes/ComBeta/images/bullet.png |
count
In this example, you use the command to display the number of occurrences of the RequestType field.
Command
... | stats count(RequestType)
Output
count(RequestType) |
|---|
4 |
count with by parameter
In this example, you use the command to display the number of occurrences of the RequestType field, grouped by the ClientIp field.
Command
... | stats count(RequestType) by ClientIp
Output
ClientIp | count(RequestType) |
|---|---|
10.1.1.141 | 2 |
10.1.1.140 | 2 |
sum and avg with by parameter
In this example, you use the command to display the sum of values and the average of values of the ResponseSize field, grouped by the ClientIp field.
Command
... | stats sum(ResponseSize), avg(ResponseSize) by ClientIp
Output
ClientIp | sum(ResponseSize) | avg(ResponseSize) |
|---|---|---|
10.1.1.141 | 300 | 150 |
10.1.1.140 | 250 | 125 |
min
In this example, you use the command to display the minimum value (smallest value) of the ResponseSize field.
Command
... | stats min(ResponseSize)
Output
min(ResponseSize) |
|---|
100 |
max
In this example, you use the command to display the maximum value (highest value) of the ResponseSize field.
Command
... | stats max(ResponseSize)
Output
max(ResponseSize) |
|---|
200 |
min with by parameter
In this example, you use the command to display the minimum value (smallest value) of the ResponseSize field, grouped by the ClientIp field. By running this command, you can understand the hosts from where minimum values are derived.
Command
... | stats min(ResponseSize)by ClientIp
Output
ClientIp | min(ResponseSize) |
|---|---|
10.1.1.141 | 100 |
10.1.1.140 | 100 |
min, max, and avg
In this example, you use the command to display the minimum (smallest), maximum (highest), and average of the ResponseSize field values.
Command
... | stats min(ResponseSize) max(ResponseSize), avg(ResponseSize)
Output
min(ResponseSize) | max(ResponseSize) | avg(ResponseSize) |
|---|---|---|
100 | 200 | 137.500 |
Notes
- If this command is preceded by a search command, the fields specified in the aggregate functions, sum and avg, must be of the numeric type. You can specify the numeric type when you create a data pattern.
- If the group by field has multiple values, the first value is considered for grouping.