events.duration() function

The events.duration() function is a user-contributed function maintained by the package author and can be updated or removed at any time.

The events.duration() function calculates the duration of events. The function determines the time between a record and the subsequent record and associates the duration with the first record (start of the event). To calculate the duration of the last event, the function compares the timestamp of the final record to the timestamp in the stopColumn or the specified stop time.

import "contrib/tomhollingworth/events"
events.duration(
  unit: 1ns,
  columnName: "duration",
  timeColumn: "_time",
  stopColumn: "_stop",
  stop: 2020-01-01T00:00:00Z
)

Similar functions

events.duration() is similar to elapsed() and stateDuration(), but differs in important ways:

elapsed() drops the first record. events.duration() does not.
stateDuration() calculates the total time spent in a state (determined by a predicate function). events.duration() returns the duration between all records and their subsequent records.

For examples, see below.

Parameters

unit

Duration unit of the calculated state duration. Default is 1ns

*Data type: Duration*

columnName

Name of the result column. Default is "duration".

*Data type: String*

timeColumn

Name of the time column. Default is "_time".

*Data type: String*

stopColumn

Name of the stop column. Default is "_stop".

*Data type: String*

stop

The latest time to use when calculating results. If provided, stop overrides the time value in the stopColumn.

*Data type: Time*

Examples

Calculate the duration of states

import "contrib/tomhollingworth/events"
data
  |> events.duration(
    unit: 1m,
    stop: 2020-01-02T00:00:00Z
  )

Input

_time	state
2020-01-01T00:00:00Z	ok
2020-01-01T00:12:34Z	warn
2020-01-01T00:25:01Z	ok
2020-01-01T16:07:55Z	crit
2020-01-01T16:54:21Z	warn
2020-01-01T18:20:45Z	ok

Output

_time	state	duration
2020-01-01T00:00:00Z	ok	12
2020-01-01T00:12:34Z	warn	12
2020-01-01T00:25:01Z	ok	942
2020-01-01T16:07:55Z	crit	46
2020-01-01T16:54:21Z	warn	86
2020-01-01T18:20:45Z	ok	339

Compared to similar functions

The example below includes output values of events.duration(), elapsed(), and stateDuration() related to the _time and state values of input data.

Input

_time	state
2020-01-01T00:00:00Z	ok
2020-01-01T00:12:34Z	warn
2020-01-01T00:25:01Z	ok
2020-01-01T16:07:55Z	crit
2020-01-01T16:54:21Z	warn
2020-01-01T18:20:45Z	ok

Functions

data |> events.duration(
  unit: 1m,
  stop: 2020-01-02T00:00:00Z
)
data |> elapsed(
  unit: 1m
)
data |> stateDuration(
  unit: 1m,
  fn: (r) => true
)

Output values

_time	state	events.duration()	elapsed()	stateDuration()
2020-01-01T00:00:00Z	ok	12	N/A	0
2020-01-01T00:12:34Z	warn	12	12	12
2020-01-01T00:25:01Z	ok	942	12	25
2020-01-01T16:07:55Z	crit	46	942	967
2020-01-01T16:54:21Z	warn	86	46	1014
2020-01-01T18:20:45Z	ok	339	86	1100