---
title: events.duration() function
description: events.duration() calculates the duration of events.
url: https://docs.influxdata.com/flux/v0/stdlib/contrib/tomhollingworth/events/duration/
estimated_tokens: 3968
product: Flux
version: v0
---

# events.duration() function

-   Flux 0.91.0+
-   View InfluxDB support

`events.duration()` is a user-contributed function maintained by the [package author](#package-author-and-maintainer).

`events.duration()` 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.

### 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.

See the example [below](#compared-to-similar-functions).

##### Function type signature

```js
(
    <-tables: stream[A],
    ?columnName: string,
    ?stop: time,
    ?stopColumn: string,
    ?timeColumn: string,
    ?unit: duration,
) => stream[B] where A: Record, B: Record
```

For more information, see [Function type signatures](/flux/v0/function-type-signatures/).

## Parameters

### unit

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

### columnName

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

### timeColumn

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

### stopColumn

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

### stop

The latest time to use when calculating results.

If provided, `stop` overrides the time value in the `stopColumn`.

### tables

Input data. Default is piped-forward data (`<-`).

## Examples

-   [Calculate the duration of states](#calculate-the-duration-of-states)
-   [Compared to similar functions](#compared-to-similar-functions)

### Calculate the duration of states

```js
import "array"
import "contrib/tomhollingworth/events"

data
    |> events.duration(unit: 1m, stop: 2020-01-02T00:00:00Z)
```

[](#view-example-input-and-output)

View example input and output

#### Input data

| _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 data

| _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.

```js
import "array"
import "contrib/tomhollingworth/events"

union(
    tables: [
        data
            |> events.duration(unit: 1m, stop: 2020-01-02T00:00:00Z)
            |> map(
                fn: (r) =>
                    ({
                        _time: r._time,
                        state: r.state,
                        function: "events.Duration()",
                        value: r.duration,
                    }),
            ),
        data
            |> elapsed(unit: 1m)
            |> map(
                fn: (r) =>
                    ({_time: r._time, state: r.state, function: "elapsed()", value: r.elapsed}),
            ),
        data
            |> stateDuration(unit: 1m, fn: (r) => true)
            |> map(
                fn: (r) =>
                    ({
                        _time: r._time,
                        state: r.state,
                        function: "stateDuration()",
                        value: r.stateDuration,
                    }),
            ),
    ],
)
    |> pivot(rowKey: ["_time", "state"], columnKey: ["function"], valueColumn: "value")
```

[](#view-example-output)

View example output

#### Output data

| _time | state | events.Duration() | elapsed() | stateDuration() |
| --- | --- | --- | --- | --- |
| 2020-01-01T00:00:00Z | ok | 12 |  | 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 |

#### Related

-   [elapsed() function](/flux/v0/stdlib/universe/elapsed/)
-   [stateDuration() function](/flux/v0/stdlib/universe/stateduration/)

[transformations](/flux/v0/tags/transformations/) [events](/flux/v0/tags/events/)