Jdbc_streaming 过滤器插件
编辑Jdbc_streaming 过滤器插件编辑
有关其他版本,请参阅 版本化插件文档。
获取帮助编辑
如果您对该插件有任何疑问,请在 Discuss 论坛中开启一个主题。如有错误或功能请求,请在 Github 中开启一个问题。有关 Elastic 支持的插件列表,请参阅 Elastic 支持矩阵。
描述编辑
此过滤器执行 SQL 查询并将结果集存储在指定为 target
的字段中。它将使用 LRU 缓存将结果缓存在本地,并设置过期时间。
例如,您可以根据事件中的 ID 加载一行。
filter { jdbc_streaming { jdbc_driver_library => "/path/to/mysql-connector-java-5.1.34-bin.jar" jdbc_driver_class => "com.mysql.jdbc.Driver" jdbc_connection_string => "jdbc:mysql://127.0.0.1:3306/mydatabase" jdbc_user => "me" jdbc_password => "secret" statement => "select * from WORLD.COUNTRY WHERE Code = :code" parameters => { "code" => "country_code"} target => "country_details" } }
预处理语句编辑
使用服务器端预处理语句可以加快执行时间,因为服务器会优化查询计划和执行。
并非所有可通过 JDBC 访问的技术都支持预处理语句。
随着预处理语句支持的引入,代码执行路径和一些新设置也随之而来。大多数现有设置仍然有用,但也有一些新的预处理语句设置需要阅读。
使用布尔设置 use_prepared_statements
启用此执行模式。
使用 prepared_statement_name
设置指定预处理语句的名称,这将在本地和远程标识预处理语句,并且在您的配置和数据库中应该是唯一的。
使用 prepared_statement_bind_values
数组设置指定绑定值。通常,这些值是从您的事件中间接提取的,即数组中的字符串指的是事件中的字段名称。您也可以使用常量值,如数字或字符串,但要确保任何字符串常量(例如,区域设置常量“en”或“de”)也不是事件字段名称。最好对字段使用括号字段引用语法,对常量使用普通字符串,例如 prepared_statement_bind_values => ["[src_ip]", "tokyo"]
。
有 3 种可能的参数方案。插值、字段引用和常量。当您对字段值进行前缀、后缀或连接以创建数据库中存在的值时,请使用插值,例如“%{username}@%{domain}”→“[email protected]”、“%{distance}km”→“42km”。对于精确的字段值,请使用字段引用,例如“[srcip]”→“192.168.1.2”。当数据库列包含对多个类似记录进行切片或分类的值时,请使用常量,例如语言翻译。
布尔设置 prepared_statement_warn_on_constant_usage
默认为 true,用于控制是否记录 WARN 消息,该消息会在检测到常量可能缺少括号字段引用语法时发出警告。如果您已正确设置字段引用和常量,则应将 prepared_statement_warn_on_constant_usage
设置为 false。此设置和代码检查应在未来的 Logstash 主要版本中弃用。
statement
(或 statement_path
)设置仍然保存 SQL 语句,但要使用绑定变量,您必须使用 ?
字符作为占位符,其顺序与 prepared_statement_bind_values
数组中的顺序完全一致。某些技术可能需要设置连接字符串属性,请参阅下面的 MySQL 示例。
示例
filter { jdbc_streaming { jdbc_driver_library => "/path/to/mysql-connector-java-5.1.34-bin.jar" jdbc_driver_class => "com.mysql.jdbc.Driver" jdbc_connection_string => "jdbc:mysql://127.0.0.1:3306/mydatabase?cachePrepStmts=true&prepStmtCacheSize=250&prepStmtCacheSqlLimit=2048&useServerPrepStmts=true" jdbc_user => "me" jdbc_password => "secret" statement => "select * from WORLD.COUNTRY WHERE Code = ?" use_prepared_statements => true prepared_statement_name => "lookup_country_info" prepared_statement_bind_values => ["[country_code]"] target => "country_details" } }
Jdbc_streaming 过滤器配置选项编辑
此插件支持以下配置选项以及稍后描述的 通用选项。
设置 | 输入类型 | 必需 |
---|---|---|
否 |
||
否 |
||
否 |
||
是 |
||
是 |
||
有效的 文件系统路径 |
否 |
|
否 |
||
否 |
||
否 |
||
否 |
||
否 |
||
否 |
||
否 |
||
否 |
||
否 |
||
是 |
||
否 |
||
否 |
||
是 |
||
否 |
||
否 |
另请参阅 通用选项,了解所有过滤器插件支持的选项列表。
cache_expiration
编辑
- 值类型为 数字
- 默认值为
5.0
任何条目在缓存中应保留的最短秒数。默认为 5 秒。
一个数值。您可以使用小数,例如:cache_expiration => 0.25
。如果存在瞬态 jdbc 错误,缓存将为给定的参数集存储空结果并绕过 jbdc 查找。这会将 default_hash 合并到事件中,直到缓存条目过期。然后,将再次尝试对相同的参数进行 jdbc 查找。相反,当缓存包含有效结果时,在 cache_expiration 时间段内,将不会注意到任何会导致 jdbc 错误的外部问题。
jdbc_driver_class
编辑
- 这是一个必需设置。
- 值类型为 字符串
- 此设置没有默认值。
要加载的 JDBC 驱动程序类,例如“oracle.jdbc.OracleDriver”或“org.apache.derby.jdbc.ClientDriver”
prepared_statement_bind_values
编辑
- 值类型为 数组
- 默认值为
[]
预处理语句的绑定值数组。使用字段引用和常量。有关更多信息,请参阅 prepared_statements 部分。
prepared_statement_name
编辑
- 值类型为 字符串
- 默认值为
""
赋予预处理语句的名称。它在您的配置和数据库中必须是唯一的。如果 use_prepared_statements
为 true,则需要提供此项。
prepared_statement_warn_on_constant_usage
编辑
- 值类型为 布尔值
- 默认值为
true
一个标志,用于控制如果在 prepared_statement_bind_values
中检测到可能打算用作字段引用的字符串常量时是否记录警告。
sequel_opts
编辑
- 值类型为 哈希
- 默认值为
{}
通用/特定于供应商的 Sequel 配置选项
可选连接池配置的示例 max_connections - 连接池的最大连接数
特定于供应商的选项示例可以在此文档页面中找到:https://github.com/jeremyevans/sequel/blob/master/doc/opening_databases.rdoc
通用选项编辑
以下配置选项受所有过滤器插件支持
设置 | 输入类型 | 必需 |
---|---|---|
否 |
||
否 |
||
否 |
||
否 |
||
否 |
||
否 |
||
否 |
add_field
编辑
- 值类型为 哈希
- 默认值为
{}
如果此过滤器成功,则向此事件添加任意字段。字段名称可以是动态的,并且可以使用 %{field}
包含事件的一部分。
示例
filter { jdbc_streaming { add_field => { "foo_%{somefield}" => "Hello world, from %{host}" } } }
# You can also add multiple fields at once: filter { jdbc_streaming { add_field => { "foo_%{somefield}" => "Hello world, from %{host}" "new_field" => "new_static_value" } } }
如果事件具有字段 "somefield" == "hello"
,则此过滤器在成功时将添加字段 foo_hello
(如果存在),其值为上述值,并将 %{host}
部分替换为事件中的该值。第二个示例还将添加一个硬编码字段。
add_tag
编辑
- 值类型为 数组
- 默认值为
[]
如果此过滤器成功,则向事件添加任意标签。标签可以是动态的,并且可以使用 %{field}
语法包含事件的一部分。
示例
filter { jdbc_streaming { add_tag => [ "foo_%{somefield}" ] } }
# You can also add multiple tags at once: filter { jdbc_streaming { add_tag => [ "foo_%{somefield}", "taggedy_tag"] } }
如果事件具有字段 "somefield" == "hello"
,则此过滤器在成功时将添加标签 foo_hello
(当然,第二个示例将添加 taggedy_tag
标签)。
id
编辑
- 值类型为 字符串
- 此设置没有默认值。
向插件配置添加唯一的 ID
。如果未指定 ID,Logstash 将生成一个。强烈建议在配置中设置此 ID。当您有两个或多个相同类型的插件时,例如,如果您有 2 个 jdbc_streaming 过滤器,这将特别有用。在这种情况下,添加命名 ID 将有助于在使用监控 API 时监控 Logstash。
filter { jdbc_streaming { id => "ABC" } }
id
字段中的变量替换仅支持环境变量,不支持使用密钥库中的值。
remove_field
编辑
- 值类型为 数组
- 默认值为
[]
如果此过滤器成功,则从此事件中删除任意字段。字段名称可以是动态的,并且可以使用 %{field} 示例包含事件的一部分
filter { jdbc_streaming { remove_field => [ "foo_%{somefield}" ] } }
# You can also remove multiple fields at once: filter { jdbc_streaming { remove_field => [ "foo_%{somefield}", "my_extraneous_field" ] } }
如果事件具有字段 "somefield" == "hello"
,则此过滤器在成功时将删除名为 foo_hello
的字段(如果存在)。第二个示例将删除一个额外的非动态字段。
remove_tag
编辑
- 值类型为 数组
- 默认值为
[]
如果此过滤器成功,则从事件中删除任意标签。标签可以是动态的,并且可以使用 %{field}
语法包含事件的一部分。
示例
filter { jdbc_streaming { remove_tag => [ "foo_%{somefield}" ] } }
# You can also remove multiple tags at once: filter { jdbc_streaming { remove_tag => [ "foo_%{somefield}", "sad_unwanted_tag"] } }
如果事件具有字段 "somefield" == "hello"
,则此过滤器在成功时将删除标签 foo_hello
(如果存在)。第二个示例还将删除一个不需要的标签。