timestamp stage

The timestamp stage is an action stage that can change the timestamp of a logline before it is sent to Loki. When a timestamp stage is not present, thetimestamp of a log line defaults to the time when the log entry is scraped.

Schema

  1. timestamp:
  2.   # Name from extracted data to use for the timestamp.
  3.   source: <string>
  5.   # Determines how to parse the time string. Can use
  6.   # pre-defined formats by name: [ANSIC UnixDate RubyDate RFC822
  7.   # RFC822Z RFC850 RFC1123 RFC1123Z RFC3339 RFC3339Nano Unix
  8.   # UnixMs UnixNs].
  9.   format: <string>
  11.   # IANA Timezone Database string.
  12.   [location: <string>]
  14.   # Which action should be taken in case the timestamp can't
  15.   # be extracted or parsed. Valid values are: [skip, fudge].
  16.   # Defaults to "fudge".
  17.   [action_on_failure: <string>]

The format field can be provided as an “example” of what timestamps look like(such as Mon Jan 02 15:04:05 -0700 2006) but Promtail accepts using a seriesof pre-defined formats to represent common forms:

  • ANSIC: Mon Jan _2 15:04:05 2006
  • UnixDate: Mon Jan _2 15:04:05 MST 2006
  • RubyDate: Mon Jan 02 15:04:05 -0700 2006
  • RFC822: 02 Jan 06 15:04 MST
  • RFC822Z: 02 Jan 06 15:04 -0700
  • RFC850: Monday, 02-Jan-06 15:04:05 MST
  • RFC1123: Mon, 02 Jan 2006 15:04:05 MST
  • RFC1123Z: Mon, 02 Jan 2006 15:04:05 -0700
  • RFC3339: 2006-01-02T15:04:05-07:00
  • RFC3339Nano: 2006-01-02T15:04:05.999999999-07:00

Additionally, support for common Unix timestamps is supported with the followingformat values:

  • Unix: 1562708916
  • UnixMs: 1562708916414
  • UnixNs: 1562708916000000123

Custom formats are passed directly to the layout parameter in Go’stime.Parse function. If the custom formathas no year component specified, Promtail will assume that the current yearaccording to the system’s clock should be used.

The syntax used by the custom format defines the reference date and time usingspecific values for each component of the timestamp (i.e., Mon Jan 2 15:04:05 -0700 MST 2006). The following table shows supported reference values whichshould be used in the custom format.

Timestamp component Format value
Year 06, 2006
Month 1, 01, Jan, January
Day 2, 02, _2 (two digits right justified)
Day of the week Mon, Monday
Hour 3 (12-hour), 03 (12-hour zero prefixed), 15 (24-hour)
Minute 4, 04
Second 5, 05
Fraction of second .000 (ms zero prefixed), .000000 (μs), .000000000 (ns), .999 (ms without trailing zeroes), .999999 (μs), .999999999 (ns)
12-hour period pm, PM
Timezone name MST
Timezone offset -0700, -070000 (with seconds), -07, 07:00, -07:00:00 (with seconds)
Timezone ISO-8601 Z0700 (Z for UTC or time offset), Z070000, Z07, Z07:00, Z07:00:00

The action_on_failure setting defines which action should be taken by thestage in case the source field doesn’t exist in the extracted data or thetimestamp parsing fails. The supported actions are:

  • fudge (default): change the timestamp to the last known timestamp, summingup 1 nanosecond (to guarantee log entries ordering)
  • skip: do not change the timestamp and keep the time when the log entry hasbeen scraped by Promtail

Examples

  1. - timestamp:
  2.     source: time
  3.     format: RFC3339Nano

This stage looks for a time field in the extracted map and reads its value inRFC3339Nano form (e.g., 2006-01-02T15:04:05.999999999-07:00). The resultingtime value will be used as the timestamp sent with the log line to Loki.