Splunk® Enterprise

Search Reference

Download manual as PDF

Download topic as PDF

timechart

Description

Creates a time series chart with corresponding table of statistics. The timechart is a statistical aggregation applied to a field, with time as the x-axis. You can specify a split-by field so that each distinct value of the split-by field is a series. If you use an eval expression, the split-by clause is required. With the limit and agg options, you can specify series filtering. These options are ignored if you specify an explicit where-clause. If you set limit=0, no series filtering occurs.

Syntax

timechart [sep=<string>] [format=<string>] [partial=<bool>] [cont=<bool>] [limit=<int>] [agg=<stats-agg-term>] [<bin-options>... ] ( (<single-agg> [BY <split-by-clause>] ) | (<eval-expression>) BY <split-by-clause> )

Required arguments

When specifying timechart arguments, either <single-agg> or <eval-expression> BY <split-by-clause> is required.

eval-expression
Syntax: <math-exp> | <concat-exp> | <compare-exp> | <bool-exp> | <function-call>
Description: A combination of literals, fields, operators, and functions that represent the value of your destination field. For these evaluations to work, your values need to be valid for the type of operation. For example, with the exception of addition, arithmetic operations might not produce valid results if the values are not numerical. Additionally, the search can concatenate the two operands if they are both strings. When concatenating values with a period '.' the search treats both values as strings, regardless of their actual data type.
single-agg
Syntax: count | <stats-func>(<field>)
Description: A single aggregation applied to a single field, including an evaluated field. No wildcards are allowed. The field must be specified, except when using the count aggregator which applies to events as a whole.
split-by-clause
Syntax: <field> (<tc-options>)... [<where-clause>]
Description: Specifies a field to split the results by. If field is numerical, default discretization is applied. Discretization is defined with the tc-options. Use the <where-clause> to specify the number of columns to include. See the tc options and the where clause sections in this topic.

Optional arguments

agg=<stats-agg-term>
Syntax: <stats-agg-term>
Description: See the Stats functions section below. For a list of stats functions with descriptions and examples, see Statistical and charting functions in this manual.
bin-options
Syntax: bins | minspan | span | <start-end>
Description: Options that you can use to specify discreet bins, or groups, to organize the information. The bin-options set the maximum number of bins, not the target number of bins. See the Bin options section in this topic.
Default: bins=100
cont
Syntax: cont=<bool>
Description: Specifies whether the chart is continuous or not. If set to true, the Search application fills in the time gaps.
Default: true
fixedrange
Syntax: fixedrange=<bool>
Description: (Not valid for 4.2) Specify whether or not to enforce the earliest and latest times of the search. Setting fixedrange=false allows the timechart command to constrict to just the time range with valid data.
Default: true
format
Syntax: format=<string>
Description: Used to construct output field names when multiple data series are used in conjunction with a split-by-field. format takes precedence over sep and allows you to specify a parameterized expression with the stats aggregator and function ($AGG$) and the value of the split-by-field ($VAL$).
limit
Syntax: limit=<int>
Description: Specifies a limit for the number of distinct values of the split-by field to return. If set to limit=0, all distinct values are used. Setting limit=N keeps the N highest scoring distinct values of the split-by field. All other values are grouped into 'OTHER', as long as useother is not set to false. The scoring is determined as follows:
  • If a single aggregation is specified, the score is based on the sum of the values in the aggregation for that split-by value. For example, for timechart avg(foo) BY <field> the avg(foo) values are added up for each value of <field> to determine the scores.
  • If multiple aggregations are specified, the score is based on the frequency of each value of <field>. For example, for timechart avg(foo) max(bar) BY <field>, the top scoring values for <field> are the most common values of <field>.


Ties in scoring are broken lexicographically, based on the value of the split-by field. For example, 'BAR' take precedence over 'bar', which takes precedence over 'foo'. See Usage.
partial
Syntax: partial=<bool>
Description: Controls if partial time bins should be retained or not. Only the first and last bin can be partial.
Default: True. Partial time bins are retained.
sep
Syntax: sep=<string>
Description: Used to construct output field names when multiple data series are used in conjunctions with a split-by field. This is equivalent to setting format to $AGG$<sep>$VALUE$.

Stats options

stats-agg-term
Syntax: <stats-function> ( <evaled-field> | <wc-field> ) [AS <wc-field>]
Description: A statistical aggregation function. Use the AS clause to place the result into a new field with a name that you specify. The function can be applied to an eval expression, or to a field or set of fields. You can use wild card characters in field names.
stats-function
Syntax: avg() | c() | count() | dc() | distinct_count() | earliest() | estdc() | estdc_error() | exactperc<int>() | first() | last() | latest() | list() | max() | median() | min() | mode() | p<int>() | perc<int>() | per_day() | per_hour() | per_minute() | per_second() |range() | stdev() | stdevp() | sum() | sumsq() | upperperc<int>() | values() | var() | varp()
Description: Functions you can use with the timechart command. Each time you invoke the timechart command, you can specify one or more functions. However, you can specify only one BY clause. For descriptions and examples of these functions, see Statistical and charting functions.

