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.
For a list of all search commands, see Search commands.
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.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
... | 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.
... | stats count(events) as Count, sum(bytes-read) as Total by HOST
... | stats sum(ResponseSize), avg(ResponseSize) by ClientIp
... | stats min(ResponseSize), max(ResponseSize), avg(ResponseSize) by ClientIp
The following sample data and sample indexed data (displayed on the Search tab) will help you understand the examples of using the stats
command.
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 |
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 |
In this example, you use the command to display the number of occurrences of the RequestType field.
... | stats count(RequestType)
count(RequestType) |
---|
4 |
In this example, you use the command to display the number of occurrences of the RequestType field, grouped by the ClientIp field.
... | stats count(RequestType) by ClientIp
ClientIp | count(RequestType) |
---|---|
10.1.1.141 | 2 |
10.1.1.140 | 2 |
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.
... | stats sum(ResponseSize), avg(ResponseSize) by ClientIp
ClientIp | sum(ResponseSize) | avg(ResponseSize) |
---|---|---|
10.1.1.141 | 300 | 150 |
10.1.1.140 | 250 | 125 |
In this example, you use the command to display the minimum value (smallest value) of the ResponseSize field.
... | stats min(ResponseSize)
min(ResponseSize) |
---|
100 |
In this example, you use the command to display the maximum value (highest value) of the ResponseSize field.
... | stats max(ResponseSize)
max(ResponseSize) |
---|
200 |
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.
... | stats min(ResponseSize)by ClientIp
ClientIp | min(ResponseSize) |
---|---|
10.1.1.141 | 100 |
10.1.1.140 | 100 |
In this example, you use the command to display the minimum (smallest), maximum (highest), and average of the ResponseSize field values.
... | stats min(ResponseSize) max(ResponseSize), avg(ResponseSize)
min(ResponseSize) | max(ResponseSize) | avg(ResponseSize) |
---|---|---|
100 | 200 | 137.500 |
sum
and avg
, must be of the numeric type. You can specify the numeric type when you create a data pattern. by
field has multiple values, the first value is considered for grouping.