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.
The values displayed in the table of statistics and the bars displayed in the chart are clickable. When you click a value in the table, the tabular view is toggled to the search results view and events associated with those values are displayed.
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.
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 a field name as an argument and returns the number of occurrences of that field in the search results.
Sum
sum (<field>)
Uses a field name as an argument and returns the sum of values of that field in the search results.
Average
avg (<field>)
Uses a field name as an argument and returns the average of values of that field in the search results.
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
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
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 |
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.
Related topic