Search commands > stats, chart, and timechart | Splunk (2024)

Thestats,chart, andtimechartcommands are great commands to know (especiallystats). 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 thestatscommand. 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 thestatscommand, 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 thehostfield 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 aseparaterowin 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 thestatscommand are referred to as <row-split> fields.

In this example, there are fiveactionsthat 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 theactionfield to the BYclause:

One big advantage of using thestatscommand 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 thechartcommand with the results produced by thestatscommand.

If you specify only one BY field, the results from thestatsandchartcommands are identical. Using thechartcommand 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 thechartcommand for thestatscommand in the search.

... | chart count BY status, host

The search returns the following results:

Thechartcommand uses the first BY field,status, to group the results. For each unique value in thestatusfield, the results appear on a separate row. This first BY field is referred to as the <row-split>field. Thechartcommand 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 thehostfield become the column labels.

Notice the results for the 403 status code in both results tables. With thestatscommand, there are no results forthe 403 status code andthe www1 and www3 hosts. With thechartcommand, 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 thestatsandchartcommands is how many fields you can specify in the BY clause.

With thestatscommand, you can specify a list of fields in the BY clause, all of which are <row-split> fields. The syntax for thestatscommand BY clause is:

BY <field-list>

For thechartcommand, you can specify at most two fields. One <row-split> field and one <column-split> field.

Thechartcommand 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 thechartcommand BY clause is:

[ BY <row-split> <column-split> ] | [ OVER <row-split> ] [BY <column-split>] ]

The advantage of using thechartcommand 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 theVisualizationtab to generate a graph from the results. Here is the visualization for thestatscommand results table:

Thestatusfield forms the X-axis, and thehostandcountfields form the data series. The range of count values form the Y-axis.

There are several problems with this chart:

1. There are multiple values for the same status code on the X-axis.
2. Thehostvalues (www1, www2, and www3) are string values and cannot be measured in the chart. Thehostshows 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 youcancreate a usable visualization from thestatscommand results table, the visualization is useful only when you specify one BY clause field.

It's better to use thechartcommand when you want to create a visualization using two BY clause fields:

Thestatusfield forms the X-axis and thehostvalues form the data series. The range of count values form the Y-axis.

What About the Timechart Command?

When you use thetimechartcommand, the results table is always grouped by the event timestamp (the_timefield). 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 thehostfield instead, this results table is produced:

The time increments that you see in the_timecolumn are based on the search time range or the arguments that you specify with thetimechartcommand. In the previous examples the time range was set toAll timeand there are only a few weeks of data. Because we didn't specify aspan, a default time span is used. In this situation, the default span is 1 day.

If you specify a time range likeLast 24 hours, the default time span is 30 minutes. TheUsagesection 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:

Thetimechartcommand 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 thetimechartcommand, which we'll explore in a separate blog.

So how do these results appear in a chart? On theVisualizationtab, you see that_timeforms 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.

• Usethe 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.

SPL it like you mean it - Laura

References

Other blogs:

• Search Command> stats, eventstats and streamstats

Splunk documentation:

• Stats command:https://docs.splunk.com/Documentation/Splunk/latest/SearchReference/Stats
• Chart command:https://docs.splunk.com/Documentation/Splunk/latest/SearchReference/Chart
• Timechart command:https://docs.splunk.com/Documentation/Splunk/latest/SearchReference/Timechart

----------------------------------------------------
Thanks!
Laura Stewart