Bin options

bins
Syntax: bins=<int>
Description: Sets the maximum number of bins to discretize into. This does not set the target number of bins. It finds the smallest bin size that results in no more than N distinct bins. Even though you specify a number such as 300, the resulting number of bins might be much lower.
Default: 100
minspan
Syntax: minspan=<span-length>
Description: Specifies the smallest span granularity to use automatically inferring span from the data time range.
span
Syntax: span=<log-span> | span=<span-length>
Description: Sets the size of each bin, using a span length based on time or log-based span.
<start-end>
Syntax: end=<num> | start=<num>
Description: Sets the minimum and maximum extents for numerical bins. Data outside of the [start, end] range is discarded.

Span options

<log-span>
Syntax: [<num>]log[<num>]
Description: Sets to log-based span. The first number is a coefficient. The second number is the base. If the first number is supplied, it must be a real number >= 1.0 and < base. Base, if supplied, must be real number > 1.0 (strictly greater than 1).
span-length
Syntax: <int>[<timescale>]
Description: A span of each bin, based on time. If the timescale is provided, this is used as a time range. If not, this is an absolute bin length.
<timescale>
Syntax: <sec> | <min> | <hr> | <day> | <week> | <month> | <subseconds>
Description: Time scale units.
Time scale Syntax Description
<sec> s | sec | secs | second | seconds Time scale in seconds.
<min> m | min | mins | minute | minutes Time scale in minutes.
<hr> h | hr | hrs | hour | hours Time scale in hours.
<day> d | day | days Time scale in days.
<month> mon | month | months Time scale in months.
<subseconds> us | ms | cs | ds Time scale in microseconds (us), milliseconds (ms), centiseconds (cs), or deciseconds (ds)

tc options

The <tc-option> is part of the <split-by-clause>.

tc-option
Syntax: <bin-options> | usenull=<bool> | useother=<bool> | nullstr=<string> | otherstr=<string>
Description: Options for controlling the behavior of splitting by a field.
bin-options
See the Bin options section in this topic.
nullstr
Syntax: nullstr=<string>
Description: If usenull is true, this series is labeled by the value of the nullstr option.
Default: NULL
otherstr
Syntax: otherstr=<string>
Description: If useother is True, this series is labeled by the value of the otherstr option.
Default: OTHER
usenull
Syntax: usenull=<bool>
Description: Controls whether or not a series is created for events that do not contain the split-by field.
useother
Syntax: useother=<bool>
Description: Specifies if a series should be added for data series not included in the graph because they did not meet the criteria of the <where-clause>.
Default: True

where clause

The <where-clause> is part of the <split-by-clause>.

where clause
Syntax: <single-agg> <where-comp>
Description: Specifies the criteria for including particular data series when a field is given in the tc-by-clause. The most common use of this option is to select for spikes rather than overall mass of distribution in series selection. The default value finds the top ten series by area under the curve. Alternately one could replace sum with max to find the series with the ten highest spikes.This has no relation to the where command.
<where-comp>
Syntax: <wherein-comp> | <wherethresh-comp>
Description: A criteria for the where clause.
<wherein-comp>
Syntax: (in | notin) (top | bottom)<int>
Description: A where-clause criteria that requires the aggregated series value be in or not in some top or bottom grouping.
<wherethresh-comp>
Syntax: (< | >)( )?<num>
Description: A where-clause criteria that requires the aggregated series value be greater than or less than some numeric threshold.

Usage

bins and span arguments

The timechart command accepts either the bins argument OR the span argument. 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

(Thanks to Splunk users MuS and Martin Mueller for their help in compiling this default time span information.)

Bin time spans versus per_* functions

The functions, per_day(), per_hour(), per_minute(), and 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.

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.

Note: You can do 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.

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

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

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

... | eval A1=A | chart 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.

Basic Examples

1. Chart the product of the average "CPU" and average "MEM" for each "host"

For each minute, compute the product of the average "CPU" and average "MEM" for each "host".

... | timechart span=1m eval(avg(CPU) * avg(MEM)) BY host

2. Chart the average of cpu_seconds by processor

Create a timechart of the average of cpu_seconds by processor, rounded to 2 decimal places.

... | timechart eval(round(avg(cpu_seconds),2)) BY processor

3. Chart the average of "CPU" for each "host"

For each minute, calculate the average value of "CPU" for each "host".

