timechart command: Overview and syntax
The SPL2 timechart command creates a time series chart with a corresponding table of statistics.
A timechart is a aggregation applied to a field to produce a chart, with time used as the X-axis. You can specify a split-by field, where each distinct value of the split-by field becomes a series in the chart.
Use these links to quickly navigate to the main sections in this topic:
Syntax
The required syntax is in bold.
timechart
[sep=<string>] [format=<string>] [partial=<boolean>] [cont=<boolean>] [fixedrange=<boolean>] [limit=<int>]
[agg=<aggregation>] [<bin-options>... ]
( (<single-aggregate> [BY <split-by-clause>] ) | (<eval-expression>) BY <split-by-clause> ) )
Required arguments
timechart command, you must specify either a <single-aggregate> or an <eval-expression> with a BY clause.single-aggregate
Syntax: count "(" ")" | <stats-function>"("<field>")"
Description: An aggregation applied to a single field, including an evaluated field. For <stats-function>, see stats-function in the Optional arguments section. No wildcards are allowed in the field name. A field must be specified, except when using the count() function, which applies to all events instead of a specific field.
eval-expression
Syntax: <math-expression> | <concatenation-expression> | <comparison-expression> | <boolean-expression> | <function>
Description: A combination of literals, fields, operators, and functions that represent the value of your field. For these evaluations to work, your field 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 values if they are both strings. When concatenating values with a period '+' the search treats both values as strings, regardless of their actual data type.
split-by-clause
Syntax: BY <field> [<timechart-options>]...
Description: A field to group the results by. If <field> is numerical, default discretization is applied. You can specify <timechart-options> to apply specific discretizations. You can only use one <split-by-clause>. See the Timechart options section.
Optional arguments
agg
Syntax: agg=( <stats-function> ( <field> ) [AS <field>] )
Description: A statistical aggregation function. See Quick Reference for SPL2 Stats and Charting Functions. The function can be applied to an eval expression, or to a field or set of fields. Use the AS clause to place the result into a new field with a name that you specify. You can use wild card characters in field names. With the limit and agg options, you can specify series filtering. If you set limit=0, no series filtering occurs.
bin-options
Syntax: bins | minspan | span | <start-end> | aligntime
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. For an explanation of these options, see the Bins options section in this topic.
Default: bins=100
cont
Syntax: cont=<boolean>
Description: Specifies whether the timechart is continuous or not. If set to true, any time gaps are filled in.
Default: true
fixedrange
Syntax: fixedrange=<boolean>
Description: Specifies whether or not to enforce the earliest and latest times of the search. Setting fixedrange=false allows the timechart command to constrict or expand to the time range covered by all events in the dataset.
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. The format option takes precedence over the sep option. You can 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. With the limit and agg options, you can specify series filtering. If you set limit=0, no series filtering occurs and 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 the 'OTHER' field, 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' takes precedence over 'bar', which takes precedence over 'foo'. See timechart command: Usage.
partial
Syntax: partial=<boolean>
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>$VAL$.
stats-function
Syntax: The syntax depends on the function that you use.
Description: Statistical functions that you can use with the timechart command. Each time you invoke the timechart command, you can use one or more functions. See timechart command: Usage.
For a list and description of the supported statistical and charting functions, see Quick Reference for SPL2 Stats and Charting Functions.
Bins 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. See timechart command: Usage.
span
Syntax: span=<log-span> | span=<span-length> | span=<snap-to-time>
Description: Sets the size of each bin, using either a log-based span, a span length based on time, or a span that snaps to a specific time. For descriptions of each of these options, see the Span options section. For more information about specifying spans, see Specifying time spans in the SPL2 Search Manual.
The starting time of a bin might not match your local timezone. See timechart command: Usage.
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.
aligntime
Syntax: aligntime=(earliest | latest | <time-specifier>)
Description: Align the bin times to something other than base UNIX time (epoch 0). The aligntime option is valid only when doing a time-based discretization. Ignored if span is in days, months, or years.
Span options
log-span
Syntax: [<num>]log[<num>]
Description: Sets a 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 < the 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: Timescale units.
Default: <sec>
| Timescale | Valid 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 |
| <week> | w | week | weeks | Time scale in weeks |
| <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) |
snap-to-time
Syntax: [+|-] [<time_integer>] <relative-time-unit>@<snap-to-time-unit>
Description: A span of each bin, based on a relative time unit and a snap to time unit. The <snap-to-time> must include the <relative-time-unit>, the @ symbol, and the <snap-to-time-unit>. The offset, represented by the plus (+) or minus (-) is optional. If the <time_integer> is not specified, 1 is the default. For example if you specify w as the <relative-time-unit>, 1 week is assumed.
snap-to-time option is only used with the week timescale unit. It cannot be used with other timescale units such as minutes or quarters.Timechart options
The <timechart-options> are part of the <split-by-clause> and must be specified after the BY keyword. See the Required arguments section.
timechart-options
Syntax: <bin-options> | usenull=<bool> | useother=<bool> | nullstr=<string> | otherstr=<string>
Description: Timechart options for controlling the behavior of splitting by a field. See the Bins options section.
nullstr
Syntax: nullstr=<string>
Description: If usenull=true, specifies the label for the series that is created for events that do not contain the split-by field.
Default: NULL
otherstr
Syntax: otherstr=<string>
Description: If useother=true, specifies the label for the series that is created in the table and the graph.
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. The label for the series is controlled by the nullstr option.
Default: true
useother
Syntax: useother=<bool>
Description: You specify which series to include in the results table by using the agg and limit options. The useother option specifies whether to merge all of the series not included in the results table into a single new series. If useother=true, the label for the series is controlled by the otherstr option.
Default: true
See also
Related information