Documentation

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
_timestate
2020-01-01T00:00:00Zok
2020-01-01T00:12:34Zwarn
2020-01-01T00:25:01Zok
2020-01-01T16:07:55Zcrit
2020-01-01T16:54:21Zwarn
2020-01-01T18:20:45Zok
Output
_timestateduration
2020-01-01T00:00:00Zok12
2020-01-01T00:12:34Zwarn12
2020-01-01T00:25:01Zok942
2020-01-01T16:07:55Zcrit46
2020-01-01T16:54:21Zwarn86
2020-01-01T18:20:45Zok339

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
_timestate
2020-01-01T00:00:00Zok
2020-01-01T00:12:34Zwarn
2020-01-01T00:25:01Zok
2020-01-01T16:07:55Zcrit
2020-01-01T16:54:21Zwarn
2020-01-01T18:20:45Zok
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
_timestateevents.duration()elapsed()stateDuration()
2020-01-01T00:00:00Zok12N/A0
2020-01-01T00:12:34Zwarn121212
2020-01-01T00:25:01Zok9421225
2020-01-01T16:07:55Zcrit46942967
2020-01-01T16:54:21Zwarn86461014
2020-01-01T18:20:45Zok339861100

Package author and maintainer

Github: @tomhollingworth
InfluxDB Slack: @Tom Hollingworth


New! Cloud or OSS?

InfluxDB OSS 2.0 now generally available!

InfluxDB OSS 2.0 is now generally available and ready for production use. See the InfluxDB OSS 2.0 release notes.

For information about upgrading to InfluxDB OSS 2.0, see: