事件 API

本节针对插件开发者和 Logstash Ruby 过滤器的用户。下面我们将记录用户在自定义插件和 Ruby 过滤器中访问 Logstash 基于事件的数据方式的最新变化（从 5.0 版本开始）。请注意，访问事件数据和字段 Logstash 配置文件中的数据流（使用 字段引用）不受此更改的影响，并将继续使用现有语法。

事件对象编辑

事件是封装 Logstash 内部数据流的主要对象，并为插件开发者提供了一个 API 来与事件内容进行交互。通常，此 API 用于插件和 Ruby 过滤器中，以检索数据并将其用于转换。事件对象包含发送到 Logstash 的原始数据以及在 Logstash 的过滤器阶段创建的任何附加字段。

在 5.0 中，我们使用纯 Java 重新实现了 Event 类及其支持类。由于 Event 是数据处理中的关键组件，因此使用 Java 重写可以提高性能，并在将数据存储到磁盘时提供高效的序列化。在很大程度上，此更改旨在保持向后兼容性，对用户来说是透明的。为此，我们更新并发布了 Logstash 生态系统中的大多数插件，以符合新的 API 更改。但是，如果您维护自定义插件或使用 Ruby 过滤器，此更改将影响您。本指南的目的是描述新的 API 并提供示例以迁移到新的更改。

事件 API编辑

在 5.0 版本之前，开发者可以通过直接使用 Ruby 哈希语法来访问和操作事件数据。例如，event[field] = foo。虽然这很强大，但我们的目标是抽象内部实现细节并提供定义明确的 getter 和 setter API。

Get API

getter 是对事件中基于字段的数据的只读访问。

语法： event.get(field)

返回值： 此字段的值，如果字段不存在则为 nil。返回值可以是字符串、数字或时间戳标量值。

field 是发送到 Logstash 或在转换过程后创建的结构化字段。 field 也可以是嵌套的 字段引用，例如 [field][bar]。

示例

event.get("foo" ) # => "baz"
event.get("[foo]") # => "zab"
event.get("[foo][bar]") # => 1
event.get("[foo][bar]") # => 1.0
event.get("[foo][bar]") # =>  [1, 2, 3]
event.get("[foo][bar]") # => {"a" => 1, "b" => 2}
event.get("[foo][bar]") # =>  {"a" => 1, "b" => 2, "c" => [1, 2]}

访问 @metadata

event.get("[@metadata][foo]") # => "baz"

Set API

此 API 可用于更改事件中的数据。

语法： event.set(field, value)

返回值： 更改后的当前事件，可用于链式调用。

示例

event.set("foo", "baz")
event.set("[foo]", "zab")
event.set("[foo][bar]", 1)
event.set("[foo][bar]", 1.0)
event.set("[foo][bar]", [1, 2, 3])
event.set("[foo][bar]", {"a" => 1, "b" => 2})
event.set("[foo][bar]", {"a" => 1, "b" => 2, "c" => [1, 2]})
event.set("[@metadata][foo]", "baz")

在事件中设置集合后，对集合进行更改的行为未定义，不允许。

h = {"a" => 1, "b" => 2, "c" => [1, 2]}
event.set("[foo][bar]", h)

h["c"] = [3, 4]
event.get("[foo][bar][c]") # => undefined

Suggested way of mutating collections:

h = {"a" => 1, "b" => 2, "c" => [1, 2]}
event.set("[foo][bar]", h)

h["c"] = [3, 4]
event.set("[foo][bar]", h)

# Alternatively,
event.set("[foo][bar][c]", [3, 4])

Ruby 过滤器编辑

Ruby 过滤器 可用于执行任何 ruby 代码并使用上面描述的 API 操作事件数据。例如，使用新的 API

filter {
  ruby {
    code => 'event.set("lowercase_field", event.get("message").downcase)'
  }
}

此过滤器将使 message 字段小写，并将其设置为名为 lowercase_field 的新字段