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

ParameterTypeRequiredDefaultDescription
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.

[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.