Feedback:

timechart

Use the timechart operator to perform aggregations over timespans.

Syntax

|timechart <aggr_func> [as new_field] by [<field_to_split_aggregate>] [span=<interval_with_time_unit>] [limit=<number_of_columns>] [makecontinuous=<create_empty_buckets>] [addtotals=<aggregate_totals>]

<aggr_func> Required. Specify a function to calculate statistics. For example, avg, count, count(distinct <field>), max, min, sum.
<field_to_split_aggregate> Optional. Specify the field you want to aggregate. Each distinct value of the split-by field becomes a series in the chart. For example, you can split and aggregate on sourcetype to understand event trends for a particular data source over a specific interval.

<interval_with_time_unit>

Optional. Specify the time interval for the split. Multiple units are not allowed for week, month, or year. In other words, specify 1 as the interval integer when using week, month, or year.

Possible values:

s: time interval in seconds

m: time interval in minutes

h: time interval in hours

d: time interval in days

w: time interval in weeks

mon: time interval in months

y: time interval in years

For example, span = 1h splits and aggregates data in one hour time buckets.

<number_of_columns>

Optional. Specify how many columns will be displayed in the results table. When using <by field> in the AQL query, if there are more values than the specified limit, the results that exceed the limit will be grouped in an additional column called others.

Default: 10.
<create_empty_buckets>

Optional. Specify whether to create empty buckets for the time range and span that contains no data. Possible values:

  • true: empty buckets are created for periods in the selected time range that have no data. Applicable to time units: s (second), m (minute), h (hour), and d (day).

  • false: no empty buckets are created for time range periods with no data.

Default: false.
<aggregate_totals>

Optional. When using <by field> in the AQL query, specify whether to display the total for a field that is aggregated across the specified time range, bucketed by the split interval. Useful for comparing entities and spotting volume trends, without needing a separate aggregation query.

When set to true, it automatically appends a new total row and column to the search results such that:

  • the total row aggregates the specified field across the full time range.

  • the total column is a sum across all values of the specified field.

For example, setting addtotals=true on sourcetype for span=1h adds a row that is an aggregate across the full time range per sourcetype and a column that is a sum across all sourcetypes for each row.

Usage

The timechart operator can be used to aggregate data for 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.

Note: After you issue a search with timechart, the value for span may be recalculated and rationalized to create meaningful buckets given the configured time range. Specify makecontinuous=true to create empty buckets for time periods with no data, for time units in s (seconds), m (minutes), h (hours), or d (days).

Examples

Example 1: Counts events over time, grouped by sourcetype.

Copy 
| timechart count as cnt by sourcetype

Example 2: Counts events per hour, grouped by sourcetype.

Copy 
| timechart count by sourcetype span=1h

Example 3: Counts events over time, showing only the top five sourcetypes, with others grouped.

Copy 
| timechart count by sourcetype limit=5

Example 4: Filter AWS CloudTrail logs and chart hourly event counts with continuous time buckets.

Copy 
| where sourcetype contains_ci 'aws_cloudtrail' | timechart count by sourcetype span=1h makecontinuous=true

Example 5: Count hosts per source type in hourly buckets, creating the total row and column to summarize across all source types and time periods.

Copy 
| timechart count(host) as devicecount by sourcetype span=1h addtotals=true

Example 6: Create a time chart showing OCSF network activity trends.

ocsf | where class_name = "Network Activity" | timechart count by connection_info.protocol_name span=1h

Example 7: Generates an hourly time series chart of OCSF event counts for the top 5 products.

Copy 
ocsf | timechart count by metadata.product.name span=1h limit=5