ElasticSearch--Jdbc导入插件

 

ElasticSearch--Jdbc导入插件

• 插件版本：v4.3.13
• 发布于：2018-09-04
• 更新日志

对于其他版本，请参阅 Versioned插件文档。

 

获取帮助

有关插件的问题，请在讨论论坛中打开一个主题。对于错误或功能请求，请在Github中打开一个问题。有关弹性支持插件的列表，请参阅弹性支持列表。

 

描述

创建此插件是为了使用JDBC接口将任何数据库中的数据提取到Logstash中。您可以使用cron语法（请参阅schedule设置）定期计划摄取，或者运行查询一次以将数据加载到Logstash中。结果集中的每一行都成为一个事件。结果集中的列将转换为事件中的字段。

 

驱动

此插件未与JDBC驱动程序库一起打包。必须使用jdbc_driver_library配置选项将所需的jdbc驱动程序库显式传入插件 。

 

调度

可以根据特定的时间表安排来自此插件的输入定期运行。此调度语法由rufus-scheduler提供支持。语法类似于cron，具有特定于Rufus的一些扩展（例如，时区支持）。

例子：

* 5 * 1-3 *	将于1月至3月的每一天每分钟执行一次。
0 * * * *	将在每天每小时的第0分钟执行。
0 6 * * * America/Chicago	将每天上午6:00（UTC / GMT -5）执行。

可在此处找到描述此语法的更多文档。

 

状态

该插件将以sql_last_value存储在已配置的元数据文件中的形式保留参数last_run_metadata_path。执行查询后，将使用当前值更新此文件sql_last_value。下次管道启动时，将通过读取文件来更新此值。如果 clean_run设置为true，则此值将被忽略并将sql_last_value设置为1970年1月1日，如果use_column_value为true，则为0 ，就好像之前没有执行任何查询一样。

 

处理大型结果集

许多JDBC驱动程序使用该fetch_size参数来限制从游标到客户端缓存中一次预取的结果数，然后从结果集中检索更多结果。这是使用jdbc_fetch_size配置选项在此插件中配置的。此插件默认情况下未设置提取大小，因此将使用特定驱动程序的默认大小。

 

用法：

以下是设置插件以从MySQL数据库获取数据的示例。首先，我们将适当的JDBC驱动程序库放在当前路径中（这可以放在文件系统的任何位置）。在这个例子中，我们使用user：mysql连接到mydb数据库，并希望在songs 表中输入与特定艺术家匹配的所有行。以下示例演示了可能的Logstash配置。此示例中的选项将指示插件每分钟执行此输入语句。schedule

input {
  jdbc {
    jdbc_driver_library => "mysql-connector-java-5.1.36-bin.jar"
    jdbc_driver_class => "com.mysql.jdbc.Driver"
    jdbc_connection_string => "jdbc:mysql://localhost:3306/mydb"
    jdbc_user => "mysql"
    parameters => { "favorite_artist" => "Beethoven" }
    schedule => "* * * * *"
    statement => "SELECT * from songs where artist = :favorite_artist"
  }
}

配置SQL语句

此输入需要sql语句。这可以通过字符串形式的语句选项传入，也可以从文件（statement_filepath）中读取。文件选项通常在SQL语句很大或在配置中提供时很麻烦时使用。file选项仅支持一个SQL语句。该插件只接受其中一个选项。它无法从文件以及statement配置参数中读取语句。

 

配置多个SQL语句

当需要查询和从不同数据库表或视图中提取数据时，配置多个SQL语句非常有用。可以为每个语句定义单独的Logstash配置文件，或在单个配置文件中定义多个语句。在单个Logstash配置文件中使用多个语句时，必须将每个语句定义为单独的jdbc输入（包括jdbc驱动程序，连接字符串和其他必需参数）。

请注意，如果任何语句使用该sql_last_value参数（例如，仅摄取自上次运行以来更改的数据），则每个输入应定义其自己的 last_run_metadata_path参数。如果不这样做将导致意外行为，因为所有输入都会将其状态存储到相同（默认）元数据文件中，从而有效地覆盖彼此sql_last_value。

 

预定义参数

某些参数是内置的，可以在查询中使用。这是清单：

sql_last_value

用于计算要查询的行的值。在运行任何查询之前，将其设置为1970年1月1日星期四，如果use_column_value为true tracking_column则设置为0 并设置为 0 。在后续查询运行后，它会相应更新。

例：

