timechart command usage
The timechart command is a transforming command, which orders the search results into a data table.
bins and span arguments
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
timechart command uses the default
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|
|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
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
Bin time spans versus per_* functions
per_second() are aggregator 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.
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
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.
If you specify a split-by field, ensure that you specify the
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
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 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
|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
useother option and other timechart options apply only to the split-by field and must be specified immediately after the split-by field.
|SPL||...| timechart count() useother=false by host|
|SPL2||...| timechart count() by host useother=false|
timechart command syntax details
timechart command examples
This documentation applies to the following versions of Splunk® Cloud Services: current