... | timechart span=1m avg(CPU) BY host

4. Chart the average "cpu_seconds" by "host" and remove outlier values

Calculate the average "cpu_seconds" by "host". Remove outlying values that might distort the timechart axis.

... | timechart avg(cpu_seconds) BY host | outlier action=tf

5. Chart the average "thruput" of hosts over time

... | timechart span=5m avg(thruput) BY host

6. Chart the eventypes by "source_ip" where the count is greater than 10

For each minute, count the eventypes by "source_ip", where the count is greater than 10.

sshd failed OR failure | timechart span=1m count(eventtype) BY source_ip usenull=f WHERE count>10

Extended Examples

1. Chart revenue for the different products that were purchased yesterday

This example uses the sample dataset from the Search Tutorial and a field lookup to add more information to the event data. Before you run this example:

The original data set includes a productId field that is the catalog number for the items sold at the Buttercup Games online store. The field lookup adds two new fields to your events: product_name, which is a descriptive name for the item, and price, which is the cost of the item.

Chart revenue for the different products that were purchased yesterday.

sourcetype=access_* action=purchase | timechart per_hour(price) by productName usenull=f useother=f

This example searches for all purchase events (defined by the action=purchase) and pipes those results into the timechart command. The per_hour() function sums up the values of the price field for each item (product_name) and bins the total for each hour of the day.

This produces the following table of results in the Statistics tab.

6.0 timechart ex1.1.png


View and format the report in the Visualizations tab. Here, it's formatted as a stacked column chart over time.

6.0 timechart ex1.2.png

After you create this chart, you can position your mouse pointer over each section to view more metrics for the product purchased at that hour of the day. Notice that the chart does not display the data in hourly spans. Because a span is not provided (such as span=1hr), the per_hour() function converts the value so that it is a sum per hours in the time range (which in this example is 24 hours).

2. Chart the number of purchases made daily for each type of product

This example uses the sample dataset from the Search Tutorial and a field lookup to add more information to the event data. Before you run this example, download the data set from this topic in the Search Tutorial and follow the instructions to upload it to your Splunk deployment.

Chart the number of purchases made daily for each type of product.

sourcetype=access_* action=purchase | timechart span=1d count by categoryId usenull=f

This example searches for all purchases events (defined by the action=purchase) and pipes those results into the timechart command. The span=1day argument buckets the count of purchases over the week into daily chunks. The usenull=f argument means "ignore any events that contain a NULL value for categoryId."

This produces the following table of results in the Statistics tab.

6.0 timechart ex2.1.png


View and format the report in the Visualizations tab. Here, it's formatted as a column chart over time.

6.0 timechart ex2.2.png


Compare the number of different items purchased each day and over the course of the week. It looks like day-to-day, the number of purchases for each item does not vary significantly.

3. Count the total revenue made for each item sold at the shop over the course of the week

This example uses the sample dataset from the Search Tutorial and a field lookup to add more information to the event data. Before you run this example:

The original data set includes a productId field that is the catalog number for the items sold at the Buttercup Games online store. The field lookup adds two new fields to your events: product_name, which is a descriptive name for the item, and price, which is the cost of the item.

Count the total revenue made for each item sold at the shop over the course of the week. This examples shows two ways to do this.

1. This first search uses the span argument to bucket the times of the search results into 1 day increments. Then uses the sum() function to add the price for each product_name.

sourcetype=access_* action=purchase | timechart span=1d sum(price) by product_name usenull=f

2. This second search uses the per_day() function to calculate the total of the price values for each day.

sourcetype=access_* action=purchase | timechart per_day(price) by product_name usenull=f

Both searches produce the following results table in the Statistics tab.

6.0 timechart ex3.1.png


View and format the report in the Visualizations tab. Here, it's formatted as a column chart over time.

6.0 timechart ex3.2.png


Now you can compare the total revenue made for items purchased each day and over the course of the week.

4. Chart product views and purchases for a single day

This example uses the sample dataset from the Search Tutorial. Download the data set from this topic in the Search Tutorial and follow the instructions to upload it to your Splunk deployment. Then, run this search using the Preset time range "Yesterday" or "Last 24 hours".

Chart a single day's views and purchases at the Buttercup Games online store.

sourcetype=access_* | timechart per_hour(eval(method="GET")) AS Views, per_hour(eval(action="purchase")) AS Purchases

This search uses the per_hour() function and eval expressions to search for page views (method=GET) and purchases (action=purchase). The results of the eval expressions are renamed as Views and Purchases, respectively.

This produces the following results table in the Statistics tab.

6.0 timechart ex4.1.png

View and format the report in the Visualizations tab. Here, it's formatted as an area chart.

6.0 timechart ex4.2.png


