事件 API

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

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

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

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

获取 API

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

语法： 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"

设置 API

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

语法： event.set(field, value)

返回值：突变后的当前 Event，可用于链式调用。

示例

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")

在 Event 中设置集合后对其进行突变具有未定义的行为，并且不允许。

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 代码并使用上面描述的 API 操作事件数据。例如，使用新的 API

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

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