Related Answers
Download topic as PDF
Date and Time functions
The following list contains the functions that you can use to calculate dates and time.
For information about using string and numeric fields in functions, and nesting functions, see Evaluation functions.
In addition to the functions listed in this topic, there are also variables and modifiers that you can use in searches.
now()
Description
This function takes no arguments and returns the time that the search was started.
Usage
The now() function is often used with other data and time functions.
The time returned by the now() function is represented in UNIX time, or in seconds since Epoch time.
When used in a search, this function returns the UNIX time when the search is run. If you want to return the UNIX time when each result is returned, use the time() function instead.
You can use this function with the eval, fieldformat, and where commands, and as part of eval expressions.
Basic example
The following example determines the UNIX time value of the start of yesterday, based on the value of now().
... | eval n=relative_time(now(), "-1d@d")
Extended example
If you are looking for events that occurred within the last 30 minutes you need to calculate the event hour, event minute, the current hour, and the current minute. You use the now() function to calculate the current hour (curHour) and current minute (curMin). The event timestamp, in the _time field, is used to calculate the event hour (eventHour) and event minute (eventMin). For example:
... earliest=-30d
| eval eventHour=strftime(_time,"%H")
| eval eventMin=strftime(_time,"%M")
| eval curHour=strftime(now(),"%H")
| eval curMin=strftime(now(),"%M")
| where (eventHour=curHour and eventMin > curMin - 30) or
(curMin < 30 and eventHour=curHour-1 and eventMin>curMin+30)
| bucket _time span=1d
| chart count by _time
relative_time(X,Y)
Description
This function takes a UNIX time, X, as the first argument and a relative time specifier, Y, as the second argument and returns the UNIX time value of Y applied to X.
Usage
You can use this function with the eval, fieldformat, and where commands, and as part of eval expressions.
Basic example
The following example determines the UNIX time value of the start of yesterday, based on the value of now().
... | eval n=relative_time(now(), "-1d@d")
strftime(X,Y)
Description
This function takes a UNIX time value, X, as the first argument and renders the time as a string using the format specified by Y. The UNIX time must be in seconds. Use the first 10 digits of a UNIX time to use the time in seconds.
Usage
If the time is in milliseconds, microseconds, or nanoseconds you must convert the time into seconds. You can use the pow function to convert the number.
- To convert from milliseconds to seconds, divide the number by 1000 or 10^3.
- To convert from microseconds to seconds, divide the number by 10^6.
- To convert from nanoseconds to seconds, divide the number by 10^9.
The following search uses the pow function to convert from nanoseconds to seconds:
| makeresults | eval StartTimestamp="1521467703049000000"| eval starttime=strftime(StartTimestamp/pow(10,9),"%Y-%m-%dT%H:%M:%S.%Q")
The results appear on the Statistics tab and look like this:
| StartTimeStamp | _time | starttime |
|---|---|---|
| 1521467703049000000 | 2018-08-10 09:04:00 | 2018-03-19T06:55:03.049 |
In these results the _time value is the date and time when the search was run.
For a list and descriptions of format options, see Common time format variables.
You can use this function with the eval, fieldformat, and where commands, and as part of eval expressions.
Basic example
The following example returns the hour and minute from the _time field.
...| eval hour_min=strftime(_time, "%H:%M")
If the _time field value is 2018-08-10 11:48:23, the value returned in the hour_min field is 11:48.
Extended example
The following example creates a single result using the makeresults command.
| makeresults
For example:
| _time |
|---|
| 2018-08-14 14:00:15 |
The _time field is stored in UNIX time, even though it displays in a human readable format. To convert the UNIX time to some other format, you use the strftime function with the date and time format variables. The variables must be in quotations marks.
For example, to return the week of the year that an event occurred in, use the %V variable.
| makeresults | eval week=strftime(_time,"%V")
The results are show the value 33 for week.
| _time | week |
|---|---|
| 2018-08-14 14:00:15 | 33 |
To return the date and time with subseconds and the time designator (the letter T) that precedes the time components of the format, use the %Y-%m-%dT%H:%M:%S.%Q variables. For example:
| makeresults | eval mytime=strftime(_time,"%Y-%m-%dT%H:%M:%S.%Q")
The results are:
| _time | mytime |
|---|---|
| 2018-08-14 14:00:15 | 2018-08-14T14:00:15.000 |
strptime(X,Y)
Description
This function takes a time represented by a string X and parses the time into a UNIX timestamp. You use date and time variables to specify the format Y that matches string X.
For example, if string X is 2018-08-13 11:22:33, the format Y must be %Y-%m-%d %H:%M:%S . The string X date must be January 1, 1971 or later.
The _time field is in UNIX time. In Splunk Web, the _time field appears in a human readable format in the UI but is stored in UNIX time. If you attempt to use the strptime function on the _time field, no action is performed on the values in the field.
Usage
With the strptime function, you must specify the time format of the string X so that the function can convert the string time into the correct UNIX time. The following table shows some examples:
| String time | Matching time format variables |
|---|---|
Mon July 23 2018 17:19:01.89
|
%a %B %d %Y %H:%M:%S.%N
|
Mon 7/23/2018 17:19:01.89
|
%a %m/%d/%Y %H:%M:%S.%N
|
2018/07/23 17:19:01.89
|
%Y/%m/%d %H:%M:%S.%N
|
2018-07-23T17:19:01.89
|
%Y-%m-%dT%H:%M:%S.%N
|
For a list and descriptions of format options, see Common time format variables.
You can use this function with the eval, fieldformat, and where commands, and as part of eval expressions.
Basic example
If the values in the timeStr field are hours and minutes, such as 11:59, the following example returns the time as a timestamp:
... | eval n=strptime(timeStr, "%H:%M")
Extended example
This example shows the results of using the strptime function. The following search does several things:
- The
gentimescommand generates a set of times with 6 hour intervals. This command returns four fields:startime,starthuman,endtime, andendhuman. - The
fieldscommand returns only thestarthumanandendhumanfields. - The
evalcommand takes the string time values in thestarthumanfield and returns the UNIX time that corresponds to the string time values.
| gentimes start=8/13/18 increment=6h
| fields starthuman endhuman
| eval startunix=strptime(starthuman,"%a %B %d %H:%M:%S.%N %Y")
The results appear on the Statistics tab and look something like this:
| starthuman | endhuman | startunix |
|---|---|---|
| Mon Aug 13 00:00:00 2018 | Mon Aug 13 05:59:59 2018 | 534143600.000000 |
| Mon Aug 13 06:00:00 2018 | Mon Aug 13 11:59:59 2018 | 1534165200.000000 |
| Mon Aug 13 12:00:00 2018 | Mon Aug 13 17:59:59 2018 | 534186800.000000 |
| Mon Aug 13 18:00:00 2018 | Mon Aug 13 23:59:59 2018 | 1534208400.000000 |
| Tue Aug 14 00:00:00 2018 | Tue Aug 14 05:59:59 2018 | 1534230000.000000 |
| Tue Aug 14 06:00:00 2018 | Tue Aug 14 11:59:59 2018 | 1534251600.000000 |
| Tue Aug 14 12:00:00 2018 | Tue Aug 14 17:59:59 2018 | 1534273200.000000 |
| Tue Aug 14 18:00:00 2018 | Tue Aug 14 23:59:59 2018 | 1534294800.000000 |
time()
Description
This function returns the wall-clock time, in the UNIX time format, with microsecond resolution.
Usage
The value of the time() function will be different for each event, based on when that event was processed by the eval command.
You can use this function with the eval, fieldformat, and where commands, and as part of eval expressions.
Basic example
This example shows the results of using the time() function. The following search does several things"
- The
gentimescommand generates a set of times with 6 hour intervals. This command returns four fields:startime,starthuman,endtime, andendhuman. - The
fieldscommand returns only thestartimeandstarthumanfields. - The first
evalcommand takes the numbers in thestartimefield and returns them with microseconds included. - The second
evalcommand creates thetesttimefield and returns the UNIX time at the instant the result was processed by theevalcommand.
| gentimes start=8/13/18 increment=6h
| fields starttime starthuman
| eval epoch_time=strptime(starttime,"%s")
| eval testtime=time()
The results appear on the Statistics tab and look something like this:
| starttime | starthuman | epoch_time | testtime |
|---|---|---|---|
| 1534143600 | Mon Aug 13 00:00:00 2018 | 1534143600.000000 | 1534376565.299298 |
| 1534165200 | Mon Aug 13 06:00:00 2018 | 1534165200.000000 | 1534376565.299300 |
| 1534186800 | Mon Aug 13 12:00:00 2018 | 1534186800.000000 | 1534376565.299302 |
| 1534208400 | Mon Aug 13 18:00:00 2018 | 1534208400.000000 | 1534376565.299304 |
| 1534230000 | Tue Aug 14 00:00:00 2018 | 1534230000.000000 | 1534376565.299305 |
| 1534251600 | Tue Aug 14 06:00:00 2018 | 1534251600.000000 | 1534376565.299306 |
| 1534273200 | Tue Aug 14 12:00:00 2018 | 1534273200.000000 | 1534376565.299308 |
| 1534294800 | Tue Aug 14 18:00:00 2018 | 1534294800.000000 | 1534376565.299309 |
Notice the difference in the microseconds between the values in the epoch_time and test_time fields. You can see that the test_time values increase with each result.
|
PREVIOUS Cryptographic functions |
NEXT Informational functions |
This documentation applies to the following versions of Splunk® Enterprise: 6.6.0, 6.6.1, 6.6.2, 6.6.3, 6.6.4, 6.6.5, 6.6.6, 6.6.7, 6.6.8, 6.6.9, 6.6.10, 6.6.11, 6.6.12, 7.0.0, 7.0.1, 7.0.2, 7.0.3, 7.0.4, 7.0.5, 7.0.6, 7.0.7, 7.0.8, 7.0.9, 7.0.10, 7.0.11, 7.0.13, 7.1.0, 7.1.1, 7.1.2, 7.1.3, 7.1.4, 7.1.5, 7.1.6, 7.1.7, 7.1.8, 7.1.9, 7.2.0, 7.2.1, 7.2.2, 7.2.3, 7.2.4, 7.2.5, 7.2.6, 7.2.7, 7.2.8, 7.2.9, 7.3.0, 7.3.1, 7.3.2, 7.3.3, 8.0.0
Comments
Thanks Laura!
This is a good example.
Anirbandasdeb
Per our conversations via email, I have updated the descriptions of the strftime and strptime functions.
I'll work on another or more detailed example as well.
contd..
| makeresults
| eval t=now()
| eval t_strftime = strftime(t, "%Y-%m-%dT%H:%M:%S.%Q")
| eval type1 = typeof(t_strftime)
| eval t_strptime = strptime(t_strftime, "%Y-%m-%dT%H:%M:%S.%Q")
| eval type2 = typeof(t_strptime)
| table _time, t, t_strftime, type1, t_strptime, type2
Given that Splunk excels in time series data, and as such, time related calculations would be required, it is important to explain the usage of these two functions in detail, with worked out examples. Especially, how the string format Y for strptime is chosen.
Perhaps, put up a blog, and link it here, rather than change the official documentation??
Regards.
The description for strptime() is dubious, and I got confused with how to make it work.
A better description is given at https://answers.splunk.com/answers/80521/time-function.html
"strptime(X,Y) will convert a string X, e.g. "2013-03-22 11:22:33", into epoch, with the string being described by Y
strftime(X,Y) will convert an epoch timestamp (X) into a string, defined by Y."
Also, a better example would be helpful as well to compare the differences of usage for strptime and strftime, like so:
contd..
Hello Badgriff16
Thank you for reaching out to us about using Splunk!
Depending on what you are trying to do, you can use either the timechart or the bin command.
timechart count by host span=month
Or
bin _time span=month | stats count by _time host
I am new to Splunk and I am still learning how to write the correct syntax to gather the right information, but I am having issues. If I am trying to find the Total access attempts by month by host and the total failed access attempts by month by host how would I need to write the syntax for? I can't seem to find anything that helps me on this.
It would be REALLY nice if we could specify "GMT" or another valid timezone specifier to return the offset of my personal TZ to the specified TZ. We need to normalize to GMT for some stuff (to make the search user-TZ-agnostic) and we have to do some silly stuff.
Its possible to increment search time by time? 1hour +1hour + 1hour with a period pre defined