The difference between the two areas indicates that all the views did not lead to purchases. If all views lead to purchases, you would expect the areas to overlay atop each other completely so that there is no difference between the two areas.

Where clause Examples

These examples use the where clause to control the number of series values returned in the time-series chart.

Example 1: Show the 5 most rare series based on the minimum count values. All other series values will be labeled as "other".

index=_internal | timechart span=1h count by source WHERE min in bottom5

Example 2: Show the 5 most frequent series based on the maximum values. All other series values will be labeled as "other".

index=_internal | timechart span=1h count by source WHERE max in top5

These two searches return six data series: the five top or bottom series specified and the series labeled other. To hide the "other" series, specify the argument useother=f.

Example 3: Show the source series count of INFO events, but only where the total number of events is larger than 100. All other series values will be labeled as "other".

index=_internal | timechart span=1h sum(eval(if(log_level=="INFO",1,0))) by source WHERE sum > 100


Example 4: Using the where clause with the count function measures the total number of events over the period. This yields results similar to using the sum function.

The following two searches returns the sources series with a total count of events greater than 100. All other series values will be labeled as "other".

index=_internal | timechart span=1h count by source WHERE count > 100

index=_internal | timechart span=1h count by source WHERE sum > 100

See also

bin, chart, sitimechart

Answers

Have questions? Visit Splunk Answers and see what questions and answers the Splunk community has using the timechart command.

PREVIOUS
tail
  NEXT
timewrap

This documentation applies to the following versions of Splunk® Enterprise: 6.0, 6.0.1, 6.0.2, 6.0.3, 6.0.4, 6.0.5, 6.0.6, 6.0.7, 6.0.8, 6.0.9, 6.0.10, 6.0.11, 6.0.12, 6.0.13, 6.0.14, 6.1, 6.1.1, 6.1.2, 6.1.3, 6.1.4, 6.1.5, 6.1.6, 6.1.7, 6.1.8, 6.1.9, 6.1.10, 6.1.11, 6.1.12, 6.1.13, 6.2.0, 6.2.1, 6.2.2, 6.2.3, 6.2.4, 6.2.5, 6.2.6, 6.2.7, 6.2.8, 6.2.9, 6.2.10, 6.2.11, 6.2.12, 6.2.13, 6.3.0, 6.3.1, 6.3.2, 6.3.3, 6.3.4, 6.3.5, 6.3.6, 6.3.7, 6.3.8, 6.3.9, 6.3.10, 6.3.11, 6.4.0, 6.4.1, 6.4.2, 6.4.3, 6.4.4, 6.4.5, 6.4.6, 6.4.7, 6.4.8, 6.5.0, 6.5.1, 6.5.1612 (Splunk Cloud only), 6.5.2, 6.5.3, 6.5.4, 6.5.5, 6.6.0, 6.6.1, 6.6.2, 6.6.3, 7.0.0


Comments

Rjthibod
Thank you for pointing this out. I corrected the text.

Lstewart splunk, Splunker
April 7, 2017

I think there is an error in the documentation for "format". The references to variable "$VALUE$" should be replaced by "$VAL$". Using "$VALUE$" results in errors in Splunk.

Rjthibod
April 1, 2017

How is the x-axis interval (not span) set by time period? I want to see tick marks and annotations hourly or daily.

Landen99
May 18, 2015

Is there a way to specify the chart properties in the search syntax? For instance, to set the time chart to display as a connected line chart with y-max at 10 and y-min at 0? Are there timechart options in the search line to set the scale to log or to set the colors of each series? I know that we can manually go in each time and set the chart to display according to our preferences, but I would like a way to ensure that the chart looks the right way from the start without all that extra work, and to ensure that the pdf attached to email reports displays the chart in the right way (the pdf chart cannot be configured after it has been generated and sent).

Landen99
February 3, 2015

How do you change the timechart labels? Example: line graph of scrip traffic over time, when you hover over the line graph, the srcip pops up...how can I configure the label there to display additional information such as action, ports, etc? Thanks.

Mzlnsoccer
December 31, 2014

Default for `sep` is colon (:). As much as possible, I'd like to see default mentioned in doc when default is set.

Yuanliu
November 21, 2014

Looking for a time chart example to show how to graph common week over week or month over month tasks?

Daniel333
August 28, 2014

Was this documentation topic helpful?

Enter your email address, and someone from the documentation team will respond to you:

Please provide your comments here. Ask a question or make a suggestion.

You must be logged into splunk.com in order to post comments. Log in now.

Please try to keep this discussion focused on the content covered in this documentation topic. If you have a more general question about Splunk functionality or are experiencing a difficulty with Splunk, consider posting a question to Splunkbase Answers.

0 out of 1000 Characters