Formats a string according to strftime,
similar to unix strftime.
| Parameter | Type | Required | Default | 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 table below. | |
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 Timezones. 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. (introduced in 1.113.0) |
| 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 | ||||
Omitted Argument NamesThe argument name for
formatcan be omitted; the following forms of this function are equivalent:logscaleformatTime("value",as="value")and:
logscaleformatTime(format="value",as="value")These examples show basic structure only; full examples are provided below.
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:
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:
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.