input {
  jdbc {
    statement => "SELECT id, mycolumn1, mycolumn2 FROM my_table WHERE id > :sql_last_value"
    use_column_value => true
    tracking_column => "id"
    # ... other configuration bits
  }
}

 

Jdbc输入配置选项

此插件支持以下配置选项以及稍后描述的Common Options。

Setting	Input type	Required
clean_run	boolean	No
columns_charset	hash	No
connection_retry_attempts	number	No
connection_retry_attempts_wait_time	number	No
jdbc_connection_string	string	Yes
jdbc_default_timezone	string	No
jdbc_driver_class	string	Yes
jdbc_driver_library	string	No
jdbc_fetch_size	number	No
jdbc_page_size	number	No
jdbc_paging_enabled	boolean	No
jdbc_password	password	No
jdbc_password_filepath	a valid filesystem path	No
jdbc_pool_timeout	number	No
jdbc_user	string	Yes
jdbc_validate_connection	boolean	No
jdbc_validation_timeout	number	No
last_run_metadata_path	string	No
lowercase_column_names	boolean	No
parameters	hash	No
record_last_run	boolean	No
schedule	string	No
sequel_opts	hash	No
sql_log_level	string, one of ["fatal", "error", "warn", "info", "debug"]	No
statement	string	No
statement_filepath	a valid filesystem path	No
tracking_column	string	No
tracking_column_type	string, one of ["numeric", "timestamp"]	No
use_column_value	boolean	No

 另请参阅“ 公共选项”以获取所有输入插件支持的选项列表。

clean_run

• 值类型是布尔值
• 默认值是 false

是否应保留先前的运行状态

columns_charset

• 值类型是哈希
• 默认值是 {}

特定列的字符编码。此选项将覆盖:charset指定列的选项。

例：

input {
  jdbc {
    ...
    columns_charset => { "column0" => "ISO-8859-1" }
    ...
  }
}

这只会将具有ISO-8859-1的column0转换为原始编码。

connection_retry_attempts

• 值类型是数字
• 默认值是 1

尝试连接数据库的最大次数

connection_retry_attempts_wait_time

• 值类型是数字
• 默认值是 0.5

连接尝试之间休眠的秒数

jdbc_connection_string

• 这是必需的设置。
• 值类型是字符串
• 此设置没有默认值。

JDBC连接字符串

jdbc_default_timezone

• 值类型是字符串
• 此设置没有默认值。

时区转换。SQL不允许时间戳字段中的时区数据。此插件将自动将SQL时间戳字段转换为Logstash时间戳，采用ISO8601格式的相对UTC时间。

使用此设置将手动分配指定的时区偏移量，而不是使用本地计算机的时区设置。例如，您必须使用规范时区，America / Denver。

jdbc_driver_class

• 这是必需的设置。
• 值类型是字符串
• 此设置没有默认值。

如果您使用的是Oracle JDBC，则可以通过https://github.com/logstash-plugins/logstash-input-jdbc/issues/43加载JDBC驱动程序类，例如“org.apache.derby.jdbc.ClientDriver”NB driver（ojdbc6.jar）正确的jdbc_driver_class是"Java::oracle.jdbc.driver.OracleDriver"

jdbc_driver_library

• 值类型是字符串
• 此设置没有默认值。

试图将JDBC逻辑抽象为mixin以便在其他插件中重用（输入/输出）当有人包含此模块时调用此方法将这些方法添加到给定的基础。JDBC驱动程序库到第三方驱动程序库的路径。如果需要多个库，您可以用逗号分隔它们。

如果没有提供，Plugin将在Logstash Java类路径中查找驱动程序类。

jdbc_fetch_size

• 值类型是数字
• 此设置没有默认值。

JDBC获取大小。如果没有提供，将使用相应的驱动程序默认值

jdbc_page_size

• 值类型是数字
• 默认值是 100000

JDBC页面大小

jdbc_paging_enabled

• 值类型是布尔值
• 默认值是 false

JDBC启用分页

这将导致sql语句被分解为多个查询。每个查询将使用限制和偏移来共同检索完整的结果集。限制大小设置为jdbc_page_size。

请注意，查询之间无法保证订购。

jdbc_password

• 值类型是密码
• 此设置没有默认值。

JDBC密码

jdbc_password_filepath

• 值类型是路径
• 此设置没有默认值。

JDBC密码文件名

jdbc_pool_timeout

• 值类型是数字
• 默认值是 5

连接池配置。在引发PoolTimeoutError之前等待获取连接的秒数（默认值为5）

jdbc_user

