Formats a string according to strftime, similar to unix strftime.

ParameterTypeRequiredDefault ValueDescription
asstringrequired  Specifies the output field.
fieldstringoptional[a]@timestamp Contains a 64-bit integer that is interpreted as either seconds or milliseconds since the Unix epoch (00:00:00 on 1 January 1970, in the timezone specified by timezone). Whether the integer is interpreted as seconds or milliseconds is controlled by the unit parameter.
format[b]stringrequired  Format string. A subset of Java Date/Time escapes is supported by LogScale, see table below.
localestringoptional[a]  Specifies the locale such as US or en_GB.
timezonestringoptional[a]UTC Specifies the timezone such as GMT, EST or Europe/London. See the full list of timezones supported by LogScale at Supported Timezones. If no timezone is present, UTC is used.
unitstringoptional[a]auto Controls whether the value in field is interpreted as seconds or milliseconds. (introduced in 1.113.0)
   Valid Values
   autoIf the number is less than or equals to 100,000,000,000, it's interpreted as seconds, otherwise it's interpreted as milliseconds.
   millisecondsThe number is unconditionally interpreted as milliseconds.
   secondsThe number is unconditionally interpreted as seconds.

[a] Optional parameters use their default value unless explicitly set.

[b] The argument name format can be omitted.

Hide omitted argument names for this function

Show omitted argument names for this function

The formatTime() function formats times using a subset of the Java Formatter pattern format. The following formats are supported:

Symbol Description Example
%H Hour of the day for the 24-hour clock, formatted as two digits with a leading zero as necessary. 00, 23
%I Hour for the 12-hour clock, formatted as two digits with a leading zero as necessary. 01, 12
%k Hour of the day for the 24-hour clock. 0, 23
%l Hour for the 12-hour clock. 1, 12
%M Minute within the hour formatted as two digits with a leading zero as necessary. 00, 59
%S Seconds within the minute, formatted as two digits with a leading zero as necessary. 00, 60 (leap second)
%L Millisecond within the second formatted as three digits with leading zeros as necessary. 000 - 999
%N Nanosecond within the second, formatted as nine digits with leading zeros as necessary. 000000000 - 999999999
%p Locale-specific morning or afternoon marker in lower case. am, pm
%z RFC 822 style numeric time zone offset from GMT. -0800
%Z A string representing the abbreviation for the time zone. UTC, EAT
%s Seconds since the beginning of the epoch starting at 1 January 1970 00:00:00 UTC (UNIXTIME) 1674304923
%Q Milliseconds since the beginning of the epoch starting at 1 January 1970 00:00:00 UTC 1674304923001.
%B Locale-specific full month name. "January", "February"
%b Locale-specific abbreviated month name. "Jan", "Feb"
%h Same as 'b'. "Jan", "Feb"
%A Locale-specific full name of the day of the week. "Sunday", "Monday"
%a Locale-specific short name of the day of the week. "Sun", "Mon".
%C Four-digit year divided by 100, formatted as two digits with leading zero as necessary 00, 99
%Y Year, formatted as at least four digits with leading zeros as necessary. 0092, 2023
%y Last two digits of the year, formatted with leading zeros as necessary. 00, 23
%j Day of year, formatted as three digits with leading zeros as necessary. 001 - 366
%m Month, formatted as two digits with leading zeros as necessary. 01 - 13
%d Day of month, formatted as two digits with leading zeros as necessary. 01 - 31
%e Day of month, formatted as two digits. 1 - 31
%R Time formatted as "%H:%M". 23:59
%T Time formatted as "%H:%M:%S". 23:59:59
%r Time formatted as "%I:%M:%S %p". NOTE: AM and PM will be uppercase unlike for %p. 01:21:11 PM
%D Date formatted as "%m/%d/%y". 01/31/23
%F ISO 8601 complete date formatted as "%Y-%m-%d" 1989-06-04
%c Date and time formatted as "%a %b %d %T %Z %Y" Thu Feb 02 11:03:28 Z 2023

By default, the function will automatically detect whether the field contains a timestamp in seconds or milliseconds, based on its numeric value:

  • If the given timestamp has less than 12 digits, it is interpreted as a timestamp in seconds.

  • if it has 12 digits or more, it is interpreted as a timestamp in milliseconds.

You can change the default auto-detection by specifically setting parameter unit to seconds or milliseconds.

When specifing the unit, the value must be a long integer and not a floating point value.

formatTime() Examples

Format time as 2021/11/26 06:54:45 using the timestamp field and UTC timezone using assignment to fmttime:

logscale
time := formatTime("%Y/%m/%d %H:%M:%S", field=@timestamp, locale=en_US, timezone=Z)

Format time as Thursday 18 November 2021, 22:59 using US locale and PST timezone using the as parameter to fmttime:

logscale
formattime("%A %d %B %Y, %R", as=fmttime, field=@timestamp, timezone=PST)

Format time variant where the unit is explicit:

logscale
formattime("%A %d %B %Y, %R", as=fmttime, field=@timestamp, timezone=PST, unit=milliseconds)

Formatting a time where the unit is explicit and the supplied value is a floating-point figure:

logscale
regex(field=InstallDate, "(?<InstallDate>\\d+)")
| formattime("%A %d %B %Y, %R", as=fmttime, field=InstallDate, timezone=PST, unit=seconds)

In the above example, only the digits are extracted through the regular expression and then used as the basis for the formatTime() call.