Timestamps are typically extracted and parsed during ingest. If there are embedded timestamps in other parts of the data, these may need to be explicitly parsed from the source data either during parsing or querying.

In Windows event logs, for example, a timestamp may exist in the embedded XML:

To extract the timestamp from this, the findTimestamp() function will look at values and identify whether any of them look like a timestamp and extract it:

parseXml()
| findTimestamp(as=eventts)

This puts the value of a timestamp into the eventts field.

If you know the name of the field that contains the timestamp, or you want to extract a timestamp that is not in a commonly used format, use the parseTimestamp(). For example, to extract a timestamp from a field where the data is stored in the format YYYYMMDD:

You must specify the format:

parseTimestamp(field="mydate",format="yyyyMMddHHmmss",as=eventts)

For more examples, see parseTimestamp().

If the time value is based on a different reference point, for example the epoch is different, or the quantity is different (hours, or days in place of seconds) and then represented only as this differential in the input then the value must separately be calculated and applied to the timestamp value.

For example, a time value measured in seconds calculated from the 1/1/2001 will need to be converted, first by calculating the difference in seconds between 1/1/1970 and 1/1/2001, then multiplying the value (in seconds) to get milliseconds:

epoch := 978307200
| newts := (ts*1000) + epoch
| formatTime(format="%m/%d/%Y %H:%M:%S %a", field=ts, as=formatted)

In general the query environment (whether in the UI or through the API) will set the time range for a given query. However, there may be occasions when you want to limit your search, or a portion of your overall search pipeline, to a range of times based on the ingest or event time.

To set for the whole query, when you cannot directly control the time range through the search method, use the setTimeInterval() function:

setTimeInterval(start=7d, end=1d)

IF you want to limit the time interval or search interval of the event data returned for a subset of the information, The way to achieve this is to use the test() function to limit your search to filter on the selected dates:

test(start_hour_utc <= time:hour(@timestamp))
| test(time:hour(@timestamp) <= end_hour_utc)

To extract single values, such as the day or hour, there are a number of functions that extract just that single value in an efficient manner. For example, to extract data and summarize it per minute:

minute := time:minute(@timestamp)
| groupBy(minute)

Might generate output like this:

This can also be performed over multiple dimensions, for example, to summarize over day and month:

day := time:dayOfMonth(@timestamp)
| month := time:month(@timestamp)
| groupBy([month,day])

Might output this:

For more information, see Time and Date Query Functions.

To format a date or time in a format that suits your desired output use the formatTime() function. This supports most of the formats familiar to users of strftime() or similar system functions. It uses a format specified to output the value. For example, to generate the day (as a number) and month (as a name):

formatTime(@timestamp,format="%d %A")

Would output 12 December (for data on that date).

To summarize by a given date and also use an alternative friendlier date format, you can use groupBy() to summarize the value and it's formatted output:

summarydate := formatTime("%m%d")
| display := formatTime("%d %B")
| groupBy([summarydate,job],function=[collect(display),count()])
| drop(summarydate,job)
| groupBy(display,function=sum("_count"))

This works by:

This might generate output like this:

If you have a relative time value, or want to output a value that represents the difference use the formatDuration() value. This converts an incoming value (for example seconds or milliseconds) into a duration. For example, to compare the @timestamp to the current time, use in combination with the now() you can subtract the times to get the value in milliseconds and then convert to a duration:

timediff := (now() - @timestamp)
| formatDuration(timediff,from="ms",as=duration)

Which might output something like this:

This may not be a useful measure if you want to summarize something by the number of days or months 'ago', when it occurred. Instead, you'll need to calculate the time difference, round the number (so that it's an integer, not a floating point), and then summarize. For example, to look for occurrences of the bucket-storage-upload job in the humio:

"bucket-storage-upload"
| nowtime := now()
| timediff := (nowtime - @timestamp)
| basedays := (timediff / (24*60*60*1000))
| daysago := round(basedays)
| groupBy(daysago)

Generates a summarized list: