timestats ​

The timestats operator aggregates events by time periods or bins.

Syntax ​

You can define either span or numBins, not both. If you define neither, this operator will automatically compute a suitable time span based on the search’s time range.

Arguments ​

• Time: Time period. Supports these relative times - s[econds], m[inutes], h[ours], d[ays], w[eeks], mon[ths], and y[ears]. Values without units get interpreted as seconds. For example, 1 = 1s.
• SnapToTime: Round down (backward) to the nearest instance of Time. Append the @ modifier, followed by the same or more granular Time. For example,
  • 1d@d snaps back to the beginning of today, 12:00 AM (midnight) in the selected timezone.
  • 1d@h snaps to 4:00 PM the next day if it’s currently 4:00 PM.
• Bins: Numeric literal, desired number of bins. Bins are split as close as possible based on the search’s time range.
• TimeSource: String. Name of the time field to use for aggregation. Defaults to _time. The field needs to have time in seconds.
• TimeLabel: String. Name of the output time field. Defaults to the same field as TimeSource.
• FieldName: String. Name to give to the field with the results created by Aggregation.
• Aggregation: Cribl and statistical functions. Wildcards are not supported for field names in aggregation functions.
• GroupExpression: A scalar expression that can reference the input data. The output will have as many events as there are distinct values of all the group expressions. After each expression, you can optionally add asc or desc, and nulls first or nulls last, to control the order of output rows (see Group-by Sort Order).

Group-by Sort Order ​

In summarize, eventstats, and timestats, you can specify sort direction and null placement directly on each field in the by clause, instead of using a separate order or sort operator after the aggregation.

After each grouping expression, you can specify:

• asc or desc: Sort direction for that group-by field.
• nulls first or nulls last: Whether null values for that field sort before or after non-null values.

You can combine direction and null placement on each field independently. For example, instead of:

| summarize cnt=count() by tenantId, workspace
| order by tenantId asc, workspace asc

you can write:

| summarize cnt=count() by tenantId asc, workspace asc

The asc, desc, nulls first, and nulls last keywords use the same meaning as in the order operator (including sorting rules).

Results ​

In Dashboards, aggregations in child searches are based on the parent search’s results, so if the parent search’s results are capped by a system limit (such as max_results_per_search / Results limit), the child search’s aggregations may be incomplete.

Examples ​

• Create two fields per host in the format Host:totalWaitTime and Host:avgResponseTime, showing the aggregates for the time-bins (rows) of one minute:

  timestats span=1m totalWaitTime=sum(responseTime), avgResponseTime=avg(responseTime) by host

  Copy

• Create roughly 42 time bins, labeled as when, and create output fields in the form srcaddr:totalRequest and dstaddr:totalRequest:

  dataset="cribl_search_sample"
  | timestats timeLabel="when" numBins=42 totalRequest=count() by srcaddr, dstaddr

  Copy Run in Cribl Search

• Aggregate time durations by interface, bin every minute:

  dataset="cribl_search_sample" 
  | timestats span=1m totalTime=sum(end-start) by interface

  Copy Run in Cribl Search

• Count events over time, bin every minute:

  dataset=$vt_dummy event<600 
  | extend _time=_time-rand(600) 
  | timestats span=1m count()

  Copy Run in Cribl Search

• Count events over time, using the timeSource option:

  dataset=$vt_dummy event<600 
  | extend rando=_time-rand(600) 
  | timestats span=1m timeSource=rando count()

  Copy Run in Cribl Search

• Count events over time, split by the field method, bin every minute:

  dataset=$vt_dummy event<600 
  | extend _time=_time-rand(600), method=iif(event%2>0, "GET", "POST") 
  | timestats span=1m count() by method

  Copy Run in Cribl Search