Formats a string according to
strftime, similar to unix
strftime.
| Parameter | Type | Required | Default Value | Description |
|---|---|---|---|---|
as | string | required | Specifies the output field. | |
field | string | optional[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] | string | required | Format string. A subset of Java Date/Time escapes is supported by LogScale, see the following table. | |
locale | string | optional[a] | Specifies the locale such as US or en_GB. | |
timezone | string | optional[a] | UTC | Specifies the timezone such as GMT, EST or Europe/London. See the full list of timezones supported by LogScale at Supported Time Zones. If no timezone is present, UTC is used. |
unit | string | optional[a] | auto | Controls whether the value in field is interpreted as seconds or milliseconds. |
| Valid Values | ||||
auto | If the number is less than or equals to 100,000,000,000, it's interpreted as seconds, otherwise it's interpreted as milliseconds. | |||
milliseconds | The number is unconditionally interpreted as milliseconds. | |||
seconds | The number is unconditionally interpreted as seconds. | |||
[a] Optional parameters use their default value unless explicitly set. | ||||
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. 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 specifying the
unit, the value
must be a long integer and not a floating point value.
formatTime() Syntax Examples
Format time as 2021/11/26 06:54:45 using the
timestamp field and
UTC timezone using assignment to
fmttime:
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 time zone setting the as
parameter to fmttime:
formatTime("%A %d %B %Y, %R", as=fmttime, field=@timestamp, timezone=PST)Format time variant where the unit is explicit:
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:
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.
formatTime() Examples
Click next to an example below to get the full details.
Sort Timestamps With groupBy()
Sorting fields based on aggregated field values