[TOC]
## 描述
date过滤器用于解析字段中的日期，然后使用该日期或时间戳作为事件的logstash时间戳。
例如，syslog事件通常有这样的时间戳：
~~~
"Apr 17 09:32:01"
~~~
你应该使用`MMM dd HH:mm:ss`的日期格式来解析这个。
日期过滤器对于事件的排序和对旧数据的回填特别重要，如果在你的事件中没有得到正确的日期，那么以后搜索它们可能会出现顺序不对。
如果没有这个过滤器，logstash将根据第一次看到事件（在输入时）的时间（如果时间戳还没有在事件中设置）选择一个时间戳，例如，对于文件输入，时间戳被设置为每次读取的时间。
## Date过滤器配置选项
这个插件支持以下配置选项以及后面描述的通用选项。
| 设置 | 输入类型 | 要求 |
| --- | --- | --- |
| `locale` | string | No |
| `match` | array | No |
| `tag_on_failure` | array | No |
| `target` | string | No |
| `timezone` | string | No |
还可以查看所有过滤器插件支持的选项列表的通用选项。
`locale`
* 值类型为string
* 此设置没有默认值
* 使用IETF-BCP47或POSIX语言标记指定要用于日期解析的语言环境，简单的例子有`en`，`en-US`代表BCP47，`en_US`代表POSIX。
* 对于解析月份名称（带有`MMM`的模式）和工作日名称（带有`EEE`的模式），通常需要设置语言环境。
* 如果没有指定，将使用平台默认值，但对于非英语平台默认值，还将使用英语解析器作为回退机制。
`match`
* 值类型为array
* 默认值为`[]`
* 首先是字段名，然后是格式模式的数组，`[ field, formats... ]`
* 如果你的时间字段有多种可能的格式，你可以这样做：
~~~
match => [ "logdate", "MMM dd yyyy HH:mm:ss",
"MMM d yyyy HH:mm:ss", "ISO8601" ]
~~~
* 以上内容将匹配syslog（rfc3164）或`iso8601`时间戳。
* 有一些特殊的例外，下面的格式文字可以帮助你节省时间并确保数据解析的正确性。
* `ISO8601` - 可以解析任何有效的ISO8601时间戳，像：`2011-04-19T03:44:01.103Z`
* `UNIX` - 解析**float或int**值表示自纪元以来的unix时间（如1326149001秒），132和1326149001一样。
* `UNIX_MS` - 解析**int**值表示自纪元以来的unix时间（如1366125117000毫秒）
* `TAI64N` - 会解析tai64n时间值
* 例如，如果你有一个字段`logdate`，其值类似于`Aug 13 2010 00:03:44`，那么你将使用这个配置：
~~~
filter {
date {
match => [ "logdate", "MMM dd yyyy HH:mm:ss" ]
}
}
~~~
* 如果字段嵌套在结构中，可以使用嵌套语法`[foo][bar]`匹配其值，有关更多信息，请参阅[字段参考资料](https://segmentfault.com/a/1190000016594400)
* **关于语法的更多细节**
* 用于解析日期和时间文本的语法使用字母表示时间值的类型（月份、分钟等），重复使用字母表示该值的形式（两位数的月份、完整的月份名称等）。
* 下面是用来解析日期和时间的方法：
* y 年
* yyyy => 全年数字，例如：`2015`。
* yy => 两位数的年，例如：`15`代表`2015`年。
* M 一年中的月份
* M => 最小位数的月份，例如：`1`为1月，`12`为12月。
* MM => 两位数的月份，如果需要将用零填充，例如：`01`为1月，`12`为12月。
* MMM => 缩写月文本，例如：`Jan`为1月，注意：使用的语言取决于你的语言环境，查看`locale`设置如何更改语言。
* MMMM => 全月的文本，例如：`January`，注意：使用的语言取决于你的语言环境。
* d 一月中的天
* d => 最小位数的天，例如：`1`为一个月的第一天。
* dd => 两位数的天，如果需要将用零填充，例如：`01`为一个月的第一天。
* H 一天中的小时（24小时时钟）
* H => 最小位数的小时，例如：`0`为午夜。
* HH => 两位数的小时，如果需要，零填充，例如：`00`为午夜。
* m 一小时中的分钟（每小时60分钟）
* m => 最小位数的分钟，例如：`0`。
* mm => 两位数的分钟，如果需要，零填充，例如：`00`。
* s 一分钟中的秒（每分钟60秒）
* s => 最小位数的秒，例如：`0`。
* ss => 两位数的秒，如果需要，零填充，例如：`00`。
* S 每秒最大精度的分数为毫秒(`SSS`)，超过这个，追加零
* S => 十分之一秒，例如：`0`表示亚秒值`012`。
* SS => 百分之一秒，例如：`01`为亚秒值`01`。
* SSS => 千分之一秒，例如：`012`为亚秒值012。
* Z 时区偏移或标识
* Z => 时区偏移结构为HHmm（Zulu/UTC的小时和分钟偏移），例如：`-0700`。
* ZZ => 时区偏移结构为HH:mm（在小时和分钟偏移量之间的冒号），例如：`-07:00`。
* ZZZ => 时区的标识，例如：`America/Los_Angeles`，注意：有效的id列在[Joda.org可用时区页面](http://joda-time.sourceforge.net/timezones.html)上。
* z 时区名称，**无法解析时区名称（z）**。
* w 一年中的周
* w => 最小位数的周，例如：`1`。
* ww => 两位数的周，如果需要，零填充，例如：`01`。
* D 一年中的天
* e 一周中的星期（数字）
* E 一周中的星期（文本）
* E, EE, EEE => 一周中缩短的星期，例如：`Mon`，`Tue`，`Wed`，`Thu`，`Fri`，`Sat`，`Sun`，注意：它的实际语言取决于你的语言环境。
* EEEE => 一周的星期全称，例如：`Monday`，`Tuesday`，...，注意：它的实际语言取决于你的语言环境。
* 对于非格式化语法，需要在值周围放置单引号字符，例如，如果你正在解析ISO8601时间，"2015-01-01T01:12:23"那个“T”不是有效的事件格式，并且你你可能想说"字面上的一个T"，你的格式应该是这样："yyyy-MM-dd’T'HH:mm:ss"。
* 其他不太常见的日期单元，如era（G）、century（C）、am/pm（a）和#更多，可以在[joda-time文档中了解](http://www.joda.org/joda-time/key_format.html)。
`tag_on_failure`
* 值类型为array
* 默认值为`["_dateparsefailure"]`
* 当没有成功匹配时，将值附加到`tags`字段
`target`
* 值类型为string
* 默认值为`"@timestamp"`
* 将匹配的时间戳存储到给定的目标字段中，如果没有提供，默认更新事件的`@timestamp`字段。
`timezone`
* 值类型为string
* 此设置没有默认值
* 指定用于日期解析的时区规范ID，有效的id列在[Joda.org可用时区页面](http://joda-time.sourceforge.net/timezones.html)上，这在无法从值中提取时区时非常有用，而且不是平台默认值。如果没有指定，将使用平台默认值，Canonical ID很好，因为它为你处理了夏令时，例如，`America/Los_Angeles`或`Europe/Paris`是有效的id。该字段可以是动态的，并使用`%{field}`语法包含事件的一部分。
## 通用选项
所有过滤器插件都支持以下配置选项：
| 设置 | 输入类型 | 要求 |
| --- | --- | --- |
| `add_field` | hash | No |
| `add_tag` | array | No |
| `enable_metric` | boolean | No |
| `id` | string | No |
| `periodic_flush` | boolean | No |
| `remove_field` | array | No |
| `remove_tag` | array | No |
`add_field`
* 值类型为hash
* 默认值为`{}`
* 如果此过滤器成功，则向此事件添加任意字段，字段名可以是动态的，并使用`%{field}`包含事件的一部分。
* 例如：
~~~
filter {
date {
add_field => { "foo_%{somefield}" => "Hello world, from %{host}" }
}
}
~~~
~~~
# You can also add multiple fields at once:
filter {
date {
add_field => {
"foo_%{somefield}" => "Hello world, from %{host}"
"new_field" => "new_static_value"
}
}
}
~~~
* 如果事件具有字段`“somefield”==“hello”`，那么在成功时，这个过滤器将添加字段`foo_hello`（如果存在的话），上面的值和`%{host}`块将被事件中的值替换，第二个示例还将添加硬编码字段。
`add_tag`
* 值类型为array
* 默认值为`[]`
* 如果此过滤器成功，则向事件添加任意tags，tags可以是动态的，并使用`%{field}`语法包含事件的一部分。
* 例如：
~~~
filter {
date {
add_tag => [ "foo_%{somefield}" ]
}
}
~~~
~~~
# You can also add multiple tags at once:
filter {
date {
add_tag => [ "foo_%{somefield}", "taggedy_tag"]
}
}
~~~
* 如果事件有字段`“somefield”==“hello”`，这个过滤器在成功时，会添加一个标签`foo_hello`（第二个例子当然会添加一个`taggedy_tag`标签）。
`enable_metric`
* 值类型为boolean
* 默认值为`true`
* 默认情况下，我们会记录所有可以记录的指标，但你可以为特定的插件禁用指标集合。
`id`
* 值类型为string
* 此设置没有默认值
* 在插件配置中添加唯一的`ID`，如果没有指定ID，则Logstash将生成一个，强烈建议在配置中设置此ID，当你有两个或多个相同类型的插件时，这一点特别有用。例如，如果你有两个电子邮件输出，在本例中添加一个命名ID将有助于在使用监控API时监控Logstash。
~~~
filter {
date {
id => "ABC"
}
}
~~~
`periodic_flush`
* 值类型为boolean
* 默认值为`false`
* 定期调用过滤器flush方法，可选的。
`remove_field`
* 值类型为array
* 默认值为`[]`
* 如果此过滤器成功，则从此事件中删除任意字段，例如：
~~~
filter {
date {
remove_field => [ "foo_%{somefield}" ]
}
}
~~~
~~~
# You can also remove multiple fields at once:
filter {
date {
remove_field => [ "foo_%{somefield}", "my_extraneous_field" ]
}
}
~~~
* 如果事件中有字段`“somefield”==“hello”`，那么在成功时，如果存在名为`foo_hello`的字段，这个过滤器将删除该字段，第二个示例将删除一个额外的非动态字段。
`remove_tag`
* 值类型为array
* 默认值为`[]`
* 如果此过滤器成功，则从事件中删除任意tags，tags可以是动态的，并使用`%{field}`语法包含事件的一部分。
* 例如：
~~~
filter {
date {
remove_tag => [ "foo_%{somefield}" ]
}
}
~~~
~~~
# You can also remove multiple tags at once:
filter {
date {
remove_tag => [ "foo_%{somefield}", "sad_unwanted_tag"]
}
}
~~~
* 如果事件有字段`“somefield”==“hello”`，这个过滤器在成功时，会删除标签`foo_hello`如果它存在，第二个示例还将删除一个sad、unwanted的标记。
