Search commands > stats, chart, and timechart
The stats, chart, and timechart commands are great commands to know (especially stats). When I first started learning about the Splunk search commands, I found it challenging to understand the benefits of each command, especially how the BY clause impacts the output of a search. It wasn't until I did a comparison of the output (with some trial and a whole lotta error) that I was able to understand the differences between the commands.
These three commands are transforming commands. A transforming command takes your event data and converts it into an organized results table. You can use these three commands to calculate statistics, such as count, sum, and average.
Note: The BY keyword is shown in these examples and in the Splunk documentation in uppercase for readability. You can use uppercase or lowercase in your searches when you specify the BY keyword.
The Stats Command Results Table
Let's start with the stats command. We are going to count the number of events for each HTTP status code.
... | stats count BY status
The count of the events for each unique status code is listed in separate rows in a table on the Statistics tab:
Basically the field values (200, 400, 403, 404) become row labels in the results table.
For the stats command, fields that you specify in the BY clause group the results based on those fields. For example, we receive events from three different hosts: www1, www2, and www3. If we add the host field to our BY clause, the results are broken out into more distinct groups.
... | stats count BY status, host
Each unique combination of status and host is listed on a separate row in the results table.
Each field you specify in the BY clause becomes a separate column in the results table. You're splitting the rows first on status, then on host. The fields that you specify in the BY clause of the stats command are referred to as <row-split> fields.
In this example, there are five actions that customers can take on our website: addtocart, changequantity, purchase, remove, and view.
Let's add action to the search.
... | stats count BY status, host, action
You are splitting the rows first on status, then on host, and then on action. Below is a partial list of the results table that is produced when we add the action field to the BY clause:
One big advantage of using the stats command is that you can specify more than two fields in the BY clause and create results tables that show very granular statistical calculations.
Chart Command Results Table
Using the same basic search, let's compare the results produced by the chart command with the results produced by the stats command.
If you specify only one BY field, the results from the stats and chart commands are identical. Using the chart command in the search with two BY fields is where you really see differences.
Remember the results returned when we used the stats command with two BY fields are:
Now let's substitute the chart command for the stats command in the search.
... | chart count BY status, host
The search returns the following results:
The chart command uses the first BY field, status, to group the results. For each unique value in the status field, the results appear on a separate row. This first BY field is referred to as the <row-split> field. The chart command uses the second BY field, host, to split the results into separate columns. This second BY field is referred to as the <column-split> field. The values for the host field become the column labels.
Notice the results for the 403 status code in both results tables. With the stats command, there are no results for the 403 status code and the www1 and www3 hosts. With the chart command, when there are no events for the <column-split> field that contain the value for the <row-split> field, a 0 is returned.
One important difference between the stats and chart commands is how many fields you can specify in the BY clause.
With the stats command, you can specify a list of fields in the BY clause, all of which are <row-split> fields. The syntax for the stats command BY clause is:
BY <field-list>
For the chart command, you can specify at most two fields. One <row-split> field and one <column-split> field.
The chart command provides two alternative ways to specify these fields in the BY clause. For example:
... | chart count BY status, host
... | chart count OVER status BY host
The syntax for the chart command BY clause is:
[ BY <row-split> <column-split> ] | [ OVER <row-split> ] [BY <column-split>] ]
The advantage of using the chart command is that it creates a consolidated results table that is better for creating charts. Let me show you what I mean.
Stats and Chart Command Visualizations
When you run the stats and chart commands, the event data is transformed into results tables that appear on the Statistics tab. Click the Visualization tab to generate a graph from the results. Here is the visualization for the stats command results table:
The status field forms the X-axis, and the host and count fields form the data series. The range of count values form the Y-axis.
There are several problems with this chart:
- There are multiple values for the same status code on the X-axis.
- The host values (www1, www2, and www3) are string values and cannot be measured in the chart. The host shows up in the legend, but there are no blue columns in the chart.
Because of these issues, the chart is confusing and does not convey the information that is in the results table.
While you can create a usable visualization from the stats command results table, the visualization is useful only when you specify one BY clause field.
It's better to use the chart command when you want to create a visualization using two BY clause fields:
The status field forms the X-axis and the host values form the data series. The range of count values form the Y-axis.
What About the Timechart Command?
When you use the timechart command, the results table is always grouped by the event timestamp (the _time field). The time value is the <row-split> for the results table. So in the BY clause, you specify only one field, the <column-split> field. For example, this search generates a count and specifies the status field as the <column-split> field:
... | timechart count BY status
This search produces this results table:
If you search by the host field instead, this results table is produced:
The time increments that you see in the _time column are based on the search time range or the arguments that you specify with the timechart command. In the previous examples the time range was set to All time and there are only a few weeks of data. Because we didn't specify a span, a default time span is used. In this situation, the default span is 1 day.
If you specify a time range like Last 24 hours, the default time span is 30 minutes. The Usage section in the timechart documentation specifies the default time spans for the most common time ranges. This results table shows the default time span of 30 minutes:
The timechart command includes several options that are not available with the stats and chart commands. For example, you can specify a time span like we have in this search:
... | timechart span=12h count BY host
In this example, the 12-hour increments in the results table are based on when you run the search (local time) and how that aligns that with UNIX time (sometimes referred to as epoch time).
Note: There are other options you can specify with the timechart command, which we'll explore in a separate blog.
So how do these results appear in a chart? On the Visualization tab, you see that _time forms the X-axis. The axis marks the Midnight and Noon values for each date. However, the columns that represent the data start at 1700 each day and end at 0500 the next day.
The field specified in the BY clause forms the data series. The range of count values forms the Y-axis.
In Summary
The stats, chart, and timechart commands have some similarities, but you’ve got to pay attention to the BY clauses that you use with them.
- Use the stats command when you want to create results tables that show granular statistical calculations.
- Use the stats command when you want to specify 3 or more fields in the BY clause.
- Use the chart command when you want to create results tables that show consolidated and summarized calculations.
- Use the chart command to create visualizations from the results table data.
- Use the timechart command to create results tables and charts that are based on time.
References
Other blogs:
Splunk documentation: