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.
Hide omitted argument names for this function
Omitted Argument NamesThe argument name for
duration
can be omitted; the following forms of this function are equivalent:logscaleduration("value")
and:
logscaleduration(duration="value")
These examples show basic structure only.
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
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
Starting with the source repository events
- flowchart LR; %%{init: {"flowchart": {"defaultRenderer": "elk"}} }%% 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;logscale
diff := endTime - startTime
Determine the difference between the endTime and startTime; the fields should be in milliseconds (as they would be for an epoch or timestamp).
- flowchart LR; %%{init: {"flowchart": {"defaultRenderer": "elk"}} }%% 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;logscale
| test(diff > duration("5m"))
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. 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
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
Starting with the source repository events
- flowchart LR; %%{init: {"flowchart": {"defaultRenderer": "elk"}} }%% repo{{Events}} 0[[Expression]] result{{Result Set}} repo --> 0 0 --> result style 0 fill:#ff0000,stroke-width:4px,stroke:#000;logscale
test(@timestamp > now() - duration("2d"))
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 fromnow()
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. Event Result set
Summary and Results
The result is syntactically equivalent to:
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.