findTimestamp( ) Query Function

Finds a timestamp in the given field and parses it, trying different formats for timestamps. The function returns the first timestamp in the field that matches one of its formats. It only finds timestamp starting within the first 128 characters of the text (configurable in parameter MAX_CHARS_TO_FIND_TIMESTAMP).

This function is primarily meant to be used in generic parsers that can be used for different event types. If the format of the timestamp is known, consider using the parseTimestamp function instead.

The function supports the following formats:

  • year month day hour minute second [subsecond] [timezone]
  • month day [year] hour minute second [subsecond] [timezone]
  • month day hour minute second [subsecond] [timezone] year4
  • day monthLetter [year4] hour minute second [subsecond] [timezone]
  • hour minute second [subsecond] [timezone]
  • epochsecond [subsecond]

Values within brackets (e.g., [timezone]) means that it’s optional.

The different parts mean the following:

Type Description
year The year with either two or four digits.
year4 The year with four digits.
month The month as two digits or three letters (e.g., Jan)
monthLetter The month as three letters (e.g., Jan)
day The day as two digits.
hour The hour as two digits (0-23 or 1-12)
minute The minutes as two digits.
second The seconds as two digits.
subsecond The sub-seconds as one to nine digits, for Unix epoch time only 3, 6 or 9 digits
timezone The timezone as either a named timezone (e.g. UTC or America/New_York) or an offset (e.g. UTC+12:30)
epochsecond The seconds since Unix epoch (01-01-1970 00:00:00 UTC) as 10 digits.

If the timezone is missing, the timezone parameter is used. Note that if timestamps are written in a timezone with Daylight Saving Time, it is recommended that the timezone is present and written as an offset. Otherwise, when switching from Dayligt Saving Time to standard time, there is no way to differentiate between the last hour before the switch and the first hour after.

If the date (year, month and day) is missing, today is used if the time is at most 10 minutes into the future, otherwise, yesterday is used.

If the year is missing, the largest of last year, this year and next year is used so that the date is at most 7 days into the future.

If the year is only 2 digits, it is assumed to be between 2013 and 2099. If you need to parse dates before 2013 with only 2 digits for year, you need to use the parseTimestamp function instead.

Leap seconds are ignored, so 60 seconds is converted to 59 seconds.

Up to 9 digits of sub seconds are accepted, but since timestamps are stored with millisecond precision, only the first 3 digits are used.

If a timestamp is found, two fields are added to the event. One contains the parsed timestamp in milliseconds since Unix epoch (01-01-1970 00:00:00 UTC) and gets its name from the as parameter. The other contains the parsed timezone, if available, and otherwise the timezone parameter, and gets its name from the timezoneAs parameter.

Parameters

Name Type Required Default Description
field string No @rawstring The field to search for a timestamp.
timezone string No UTC If the timestamp does not contain a timezone, this timezone is used. The timezone can be specified as a named timezone or as an offset. Example are Europe/London, America/New_York, UTC or UTC+12:30. See the full list of supported named timezones.
as string No @timestamp The output field that will contain the parsed timestamp. The timestamp is represented as milliseconds since Unix epoch (01-01-1970 00:00:00 UTC). Humio expects to find the timestamp for the event in the field @timestamp, so do not set this parameter to anything else in a parser.
timezoneAs string No @timezone The output field that will contain the parsed timezone. Humio expects to find the timezone for the event in the field @timezone, so do not set this parameter to anything else in a parser.
addErrors bool No true Whether to add an error field to the event, if it was not possible to find a timestamp.

findTimestamp has no unnamed parameter.

Examples

In a parser with UTC as default timezone.

findTimestamp()

In a parser with America/New_York as default timezone.

findTimestamp(timezone="America/New_York")

In a parser where the timestamp is located in a field named date.

findTimestamp(field=date, timezone="Europe/London")

In a query function where the timestamp should be stored in a field datetime and the timezone in a field tz.

findTimestamp(as="datetime", timezoneAs="tz")