This function computes the number of milliseconds in a certain fixed time period. It is used to make timestamp comparisons easier, more readable and less error-prone.

ParameterTypeRequiredDefaultDescription
asstringoptional[a]_duration The name of the output field.
duration[b]stringrequired  The time duration specification. It is defined as a Relative Time Syntax such as 5m or 2d.

[a] Optional parameters use their default value unless explicitly set

[b] The argument name duration can be omitted.

Omitted Argument Names

The argument name for duration can be omitted; the following forms of this function are equivalent:

logscale
duration("value")

and:

logscale
duration(duration="value")

The function returns (in the field selected by the as argument) the number of milliseconds in the duration described by the duration argument. The syntax and semantics of the duration argument is exactly the duration specification mini-language used elsewhere in the system; for more information on time duration, see Relative Time Syntax.

duration() Examples

Compare two timestamps

Query
flowchart LR; repo{{Events}} 0>Augment Data] 1[[Expression]] result{{Result Set}} repo --> 0 0 --> 1 1 --> result
logscale
diff := endTime - startTime
| test(diff > duration("5m"))
Introduction

The duration() function returns the number of milliseconds for a given duration specification. This value can be used as the basis for comparison for different values. In this example, the function is used to compute a simple value to use in a comparison. The input data contains the startTime and endTime for an operation, to determine whether the difference between the two exceeds a duration of 5 minutes.

Step-by-Step

  1. Starting with the source repository events

  2. flowchart LR; repo{{Events}} 0>Augment Data] 1[[Expression]] result{{Result Set}} repo --> 0 0 --> 1 1 --> result style 0 fill:#ff0000,stroke-width:4px,stroke:#000;

    Determine the difference between the endTime and startTime; the fields should be in milliseconds (as they would be for an epoch or timestamp).

    logscale
    diff := endTime - startTime
  3. flowchart LR; repo{{Events}} 0>Augment Data] 1[[Expression]] result{{Result Set}} repo --> 0 0 --> 1 1 --> result style 1 fill:#ff0000,stroke-width:4px,stroke:#000;

    Use the test() function to determine if the computed difference is greater than a duration of 5 minutes. In this case, duration() returns 300,000.

    logscale
    | test(diff > duration("5m"))

  4. Event Result set

Summary and Results

The duration() functions supports a more convenient, and human-readable, method of defining a duration without needing to explicitly calculate the comparison. This is particularly useful when using parameters on a dashboard.

Narrow the search interval

Query
flowchart LR; repo{{Events}} 0[[Expression]] result{{Result Set}} repo --> 0 0 --> result
logscale
test(@timestamp > now() - duration("2d"))
Introduction

When searching across a range of timestamps, the ability to limit the search to a more specific range using a relative duration can limit the output. To achieve this with the search, make use of duration() with a relative time, for example 2d for two days and use this to compare against the current time and @timestamp of the event.

Step-by-Step

  1. Starting with the source repository events

  2. flowchart LR; repo{{Events}} 0[[Expression]] result{{Result Set}} repo --> 0 0 --> result style 0 fill:#ff0000,stroke-width:4px,stroke:#000;

    Create a value based on a duration of 2d (two days). This returns a value in milliseconds (2 * 24 * 60 * 60 * 1000). By subtracting the value from now() the value is two days ago from the time the event is executed. Then the value is compared to the @timestamp to filter the events.

    logscale
    test(@timestamp > now() - duration("2d"))

  3. Event Result set

Summary and Results

The result is syntactically equivalent to:

logscale
test(@timestamp > now() - 172800000)

As the value is in a human-readable and relative time syntax, the value can be used in dashboards and user-selected parameters.