
Time modifiers
Use time modifiers to customize the time range of a search or change the format of the timestamps in the search results.
_time and _indextime fields
When an event is processed by Splunk software, its timestamp is saved as the default field _time
. This timestamp, which is the time when the event occurred, is saved in UNIX time notation. Searching with relative time modifiers, earliest
or latest
, finds every event with a timestamp beginning, ending, or between the specified timestamps.
For example, when you search for earliest=-4h
, the search finds every event with a _time
value in the last four hours.
You also have the option of searching for events based on when they were indexed. The UNIX time is saved in the _indextime
field. Similar to earliest
and latest
for the _time
field, you can use the relative time modifiers _index_earliest
and _index_latest
to search for events based on _indextime
. For example, if you wanted to search for events indexed in the previous hour, use: _index_earliest=-h _index_latest=now()
.
Note: When using index-time based modifiers such as index_earliest
and index_latest
, your search must also have an event-time window which will retrieve the events. In other words, chunks of events might be ruled out based on the non index-time window as well as the index-time window. To be certain of retrieving every event based on index-time, you must run your search using All Time.
List of time modifiers
Use the earliest
and latest
modifiers to specify custom and relative time ranges. You can specify an exact time such as earliest="10/5/2016:20:00:00"
, or a relative time such as earliest=-h
or latest=-15m
.
When specifying relative time, you can use the now()
modifier to refer to the current time.
Modifier | Syntax | Description |
---|---|---|
earliest | earliest=[+|-]<time_integer><time_unit>
|
Specify the earliest _time for the time range of your search. |
_index_earliest | _index_earliest=[+|-]<time_integer><time_unit>
|
Specify the earliest _indextime for the time range of your search. |
_index_latest | _index_latest=[+|-]<time_integer><time_unit>
|
Specify the latest _indextime for the time range of your search. |
latest | latest=[+|-]<time_integer><time_unit>
|
Specify the latest time for the _time range of your search. |
now | now()
|
Refers to the current time. If set to earliest, now() is the start of the search. |
time | time()
|
In real-time searches, time() is the current machine time. |
For more information about customizing your search window, see Specify real-time time range windows in your search in the Search Manual.
How to specify relative time modifiers
You can define the relative time in your search with a string of characters that indicate time amount (integer and unit).
The syntax for using time modifiers is [+|-]<time_integer><time_unit>
The steps to specify a relative time modifier are:
- Indicate the time offset from the current time.
- Define the time amount, which is a number and a unit.
Indicate the time offset
Begin your string with a plus (+) or minus (-) to indicate the offset from the current time.
Define the time amount
Define your time amount with a number and a unit. The supported time units are:
- second: s, sec, secs, second, seconds
- minute: m, min, minute, minutes
- hour: h, hr, hrs, hour, hours
- day: d, day, days
- week: w, week, weeks
- month: mon, month, months
- quarter: q, qtr, qtrs, quarter, quarters
- year: y, yr, yrs, year, years
For example, to start your search an hour ago, use either of the following time modifiers.
earliest=-h
or
earliest=-60m
When specifying single time amounts, the number one is implied. An 's' is the same as '1s', 'm' is the same as '1m', 'h' is the same as '1h', and so forth.
Examples
1. Search the events from the last 7 days
earliest=-7d
2. Search with an exact date as a boundary
With a boundary such as from November 5 at 8 PM to November 12 at 8 PM, use the timeformat %m/%d/%Y:%H:%M:%S
.
earliest="11/5/2017:20:00:00" latest="11/12/2017:20:00:00"
3. Specify multiple time windows
You can specify multiple time windows using the timeformat %m/%d/%Y:%H:%M:%S
. For example to find events from 5-6 PM or 7-8 PM on specific dates, use the following syntax.
(earliest=“1/22/2018:17:00:00" latest="1/22/2018:18:00:00") OR (earliest="1/22/2018:19:00:00" latest="1/22/2018:20:00:00")
Other time modifiers
These search time modifiers are still valid, but might be removed and their function no longer supported in a future release.
Modifier | Syntax | Description |
---|---|---|
daysago | daysago=<int>
|
Search events within the last integer number of days. |
enddaysago | enddaysago=<int>
|
Set an end time for an integer number of days before Now. |
endhoursago | endhoursago=<int>
|
Set an end time for an integer number of hours before Now. |
endminutesago | endminutesago=<int>
|
Set an end time for an integer number of minutes before Now. |
endmonthsago | endmonthsago=<int>
|
Set an end time for an integer number of months before Now. |
endtime | endtime=<string>
|
Search for events before the specified time (exclusive of the specified time). Use timeformat to specify how the timestamp is formatted. |
endtimeu | endtimeu=<int>
|
Search for events before the specific UNIX time. |
hoursago | hoursago=<int>
|
Search events within the last integer number of hours. |
minutesago | minutesago=<int>
|
Search events within the last integer number of minutes. |
monthsago | monthsago=<int>
|
Search events within the last integer number of months. |
searchtimespandays | searchtimespandays=<int>
|
Search within a specified range of days, expressed as an integer. |
searchtimespanhours | searchtimespanhours=<int>
|
Search within a specified range of hours, expressed as an integer. |
searchtimespanminutes | searchtimespanminutes=<int>
|
Search within a specified range of minutes, expressed as an integer. |
searchtimespanmonths | searchtimespanmonths=<int>
|
Search within a specified range of months, expressed as an integer. |
startdaysago | startdaysago=<int>
|
Search the specified number of days before the present time. |
starthoursago | starthoursago=<int>
|
Search the specified number of hours before the present time. |
startminutesago | startminutesago=<int>
|
Search the specified number of minutes before the present time. |
startmonthsago | startmonthsago=<int>
|
Search the specified number of months before the present time. |
starttime | starttime=<timestamp>
|
Search from the specified date and time to the present, inclusive of the specified time. |
starttimeu | starttimeu=<int>
|
Search for events starting from the specific UNIX time. |
timeformat | timeformat=<string>
|
Set the timeformat for the starttime and endtime modifiers. By default: timeformat=%m/%d/%Y:%H:%M:%S
|
]
PREVIOUS Date and time format variables |
NEXT abstract |
This documentation applies to the following versions of Splunk® Enterprise: 6.0, 6.0.1, 6.0.2, 6.0.3, 6.0.4, 6.0.5, 6.0.6, 6.0.7, 6.0.8, 6.0.9, 6.0.10, 6.0.11, 6.0.12, 6.0.13, 6.0.14, 6.0.15, 6.1, 6.1.1, 6.1.2, 6.1.3, 6.1.4, 6.1.5, 6.1.6, 6.1.7, 6.1.8, 6.1.9, 6.1.10, 6.1.11, 6.1.12, 6.1.13, 6.1.14, 6.2.0, 6.2.1, 6.2.2, 6.2.3, 6.2.4, 6.2.5, 6.2.6, 6.2.7, 6.2.8, 6.2.9, 6.2.10, 6.2.11, 6.2.12, 6.2.13, 6.2.14, 6.2.15, 6.3.0, 6.3.1, 6.3.2, 6.3.3, 6.3.4, 6.3.5, 6.3.6, 6.3.7, 6.3.8, 6.3.9, 6.3.10, 6.3.11, 6.3.12, 6.3.13, 6.3.14, 6.4.0, 6.4.1, 6.4.2, 6.4.3, 6.4.4, 6.4.5, 6.4.6, 6.4.7, 6.4.8, 6.4.9, 6.4.10, 6.4.11, 6.5.0, 6.5.1, 6.5.1612 (Splunk Cloud only), 6.5.2, 6.5.3, 6.5.4, 6.5.5, 6.5.6, 6.5.7, 6.5.8, 6.5.9, 6.5.10
Comments
I believe that in 6.4.3 at least, the timeformat searchterm has died.
See my answer on this question here - https://answers.splunk.com/answers/448641/how-do-i-change-the-date-format-from-mmddyyyy-to-d.html#answer-448782
From what I can see on 6.4.3 on windows, timeformat="foo" in your searchterms, is accepted by Splunk without complaint, but it never has any affect. And I don't think there's any way any more *at all* for non-US users to get the old behavior of starttime="24/12/2015:00:00:00" endtime="25/12/2015:00:00:00" like you could when timeformat was working.
I believe the 2nd example is false:
Example 2: To search events from the last full business week:
earliest=-7d@w1 latest=@w6
If we are Sunday for example, the earliest date is the Monday from the previous week and the latest date is the Saturday of the current week, so we search events for 2 full weeks of business, not 1.
I might be wrong, correct me please if necessary.
Thank you. These are great suggestions and will be submitted as enhancement requests.
Personally, I'd like to see an option for a simper format (in addition to ISO). If I want 3 days of data from Jan 5, 2014 I'd love to be able to say:<br /><br /> earliest=01/05/2104 latest=+3d <br /> // default: midnight; <br /> // implied: 'latest' is relative to 'earliest' when "+" is used (since adding to 'now' is pointless)<br /><br />which is MUCH more friendly than my only option now:<br /><br /> earliest="01/05/2014:00:00:00" latest="01/08/2014:00:00:00"<br /><br />Furthermore: I often copy/paste queries into email. I'd like a way to convert relative times to literals so the query is still valid a week from now:<br /><br />earliest=-5d latest=+3d // used my "latest is relative to earliest" improvement<br /><br />somehow becomes <br />earliest="01/05/2014:10:11:12" latest="01/08/2014:10:11:12" <br /><br />so I can paste it accurately.
Yes. The timeformat used here is not scientific and confusing. I second the use of ISO format.
if timeformat, starttime, and endtime are being deprecated, request that you use a different time format for earliest and latest. "2012-04-25T14:30:00-0500" (ISO 8601) perhaps? The existing format is incorrect for users outside the USA. 8601 is mostly supported by python
Please bring back the Timeformat command!! We upgraded to 6.5.2. I have several dashboards that use this command. The search in the dashboard still works, but I can't drill in to see the results. I can't use it in a search, I can't do testing. I get the following error message: Error in 'convert' command: The conversion type ' ' is invalid.