reltime
Description
Creates one or more relative time fields and adds the field or fields to returned events. Each added relative time field provides a human-readable value of the difference between "now" (the start time of the search) and the timestamp value of a corresponding field in the returned event. Human-readable values look like 5 days ago
, 1 minute ago
, 2 years ago
, and so on.
Syntax
The required syntax is in bold.
- | reltime
- [timefield=<field-list>]
- [prefix=<string>]
Optional arguments
- timefield
- Syntax: timefield=<field-list>
- Description: Specifies one or more time fields in the events returned by the search. The
reltime
command uses these fields as the basis for the relative time field that it adds to the events.timefield
can specify only fields with values that are valid timestamps.timefield
can specify multiple time fields as a comma-separated list bounded by double quotation marks. - Default: _time
- prefix
- Syntax: prefix=<string>
- Description: Sets a prefix string for relative time field names. Use it to help others identify fields added by
reltime
or to provide unique field names when you identify multipletimefield
values. If you specify multiple values fortimefield
but do not specify aprefix
, thereltime
command prefixes the relative time fields that it adds withreltime_
.
Usage
The reltime
command adds one or more relative time fields to your events. Each field added provides a human-readable value that represents the difference between now
(the start time of the search) and the timestamp value of a field in the event.
For example, say you tie reltime
to the _time
fields in your events. If you run a search at 6 a.m., and the search returns an event with a _time
value that translates to 5 a.m., reltime
adds a field to that event named reltime
with the value 1 hour ago
.
If you use reltime
without arguments, the command adds a relative time field to your events named reltime
. This new field will be based on the _time
field in each of your events.
The following table explains how reltime
defines and names the fields that it adds.
Custom timefield specified? | Custom prefix specified? | Basis for field(s) added by reltime | Name(s) of field(s) added by reltime |
---|---|---|---|
None | No | _time
|
reltime
|
One timefield specified
|
No | The time field you specified for timefield
|
reltime
|
One timefield specified
|
Yes | The time field you specified for timefield
|
reltime , prefixed by your custom prefix string
|
Multiple time fields specified | No | The list of time fields you specified for timefield
|
The names of the fields you specified for timefield , prefixed by reltime_
|
Multiple time fields specified | Yes | The list of time fields you specified for timefield
|
The names of the fields you specified for timefield , prefixed by your custom prefix string
|
The reltime
command is a distributable streaming command. See Command types.
Examples
Example 1:
Adds a field called reltime
to the events returned by the search, based on the _time
field in those events.
... | reltime
Example 2:
Adds a field called reltime
to events returned by the search, based on the earliest_time
field in those events.
... | reltime timefield=earliest_time
Example 3:
Adds a field called reltime_now_current_time
to events, based on the current_time
field in those events.
... | reltime timefield=current_time prefix=reltime_now_
Example 4:
Adds three new relative time fields called reltime_max_time
, reltime_min_time
, and reltime_current_time
to returned events with max_time
, min_time
, and current_time
fields.
... | reltime timefield="max_time,min_time,current_time"
Example 5:
Adds two new relative time fields called usr_prefix_max_time
and usr_prefix_min_time
to returned events with max_time
and min_time
fields.
... | reltime timefield="max_time,min_time" prefix=usr_prefix_
See also
regex | rename |
This documentation applies to the following versions of Splunk Cloud Platform™: 9.2.2406, 9.0.2205, 8.2.2112, 8.2.2201, 8.2.2202, 8.2.2203, 9.0.2208, 9.0.2209, 9.0.2303, 9.0.2305, 9.1.2308, 9.1.2312, 9.2.2403 (latest FedRAMP release)
Feedback submitted, thanks!