事件 API
编辑事件 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 的新字段