Parses a string into a timestamp.
This function is important for creating parsers, as it is used to parse the timestamp for an incoming event.
| Parameter | Type | Required | Default Value | Description | |
|---|---|---|---|---|---|
addErrors | boolean | optional[a] | true | Whether to add an error field to the event, if it was not possible to find a timestamp. | |
as | string | optional[a] | @timestamp | Name of output field that will contain the parsed timestamp. The timestamp is represented as milliseconds since 1970 in UTC. LogScale expects to find the timestamp in the field @timestamp, so do not change this when creating parsers. | |
caseSensitive | boolean | optional[a] | true | Whether the timestamp format pattern is case sensitive. For example, the format LLL will accept Feb but not feb in case sensitive mode, while both will be accepted in case insensitive mode. | |
| Valid Values | |||||
false | Pattern is not case sensitive | ||||
true | Pattern is case sensitive | ||||
field | string | required | The field holding the timestamp to be parsed. | ||
format[b] | string | optional[a] | yyyy-MM-ddTHH:mm:ss[.SSS]XXX | Pattern used to parse the timestamp. Either a format string as specified in Java's DateTimeFormatter, or one of the special format specifiers (these specifiers are not case-sensitive, that is, MilliSeconds works as well). | |
| Valid Values | |||||
millis | Epoch time in milliseconds (UTC) | ||||
milliseconds | Epoch time in milliseconds (UTC) | ||||
nanos | Epoch time in nanoseconds (UTC) | ||||
seconds | Epoch time in seconds (UTC) | ||||
unixTimeMillis | Epoch time in milliseconds (UTC) | ||||
unixTimeSeconds | Epoch time in seconds (UTC) | ||||
unixtime | Epoch time in seconds (UTC) | ||||
timezone | string | optional[a] | If the timestamp does not contain a timezone, it can be specified using this parameter. Example are Europe/London, America/New_York and UTC. See the full list of timezones supported by LogScale at Supported Timezones. | ||
timezoneAs | string | optional[a] | @timezone | Name of output field that will contain the parsed timezone. LogScale expects to find the timezone in the field @timezone , so do not change when creating parsers. | |
[a] Optional parameters use their default value unless explicitly set. | |||||
Hide omitted argument names for this function
Omitted Argument NamesThe argument name for
formatcan be omitted; the following forms of this function are equivalent:logscaleparseTimestamp("millis",field="value")and:
logscaleparseTimestamp(format="millis",field="value")These examples show basic structure only.
Before parsing the timestamp, the part of the log containing the timestamp
should have been captured in af field. Typically this is done during
parsing, but can extract during queries using functions like
regex() and parseJson() before
parseTimestamp().
The parseTimestamp() function formats times using a
subset of
Java's
DateTimeFormatter.
LogScale also supports some special format strings like
seconds,
milliseconds, and
unixtime (see in table below the
description of the
format parameter for a
full list of options).
unixtimeMillisUTC time since 1970 in millisecondsunixtimeUTC time since 1970 in seconds
For the special formats that specify seconds (that is
seconds, unixtime, and
unixtimeseconds), the function also supports specifying
milliseconds using floating point numbers.
For example, 1690480444.589 means 2023-07-27 19:54:04
and 589 milliseconds.
LogScale can also parse timestamps that use nanosecond precision, the nanosecond component will be extracted during the process. For example:
nanos := 1451606399999998965
parseTimestamp("nanos")
Would extract 2024-03-07 12:04:14
and 547998965 nanoseconds.
If the timestamp is parsed it will create a field @timestamp containing the parsed timestamp in UTC milliseconds and a @timezone field containing the original timezone.
It is possible to parse time formats leaving out the year designator as is
sometime seen in time formats from Syslog. For example
Mar 15 07:48:13 can be parsed using the
format MM d HH:mm:ss. In this case
LogScale will guess the year.
parseTimestamp() Examples
Extract a timestamp that is using millisecond precision embedded in a JSON value:
parseJson()
| parseTimestamp("millis", field=timestamp)Events having a timestamp in ISO8601 format that include a timezone offset can be parsed using the default format:
expiryTime := "2018-09-08 17:51:04.777Z"
| parseTimestamp(field=expiryTime)
Another example is a timestamp like
2017-12-18T20:39:35-04:00:
/(?<timestamp>\S+)/
| parseTimestamp(field=timestamp)
Parse timestamps in an accesslog where the timestamp includes an
explicit timezone offset like 192.168.1.19
[02/Apr/2014:16:29:32 +0200] GET /hello/test/123 ...
/(?<client>\S+) \[(?<@timestamp>.+)\] (?<method>\S+) (?<url>\S+)/
| parseTimestamp("dd/MMM/yyyy:HH:mm:ss Z", field=timestamp)
When parsing a timestamp without a timezone like
2015-12-18T20:39:35 you must declare to
LogScale what timezone a given time should be located:
parseTimestamp("yyyy-MM-ddTHH:mm:ss", field=timestamp, timezone="America/New_York")
Parse an event with a timestamp not containing year, like
Feb 9 12:22:44 hello world
/(?<timestamp>\S+\s+\S+\s+\S+)/
| parseTimestamp("MMM [ ]d HH:mm:ss", field=timestamp, timezone="Europe/London")