[[processor-timestamp]]
=== Timestamp

beta[]

The `timestamp` processor parses a timestamp from a field. By default the
timestamp processor writes the parsed result to the `@timestamp` field. You can
specify a different field by setting the `target_field` parameter. The timestamp
value is parsed according to the `layouts` parameter. Multiple layouts can be
specified and they will be used sequentially to attempt parsing the timestamp
field.

NOTE: The timestamp layouts used by this processor are different than the
      formats supported by date processors in Logstash and Elasticsearch Ingest
      Node.

The `layouts` are described using a reference time that is based on this
specific time:

    Mon Jan 2 15:04:05 MST 2006

Since MST is GMT-0700, the reference time is:

    01/02 03:04:05PM '06 -0700

To define your own layout, rewrite the reference time in a format that matches
the timestamps you expect to parse. For more layout examples and details see the
https://godoc.org/time#pkg-constants[Go time package documentation].

If a layout does not contain a year then the current year in the specified
`timezone` is added to the time value.

.Timestamp options
[options="header"]
|======
| Name             | Required | Default    | Description                                                                                                           |
| `field`          | yes      |            | Source field containing the time to be parsed.                                                                        |
| `target_field`   | no       | @timestamp | Target field for the parsed time value. The target value is always written as UTC.                                    |
| `layouts`        | yes      |            | Timestamp layouts that define the expected time value format. In addition layouts, `UNIX` and `UNIX_MS` are accepted. |
| `timezone`       | no       | UTC        | Timezone (e.g. America/New_York) to use when parsing a timestamp not containing a timezone.                           |
| `ignore_missing` | no       | false      | Ignore errors when the source field is missing.                                                                       |
| `ignore_failure` | no       | false      | Ignore all errors produced by the processor.                                                                          |
| `test`           | no       |            | A list of timestamps that must parse successfully when loading the processor.                                         |
| `id`             | no       |            | An identifier for this processor instance. Useful for debugging.                                                      |
|======

Here is an example that parses the `start_time` field and writes the result
to the `@timestamp` field then deletes the `start_time` field. When the
processor is loaded it will immediately validate that the two `test` timestamps
parse with this configuration.

[source,yaml]
----
processors:
- timestamp:
    field: start_time
    layouts:
      - '2006-01-02T15:04:05Z'
      - '2006-01-02T15:04:05.999Z'
    test:
      - '2019-06-22T16:33:51Z'
      - '2019-11-18T04:59:51.123Z'
- drop_fields:
    fields: [start_time]
----
