Logstash 参考指南（Date过滤器插件）

Date过滤器插件

• 插件版本：v3.1.9
• 发布于：2017-11-07
• 更改日志

其他版本，请参阅版本化的插件文档。

获取帮助

有关插件的问题，请在讨论论坛中打开一个主题，对于bug或特性请求，在Github中打开一个issue，关于Elastic支持的插件列表，请考虑Elastic支持矩阵。

描述

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]匹配其值，有关更多信息，请参阅字段参考资料
• 关于语法的更多细节
• 用于解析日期和时间文本的语法使用字母表示时间值的类型（月份、分钟等），重复使用字母表示该值的形式（两位数的月份、完整的月份名称等）。
• 下面是用来解析日期和时间的方法：

• 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可用时区页面上。
• 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文档中了解。

tag_on_failure

• 值类型为array
• 默认值为["_dateparsefailure"]
• 当没有成功匹配时，将值附加到tags字段

target

• 值类型为string
• 默认值为"@timestamp"
• 将匹配的时间戳存储到给定的目标字段中，如果没有提供，默认更新事件的@timestamp字段。

timezone

• 值类型为string
• 此设置没有默认值
• 指定用于日期解析的时区规范ID，有效的id列在Joda.org可用时区页面上，这在无法从值中提取时区时非常有用，而且不是平台默认值。如果没有指定，将使用平台默认值，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的标记。