说明文档:https://github.com/logstash-plugins/logstash-input-jdbc/blob/master/docs/index.asciidoc
插件简述
- 这个插件被创造出来,是为了实现从任何JDBC数据库中吸收数据并同步至Logstash中。
- 两种使用方式:
- 全量导入:一次性全部导入。
- 增量导入:通过特定的调度算法进行周期性的增量导入。
显式加载驱动
本插件并没有包含jdbc的驱动类,所以需要通过jdbc_driver_library
显式地传递给插件。
调度规则
插件的输入内容,可以根据特定的调度规则,进行周期性的执行。
调度规则基于
rufus-scheduler
,是rufus-scheduler
的扩展。语法:
* * * * *
minute—hour—day—month—timeZone
举例说明:
序号 | 调度规则 | 调度说明 |
---|---|---|
1 |
| 将于,1月至3月,每天,上午5点,每分钟执行 |
2 | 0 * * * * | 将于,每天,每小时,第0分钟执行 |
3 | 0 6 * * * America/Chicago | 将于, UTC/GMT -5时区,每天,上午6点,第0分钟执行 |
Sql运行状态
sql_last_value
参数表示上次的SQL执行到了哪里。- 插件会在
last_run_metadata_path
参数所指示的元数据文件中,持久化sql_last_value
参数。 - 一旦查询执行,元数据文件就会更新
sql_last_value
参数。 - 如果
clean_run
参数被设置成true,则sql_last_value
参数将被设置成Jan 1, 1970
,并且被忽略。 - 如果
use_column_value
参数被设置成true,则sql_last_value
参数将被设置成0
,就行从未发生过查询。
处理大型结果集
- 许多JDBC驱动程序使用
fetch_size
参数来限制在从结果集检索更多结果之前,一次提取多少结果放在客户端缓存中。 - 提取大小在本插件中通过
jdbc_fetch_size
参数来配置。 - 默认情况下,本插件中没有设置提取大小,这种情况下,将使用特定的驱动程序的大小进行配置。
示例
下面是一个从MySql数据库提取数据的示例。
首先,我们需要将JDBC驱动放置在合适的目录下。
下面,分布对每行配置进行注释说明:
input { # 一个JDBC配置,可以配置多个 jdbc { # 驱动路径 jdbc_driver_library => "mysql-connector-java-5.1.36-bin.jar" # 驱动类路径 jdbc_driver_class => "com.mysql.jdbc.Driver" # 数据库URL jdbc_connection_string => "jdbc:mysql://localhost:3306/mydb" # 用户名 jdbc_user => "mysql" # 参数配置,可以多个 parameters => { "favorite_artist" => "Beethoven" } # 调度规则:每分钟执行一次 schedule => "* * * * *" # 从songs表中查询artist=Beethoven的记录 statement => "SELECT * from songs where artist = :favorite_artist" } }
配置SQL语句
- 输入需要配置SQL语句。
- SQL语句有两种配置方式:
- 在jdbc配置块中,在
statement
参数处,直接以字符串的形式进行配置。 - 在jdbc配重块中,以
statement_filepath
参数配置SQL语句文件,然后在SQL文件中编写SQL语句。
- 在jdbc配置块中,在
- 关于两种SQL语句配置方式:
- 两种方式是互斥的,只能二选其一。
- SQL文件的配置方式一般针对SQL繁琐复杂的情况下。
- SQL文件的配置方式也只能配置一条SQL语句。
配置多个SQL语句
- 当需要从不同的数据库、表、视图中提取数据时,配置多个SQL语句时非常有必要的。
- 可以为每个语句定义单独的Logstash配置文件,或者在单个配置文件中定义多个语句。
- 当在单个Logstash配置文件中使用多个语句时,必须将每个语句定义为单独的JDBC输入(包括JDBC驱动程序、连接字符串和其他所需参数)。
- 请注意,如果任何语句使用了
sql_last_value
参数(例如,只摄取自上次运行以来更改的数据),则每个输入应该定义自己的last_run_metadata_path
路径参数。不这么做会产生不可预期的结果,因为多个输入使用同一个sql_last_value
参数,他们会彼此覆盖。
预定义参数
一些参数是内置的,可以在查询中使用。
-
序号 内置参数 说明 1 sql_last_value -
用于计算应该查询哪一行记录。
- 在后续查询运行之后,它会相应地更新。
- 默认情况下,查询之前,这个值会被置为Jan 1, 1970
- 如果use_column_value => true
,在查询之前,这个值置为0
示例
input { jdbc { # 通过id > :sql_last_value去判断上次执行到了哪里 statement => "SELECT id, mycolumn1, mycolumn2 FROM my_table WHERE id > :sql_last_value" # 使用列值进行查询记录追踪 use_column_value => true # 设置跟踪记录的列为:id tracking_column => "id" # ... other configuration bits } }
-
用于计算应该查询哪一行记录。
JDBC的输入配置参数
jdbc_connection_string
- 必须配置
- 类型:string
- 无default
- 说明:JDBC连接URL。
jdbc_driver_library
- 类型:string
- 无default
- 说明:JDBC驱动程序库路径到第三方驱动程序库。在需要多个库的情况下,可以通过逗号分隔它们。
- 示例:
"mysql-connector-java-5.1.36-bin.jar"
- 如果没有提供,插件将在Logstash Java类路径中寻找驱动程序类。
jdbc_driver_class
- 类型:string
- 无default
- 说明:JDBC驱动类的类路径
- Oracle:
"Java::oracle.jdbc.driver.OracleDriver"
- Mysql:
"com.mysql.jdbc.Driver"
- Oracle:
jdbc_user
- 必须配置。
- 类型:string
- 无default
- 说明:jdbc密码
jdbc_password
- 类型:password
- 无default
- 说明:jdbc密码
jdbc_password_filepath
- 类型:path
- 无default
- 说明:jdbc密码文件
schedule
- 类型:string
- 无default
- 说明:调度规则,或者说什么时候去运行SQL语句。
- 规则:
[minute] [hour] [day] [month] [timeZone]
,如:* * * * *
表示每分钟执行一次。 - 默认情况下,没有调度规则,这种情况下,只运行一次。
parameters
- 类型:hash
- default =
{}
- 说明:查询参数的散列表,例如:
{ "target_id" ⇒ "321" }
。
statement
- 类型:string
- 无default
- 说明:需要执行的SQL语句。
- 可以使用参数,语法为:
:parameter_name
,示例:
"SELECT * FROM MYTABLE WHERE id = :target_id"
- 通过
parameters
配置项对参数列表进行配置。
statement_filepath
- 类型:path
- 无default
- 说明:SQL语句文件路径。
use_column_value
- 类型:boolean
- default =
false
- 说明:是否使用列值作为依据,进行上次运行位置的记录。
- 如果设置为true,则使用
tracking_column
定义的列,作为:sql_last_value
. - 如果设置为false,则
:sql_last_value
反映的是上次SQL的运行时间。
tracking_column
- 类型:string
- 无default
- 说明:将哪一列作为
:sql_last_value
,进行sql执行情况的跟踪。 - 此值的生效前提是:
use_column_value = true
。
tracking_column_type
- 类型:
numeric
,timestamp
- default =
"numeric"
- 说明:跟踪列的类型。
last_run_metadata_path
- 类型:string
- default =
"/home/ph/.logstash_jdbc_last_run"
- 说明:具有上次运行状态的元数据文件路径。
clean_run
- 类型:boolean
- default = false
- 说明:前一个运行状态是否应该保留
columns_charset
类型:hash
default = {}
说明:特定列的字符编码,此选项将重写指定列的“字符集”选项。
示例:
input { jdbc { ... columns_charset => { "column0" => "ISO-8859-1" } ... } }
connection_retry_attempts
- 类型:number
- default = 1
- 说明:重试连接到数据库的次数。
connection_retry_attempts_wait_time
- 类型:number
- default = 0.5
- 说明:两次重试连接之间的休眠时间。
jdbc_pool_timeout
- 类型:number
- default = 5
- 连接池配置:在引发池PoolTimeoutError 之前等待获取连接的秒数(默认值5)
jdbc_validate_connection
- 类型:boolean
- default = false
- 连接池配置:在使用之前进行连接验证。
jdbc_validation_timeout
- 类型:number
- default = 3600
- 连接池配置:多久进一次连接验证(单位:秒)。
lowercase_column_names
- 类型:boolean
- default =
true
- 说明:是否对标识符字段进行强制小写转换。
sql_log_level
- 类型:
fatal
,error
,warn
,info
,debug
- default =
"info"
- 说明:SQL执行时打印日志的等级。
sequel_opts
- 类型:hash
- default =
{}
- 说明:配置选项映射,如
max_connections
等
record_last_run
- 类型:boolean
- default =
true
- 说明:在
last_run_metadata_path
配置的元数据文件中,是否记录上次运行记录。
jdbc_default_timezone
- 类型:string
- 无default。
- 类型:默认的时区。
- SQL不允许时间戳字段中的时区数据。
- 该插件将自动转换SQL时间戳字段到Logstash时间戳,以ISO8601标准的UTC时间进行转换。
- 配置将手动分配指定的时区偏移量,而不是使用本地机器的时区设置。
- 必须使用规范时区,如:
America/Denver
。
jdbc_fetch_size
- 类型:number
- default :100000
- 说明:JDBC一次提取大小
jdbc_paging_enabled
- 类型:boolean
- default = false
- 说明:开启分页
- 这将导致SQL语句被分解成多个查询。
- 每个查询将使用限制和偏移来共同检索完整的结果集。
- 分页大小用
jdbc_page_size
来设置。 - 请注意,查询之间不能保证排序。