• 这是必需的设置。
• 值类型是字符串
• 此设置没有默认值。

JDBC用户

jdbc_validate_connection

• 值类型是布尔值
• 默认值是 false

连接池配置。使用前验证连接。

jdbc_validation_timeout

• 值类型是数字
• 默认值是 3600

连接池配置。验证连接的频率（以秒为单位）

last_run_metadata_path

• 值类型是字符串
• 默认值是 "$HOME/.logstash_jdbc_last_run"

上次运行时文件的路径

lowercase_column_names

• 值类型是布尔值
• 默认值是 true

是否强制标识符字段的小写

parameters

• 值类型是哈希
• 默认值是 {}

例如，查询参数的哈希值 { "target_id" => "321" }

record_last_run

• 值类型是布尔值
• 默认值是 true

是否保存状态 last_run_metadata_path

schedule

• 值类型是字符串
• 此设置没有默认值。

以Cron格式定期运行语句的时间表，例如：“* * * * *”（每分钟执行查询，分钟）

默认情况下没有计划。如果没有给出计划，则该语句只运行一次。

sequel_opts

• 值类型是哈希
• 默认值是 {}

一般/供应商特定的续集配置选项。

可选连接池配置示例max_connections - 连接池的最大连接数

特定于供应商的选项示例可在此文档页面中找到：https：//github.com/jeremyevans/sequel/blob/master/doc/opening_databases.rdoc

sql_log_level

• 值可以是任何的：fatal，error，warn，info，debug
• 默认值是 "info"

记录SQL查询的日志级别，可接受的值是常见的致命，错误，警告，信息和调试。默认值为info。

statement

• 值类型是字符串
• 此设置没有默认值。

如果未定义，Logstash会抱怨，即使编解码器未使用。要执行的声明

要使用参数，请使用命名参数语法。例如：

“SELECT * FROM MYTABLE WHERE id =：target_id”

这里，“：target_id”是一个命名参数。您可以使用该parameters设置配置命名参数。

statement_filepath

• 值类型是路径
• 此设置没有默认值。

包含要执行的语句的文件路径

tracking_column

• 值类型是字符串
• 此设置没有默认值。

如果use_column_value设置为，则要跟踪其值的列true

tracking_column_type

• 值可以是任何的：numeric，timestamp
• 默认值是 "numeric"

跟踪列的类型。目前只有“数字”和“时间戳”

use_column_value

• 值类型是布尔值
• 默认值是 false

设置为时true，使用定义的 tracking_column值作为:sql_last_value。设置为时false，:sql_last_value反映上次执行查询的时间。

 

常用选项

所有输入插件都支持以下配置选项：

设置	输入类型	需要
add_field	哈希	没有
codec	编解码器	没有
enable_metric	布尔	没有
id	字符串	没有
tags	排列	没有
type	字符串	没有

 

细节

add_field

• 值类型是哈希
• 默认值是 {}

向事件添加字段

codec

• 值类型是编解码器
• 默认值是 "plain"

用于输入数据的编解码器。输入编解码器是一种在数据进入输入之前解码数据的便捷方法，无需在Logstash管道中使用单独的过滤器。

enable_metric

• 值类型是布尔值
• 默认值是 true

默认情况下，禁用或启用此特定插件实例的度量标准记录我们会记录所有可用的度量标准，但您可以禁用特定插件的度量标准收集。

id

• 值类型是字符串
• 此设置没有默认值。

ID为插件配置添加唯一。如果未指定ID，则Logstash将生成一个ID。强烈建议在配置中设置此ID。当您有两个或更多相同类型的插件时，这尤其有用，例如，如果您有2个jdbc输入。在这种情况下添加命名ID将有助于在使用监视API时监视Logstash。

input {
  jdbc {
    id =>“my_plugin_id”
  }
}

tags

• 值类型是数组
• 此设置没有默认值。

为您的活动添加任意数量的任意标签。

这有助于以后处理。

type

• 值类型是字符串
• 此设置没有默认值。

将type字段添加到此输入处理的所有事件。

类型主要用于过滤器激活。

类型存储为事件本身的一部分，因此您也可以使用该类型在Kibana中搜索它。

如果您尝试在已有事件的事件上设置类型（例如，当您将事件从托运人发送到索引器时），则新输入将不会覆盖现有类型。托运人设置的类型即使在发送到另一个Logstash服务器时仍会保留该事件。

 

转载来源：https://www.elastic.co/guide/en/logstash/current/plugins-inputs-jdbc.html#plugins-inputs-jdbc