timechart command usage

The timechart command is a transforming command, which orders the search results into a data table.

bins and span arguments

The timechart command accepts either the bins argument OR the span argument. If you specify both, only span is used. The bins argument is ignored.

If you do not specify either bins or span, the timechart command uses the default bins=100.

Default time spans

It you use the predefined time ranges in the time range picker, and do not specify the span argument, the following table shows the default span that is used.

Time range	Default span
Last 15 minutes	10 seconds
Last 60 minutes	1 minute
Last 4 hours	5 minutes
Last 24 hours	30 minutes
Last 7 days	1 day
Last 30 days	1 day
Previous year	1 month

Spans used when minspan is specified

When you specify a minspan value, the span that is used for the search must be equal to or greater than one of the span threshold values in the following table. For example, if you specify minspan=15m that is equivalent to 900 seconds. The minimum span that can be used is 1800 seconds, or 30 minutes.

Span threshold	Time equivalents
1 second
5 second
10 second
30 second
60 second	1 minute
300 second	5 minutes
600 second	10 minutes
1800 second	30 minutes
3600 seconds	1 hour
86400 seconds	1 day
2592000 seconds	30 days

Bin time spans and local time

The span option always rounds down the starting date for the first bin. There is no guarantee that the bin start time used by the timechart command corresponds to your local timezone. In part this is due to differences in daylight savings time for different locales. To use day boundaries, use span=1d. Do not use not span=24h, or span=1440m, or span=86400s.

Bin time spans versus per_* functions

The functions, per_day(), per_hour(), per_minute(), and per_second() are aggregation functions and are not responsible for setting a time span for the resultant chart. These functions are used to get a consistent scale for the data when an explicit span is not provided. The resulting span can depend on the search time range.

For example, per_hour() converts the field value so that it is a rate per hour, or sum(<hours in the span>). If your chart span ends up being 30m, it is sum()*2.

If you want the span to be 1h, you still have to specify the argument span=1h in your search.

You can calculate per_hour() on one field and per_minute(), or any combination of the functions, on a different field in the same search.

Split-by fields

If you specify a split-by field, ensure that you specify the bins and span arguments before the split-by field. If you specify these arguments after the split-by field, Splunk software assumes that you want to control the bins on the split-by field, not on the time axis.

You cannot use a field that you specify in a function as your split-by field. For example, you will not be able to run:

... | timechart sum(A) by A span=log2

However, you can work around this with an eval expression, for example:

... | eval A1=A | timechart sum(A) by A1 span=log2

Functions and memory usage

Some functions are inherently more expensive, from a memory standpoint, than other functions. For example, the distinct_count function requires far more memory than the count function. The values and list functions also can consume a lot of memory.

If you are using the distinct_count function without a split-by field or with a low-cardinality split-by by field, consider replacing the distinct_count function with the the estdc function (estimated distinct count). The estdc function might result in significantly lower memory usage and run times.

Lexicographical order

Lexicographical order sorts items based on the values used to encode the items in computer memory. In Splunk software, this is almost always UTF-8 encoding, which is a superset of ASCII.

• Numbers are sorted before letters. Numbers are sorted based on the first digit. For example, the numbers 10, 9, 70, 100 are sorted lexicographically as 10, 100, 70, 9.
• Uppercase letters are sorted before lowercase letters.
• Symbols are not standard. Some symbols are sorted before numeric values. Other symbols are sorted before or after letters.

You can specify a custom sort order that overrides the lexicographical order. See the blog Order Up! Custom Sort Orders.

Differences between SPL and SPL2

The <where-clause> is removed in the SPL2 syntax

The <where-clause>, from the <split-by-clause>, is removed in the SPL2 syntax. The where <agg-func-name> in top<N> can be achieved by using agg=<agg-func-name> limit=<int>.

Version	Example
SPL	...| timechart avg(foo) by host where sum in top5
SPL2	...| timechart agg=sum limit=5 avg(foo) by host

Some options only apply to the <split-by-clause> in SPL2

The useother option and other timechart options apply only to the split-by field and must be specified immediately after the split-by field.

Version	Example
SPL	...| timechart count() useother=false by host
SPL2	...| timechart count() by host useother=false

See also

timechart command

timechart command overview

timechart command syntax details

timechart command examples

Related information

Specifying time spans in the SPL2 Search Manual