目录
1.9.生成插件(Generating Pluginsedit)
1.10.离线插件管理(Offline Plugin Management)
1.10.1.构建离线插件包(Building Offline Plugin Packs)
1.使用插件
Logstash具有丰富的输入,过滤器,编解码器和输出插件集合。 插件以称为gems的自包含软件包形式提供,并托管在RubyGems.org上。 通过bin / logstash-plugin脚本访问的插件管理器用于管理Logstash部署中插件的生命周期。 您可以使用下面描述的命令行界面(CLI)调用来安装,删除和升级插件。
1.1.代理配置(Proxy configuration)
大部分插件管理器命令都需要访问Internet才能访问RubyGems.org。 如果您的组织位于防火墙后面,则可以设置这些环境变量以将Logstash配置为使用代理。
export http_proxy=http://localhost:3128
export https_proxy=http://localhost:3128
1.2.列出插件(Listing plugins)
Logstash发行包捆绑了常见插件,因此您可以立即使用它们。 列出部署中当前可用的插件:
bin/logstash-plugin list
bin/logstash-plugin list --verbose
bin/logstash-plugin list '*namefragment*'
bin/logstash-plugin list --group output
- 将列出所有已安装的插件
- 将列出已安装的插件以及版本信息
- 将列出所有安装的包含名称片段的插件
- 将列出特定组的所有已安装插件(输入,过滤器,编解码器,输出)
1.3.将插件添加到您的部署中
处理插件安装时最常见的情况是可以访问Internet。 使用此方法,您将能够检索公共资源库(RubyGems.org)上托管的插件,并在Logstash安装的顶部进行安装。
bin/logstash-plugin install logstash-output-kafka
成功安装插件后,您可以在配置文件中开始使用它。
1.4.高级:添加本地构建的插件
在某些情况下,您想安装尚未发布且未托管在RubyGems.org上的插件。 Logstash为您提供了安装本地构建的插件的选项,该插件打包为ruby gem。 使用文件位置:
bin/logstash-plugin install /path/to/logstash-output-kafka-1.0.0.gem
1.5.高级:Using --path.plugins
使用Logstash --path.plugins标志,可以加载位于文件系统上的插件源代码。 通常,开发人员在定制插件上进行迭代并想要在创建ruby gem之前对其进行测试,以供使用。
该路径必须位于特定的目录层次结构中:PATH / logstash / TYPE / NAME.rb,其中TYPE是输入过滤器,输出或编解码器,而NAME是插件的名称。
# supposing the code is in /opt/shared/lib/logstash/inputs/my-custom-plugin-code.rb
bin/logstash --path.plugins /opt/shared/lib
1.6.更新插件
插件具有自己的发布周期,并且通常独立于Logstash的核心发布周期进行发布。 使用update子命令,您可以获得插件的最新版本。
bin/logstash-plugin update
bin/logstash-plugin update logstash-output-kafka
- 将更新所有已安装的插件
- 将仅更新此插件
1.7.删除插件
如果您需要从Logstash安装中删除插件,请执行以下操作:
bin/logstash-plugin remove logstash-output-kafka
1.8.代理支持
前面的部分依靠Logstash能够与RubyGems.org进行通信。 在某些环境中,转发代理用于处理HTTP请求。 可以通过设置HTTP_PROXY环境变量来通过代理安装和更新Logstash插件:
export HTTP_PROXY=http://127.0.0.1:3128
bin/logstash-plugin install logstash-output-kafka
设置后,将安装插件命令,并可以通过此代理使用更新。
1.9.生成插件(Generating Pluginsedit)
您现在可以在几秒钟内创建自己的Logstash插件! bin/logstash-plugin 的generate子命令为带有模板文件的新Logstash插件创建基础。 它会创建正确的目录结构,gemspec文件和相关性,因此您可以开始添加自定义代码来使用Logstash处理数据。
用法示例
bin/logstash-plugin generate --type input --name xkcd --path ~/ws/elastic/plugins
--type
: 插件类型 - input, filter, output, or codec--name
: 新插件的名称--path
: 将在其中创建新插件结构的目录路径。 如果未指定,它将在当前目录中创建。
1.10.离线插件管理(Offline Plugin Management)
Logstash插件管理器提供了对准备脱机插件包的支持,您可以使用它们来在无法访问Internet的系统上安装Logstash插件。
此过程需要运行Logstash的登台计算机,该登台计算机有权访问公共或私有Rubygems服务器。 登台计算机下载并打包脱机安装所需的所有文件和依赖项。
1.10.1.构建离线插件包(Building Offline Plugin Packs)
离线插件包是一个压缩文件,其中包含您的离线Logstash安装所需的所有插件,以及这些插件的依赖性。
要构建离线插件包:
1.确保要打包的所有插件都已安装在登台服务器上,并且该登台服务器可以访问Internet。
2.运行bin/logstash-plugin prepare-offline-pack子命令来打包插件和依赖项:
bin/logstash-plugin prepare-offline-pack --output OUTPUT [PLUGINS] --overwrite
where:
OUTPUT 指定将压缩的插件包写入的zip文件。 默认文件是 /LOGSTASH_HOME/logstash-offline-plugins-7.4.1.zip
。 如果您使用的是5.2.x和5.3.0,则此位置应该是一个zip文件,其内容将被覆盖。
[PLUGINS] 指定要包含在包中的一个或多个插件。
--overwrite 指定是否要覆盖该位置的现有文件
例子:
bin/logstash-plugin prepare-offline-pack logstash-input-beats
bin/logstash-plugin prepare-offline-pack logstash-filter-*
bin/logstash-plugin prepare-offline-pack logstash-filter-* logstash-input-beats
- 打包Beats输入插件和所有依赖项。
- 使用通配符打包所有过滤器插件和所有依赖项。
- 打包所有过滤器插件,Beats输入插件以及所有依赖项。
下载指定插件的所有依赖项可能需要一些时间,具体取决于列出的插件。
1.10.2.安装脱机插件包
要安装脱机插件包:
1.将压缩包移动到要安装插件的机器上。
2.运行bin/logstash-plugin install子命令,并传递脱机插件包的文件URI。
Windows example:
bin/logstash-plugin install file:///c:/path/to/logstash-offline-plugins-7.4.1.zip
Linux example:
bin/logstash-plugin install file:///path/to/logstash-offline-plugins-7.4.1.zip
此命令需要文件URI,因此请确保使用正斜杠并指定包的完整路径。
1.10.3.更新离线插件
要更新脱机插件,请在登台服务器上更新插件,然后使用与生成和安装插件包相同的过程:
- 在登台服务器上,运行bin/logstash-plugin update子命令来更新插件。 请参阅Updating plugins。
- 创建新版本的插件包。 请参阅Building Offline Plugin Packs。
- 安装新版本的插件包。 请参阅 Installing Offline Plugin Packs。
1.11.Private Gem Repositories
Logstash插件管理器连接到Ruby gems存储库以安装和更新Logstash插件。 默认情况下,此存储库为http://rubygems.org。
某些使用案例无法使用默认存储库,如以下示例所示:
- 防火墙阻止访问默认存储库。
- 您正在本地开发自己的插件。
- 本地系统上的气隙要求。
使用自定义gem储存库时,请确保使插件依赖项可用。
几个开源项目使您可以运行自己的插件服务器,其中包括:
1.11.1.编辑Gemfile
gemfile是一个配置文件,用于指定插件管理所需的信息。 每个gem文件都有一个源代码行,用于指定插件内容的位置。
默认情况下,gemfile的源代码行显示为:
# This is a Logstash generated Gemfile.
# If you modify this file manually all comments and formatting will be lost.
source "https://rubygems.org"
要更改源,请编辑源行以包含您的首选源,如以下示例所示:
# This is a Logstash generated Gemfile.
# If you modify this file manually all comments and formatting will be lost.
source "https://my.private.repository"
保存新版本的gemfile后,请正常使用插件管理命令。
以下链接包含有关设置一些常用存储库的更多材料:
- Geminabox
- Artifactory
- Running a rubygems mirror
1.12.Event API
本部分面向插件开发人员和Logstash的Ruby过滤器用户。 下面,我们记录了用户自定义插件和Ruby过滤器中访问Logstash基于事件的数据的方式(从5.0版开始)的最新更改。 请注意,访问Logstash的配置文件中的配置数据流中的事件数据和字段-“使用字段引用”-不受此更改的影响,并将继续使用现有语法。
1.12.1.Event Object
事件是将数据流内部封装在Logstash中的主要对象,并为插件开发人员提供了与事件内容进行交互的API。通常,此API用于插件和Ruby过滤器中,以检索数据并将其用于转换。事件对象包含发送给Logstash的原始数据以及在Logstash过滤阶段创建的任何其他字段。
在5.0中,我们已经在纯Java中重新实现了Event类及其支持类。由于事件是数据处理中的关键组件,因此Java重写可以提高性能,并在磁盘上存储数据时提供有效的序列化。在大多数情况下,此更改旨在保持向后兼容性,并且对用户透明。在此程度上,我们已经更新并发布了Logstash生态系统中的大多数插件,以适应新的API更改。但是,如果您要维护自定义插件或使用Ruby过滤器,则此更改将影响您。本指南的目的是描述新的API,并提供示例以移植到新的更改。
1.12.2.Event API
在5.0版之前,开发人员可以直接使用Ruby哈希语法访问和操作事件数据。 例如,event [field] = foo。 尽管功能强大,但我们的目标是抽象内部实现细节并提供定义良好的getter和setter API。
Get API
getter是对Event中基于字段的数据的只读访问。
Syntax: event.get(field)
Returns:此字段的值;如果该字段不存在,则为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]}
Accessing @metadata
event.get("[@metadata][foo]") # => "baz"
Set API
此API可用于更改事件中的数据。
Syntax: event.set(field, value)
Returns: 突变后的当前事件,可用于可链接调用。
例子:
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])
1.12.3.Ruby Filter
Ruby Filter可用于使用上述API执行任何红宝石代码并处理事件数据。 例如,使用新的API:
filter {
ruby {
code => 'event.set("lowercase_field", event.get("message").downcase)'
}
}
此过滤器将小写消息字段,并将其设置为名为lowercase_field的新字段