Splunk® Cloud Services

SPL2 Search Reference

Acrobat logo Download manual as PDF


Acrobat logo 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 Overview of SPL2 eval functions.

now()

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 and where commands, in the WHERE clause of the from command, and as part of evaluation expressions with other commands.

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) | bin _time span=1d | timechart count() by _time

relative_time(<time>,<specifier>)

This function takes a UNIX time and a relative time specifier and returns the UNIX time value of the specifier applied to the time.

Usage

You can use this function with the eval and where commands, in the WHERE clause of the from command, and as part of evaluation expressions with other commands.

To use named arguments, you must specify the argument names before the argument values. For example:

... relative_time(time:now(), specifier:"-1d@d")

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(<time>,<format>)

This function takes a UNIX time value and renders the time as a string using the format specified. The UNIX time must be in seconds. Use the first 10 digits of a UNIX time to use the time in seconds.

Usage

You can use this function with the eval and where commands, in the WHERE clause of the from command, and as part of evaluation expressions with other commands.

Converting time into seconds

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:

| from [{ }] | eval StartTimestamp="1566554581000" | eval starttime=strftime(StartTimestamp/pow(10,9),"%Y-%m-%dT%H:%M:%S.%Q")


The results look like this:

StartTimeStamp _time starttime
1566554581000 2019-08-23 10:03:01 2019-08-23T03:03:01.000

In these results the _time value is the date and time when the search was run.

Using time variables

For a list and descriptions of format options, see Using time variables.

Using named arguments

To use named arguments, you must specify the argument names before the argument values. For example:

...strftime(time:_time, format:"%H:%M")

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 from command.

| from [{ }]

For example:

_time
2019-08-23 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.

| from [{ }] | eval week=strftime(_time,"%V")

The results are show the value 34 for week.

_time week
2019-08-23 14:00:15 34

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:

| from [{ }] | eval mytime=strftime(_time,"%Y-%m-%dT%H:%M:%S.%Q")

The results are:

_time mytime
2019-08-23 14:00:15 2019-08-23T14:00:15.000

strptime(<str>, <format>)

Takes a human readable time, represented by a string, and parses the time into a UNIX timestamp using the format. You use date and time variables to specify the format that matches string.

For example, if the string is 2019-08-23 17:19:01, the format must be %Y-%m-%d %H:%M:%S . The string 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

You can use this function with the eval and where commands, in the WHERE clause of the from command, and as part of evaluation expressions with other commands.

With the strptime function, you must specify the time format of the string 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 August 23 2019 17:19:01.89 %a %B %d %Y %H:%M:%S.%N
Mon 8/23/2019 17:19:01.89 %a %m/%d/%Y %H:%M:%S.%N
2019/08/23 17:19:01.89 %Y/%m/%d %H:%M:%S.%N
2019-08-23T17:19:01.89 %Y-%m-%dT%H:%M:%S.%N

Using time variables

For a list and descriptions of format options, see Using time variables.

Using named arguments

To use named arguments, you must specify the argument names before the argument values. For example:

...strptime(str:"Mon Aug 23 00:00:00 2020", format:"%a %B %d %H:%M:%S.%N %Y"

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.

Let's say you have a series of start and end times such as these:

starttime endtime
Mon Aug 12 00:00:00 2019 Mon Aug 12 05:59:59 2019
Mon Aug 12 06:00:00 2019 Mon Aug 12 11:59:59 2019
Mon Aug 12 12:00:00 2019 Mon Aug 12 17:59:59 2019
Mon Aug 12 18:00:00 2019 Mon Aug 12 23:59:59 2019
Tue Aug 13 00:00:00 2019 Tue Aug 13 05:59:59 2019
Tue Aug 13 06:00:00 2019 Tue Aug 13 11:59:59 2019
Tue Aug 13 12:00:00 2019 Tue Aug 13 17:59:59 2019
Tue Aug 13 18:00:00 2019 Tue Aug 13 23:59:59 2019

When you run the following search, the eval command takes the string time values in the starttime field and returns the UNIX time that corresponds to the string time values.

...| eval startunix=strptime(starttime,"%a %B %d %H:%M:%S.%N %Y")

The results look something like this:

starttime endtime startunix
Mon Aug 23 00:00:00 2019 Mon Aug 23 05:59:59 2019 534143600.000000

2019-10-01T21:22:47.000

Mon Aug 12 06:00:00 2019 Mon Aug 12 11:59:59 2019 1534165200.000000
Mon Aug 12 12:00:00 2019 Mon Aug 12 17:59:59 2019 534186800.000000
Mon Aug 12 18:00:00 2019 Mon Aug 12 23:59:59 2019 1534208400.000000
Tue Aug 13 00:00:00 2019 Tue Aug 13 05:59:59 2019 1534230000.000000
Tue Aug 13 06:00:00 2019 Tue Aug 13 11:59:59 2019 1534251600.000000
Tue Aug 13 12:00:00 2019 Tue Aug 13 17:59:59 2019 1534273200.000000
Tue Aug 13 18:00:00 2019 Tue Aug 13 23:59:59 2019 1534294800.000000

time()

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 the event is processed.

You can use this function with the eval and where commands, in the WHERE clause of the from command, and as part of evaluation expressions with other commands.

Basic example

This example shows the results of using the time() function.

Let's consider the following times:

starttime starthuman
1534143600 Mon Aug 13 00:00:00 2018
1534165200 Mon Aug 13 06:00:00 2018
1534186800 Mon Aug 13 12:00:00 2018
1534208400 Mon Aug 13 18:00:00 2018
1534230000 Tue Aug 14 00:00:00 2018
1534251600 Tue Aug 14 06:00:00 2018
1534273200 Tue Aug 14 12:00:00 2018
1534294800 Tue Aug 14 18:00:00 2018

To return the UNIX time when a result is processed, you first need to convert the startime values to include microseconds.

... | eval epoch_time=strptime(starttime,"%s") | eval testtime=time()

  • The first eval command takes the numbers in the startime field and returns them with microseconds included.
  • The second eval command creates the testtime field and returns the UNIX time at the instant the result was processed by the eval command.


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.

See also

Functions
SPL2 eval functions Quick Reference
Overview of SPL2 eval functions
Last modified on 08 September, 2020
PREVIOUS
Cryptographic functions
  NEXT
Informational functions

This documentation applies to the following versions of Splunk® Cloud Services: current


Was this documentation topic helpful?

You must be logged into splunk.com in order to post comments. Log in now.

Please try to keep this discussion focused on the content covered in this documentation topic. If you have a more general question about Splunk functionality or are experiencing a difficulty with Splunk, consider posting a question to Splunkbase Answers.

0 out of 1000 Characters