[Logstash] jdbc input plugin 4.3.19

 

• Plugin version: v4.3.19
• Released on: 2019-11-25

Description

이 플러그인은 JDBC 인터페이스가 있는 모든 데이터베이스에서 Logstash로 데이터를 수집하는 방법으로 만들어졌다. 크론 구문을 사용하여 주기적으로 수집을 예약하거나 쿼리를 한번 실행하여 데이터를 Logstash에 로드할 수 있다. 결과 집합의 각 행은 단일 이벤트가 된다. 결과 집합의 열은 이벤트에서 필드로 변환된다.

 

Drivers

이 플러그인은 JDBC 드라이버 라이브러리와 함께 제공되지 않는다. 원하는 jdbc 드라이버 라이브러리는 jdbc_driver_library 구성 옵션을 사용하여 플러그인에 명시적으로 전달해야 한다.

 

Scheduling

이 플러그인의 입력은 특정 일정에 따라 주기적으로 실행되도록 예약할 수 있다. 이 스케줄링 구문은 rufus-scheduler에 의해 작동된다. 구문은 Rufus(예: 표준 시간대 지원)에 특정된 일부 확장을 사용하는 크론(Cron)과 유사하다.

 

예시:

* 5 * 1-3 *	매일 오전 5시 마다 1월부터 3월까지 실행
0 * * * *	매일 매시 0분에 실행
0 6 * * * America/Chicago	매일 오전 6시(UTC/GMT -5)에 실행

이 구문을 설명하는 추가 문서는 이곳에서 찾을 수 있다.

 

State

플러그인은 설정된 last_run_metadata_path에 저장된 메타데이터 파일의 형태로 sql_last_value 파라미터를 유지한다. 쿼리 실행 시 이 파이른 현재 값은 sql_last_value로 업데이트 된다. 파이프라인이 시작된 다음, 이 값은 파일에서 읽음으로써 업데이트 될 것이다. clean_run을 true로 설정하면, 이 값은 무시 되고 sql_last_value가 1970년 1월 1일 또는 user_column_value가 true이면 쿼리가 실행 되지 않은 것처럼 0으로 설정 된다.

 

Dealing With Large Result-sets

많은 JDBC 드라이버는 fetch_size 파라미터를 사용하여 결과 집합에서 더 많은 결과를 검색하기전에 커서에서 한번에 클라이언트의 캐시로 사전 설정되는 결과 수를 제한한다. 이것은 jdbc_fetch_size 구성옵션을 사용하여 이 플러그인에서 구성된다. 이 플러그인에는 기본적으로 가져오기 크기가 설정되어 있지 않으므로 특정 드라이버의 기본 크기가 사용된다.

 

Usage

다음은 MySQL 데이터베이스에서 데이터를 가져오도록 플러그인은 설정하는 예제다. 우선 적절한 JDBC 드라이버 라이브러리를 현재 경로에 배치한다. (파일 시스템의 어느곳에나 배치할 수 있음) 이 예제에서는 MySQL 사용자를 사용하여 mydb 데이터베이스에 연결하고 특정 아티스트와 일치하는 곡 테이블의 모든 행을 입력하고자 한다. 다음 예는 이를 위해 가능한 Logstash 구성을 보여준다. 이 예제의 스케줄 옵션은 플러그인이 매 분마다 이 입력문을 실행하도록 지시한다.

 

 

Configuring SQL statement

이 입력에는 SQL 문구가 필요하다. 문자열 형식의 statement 옵션을 통해 전달하거나 파일(statement_filepath)에서 읽을 수 있다. 파일 옵션은 일반적으로 SQL문이 크거나 구성에 제공하기 번거로울 때 사용된다. 파일 옵션은 하나의 SQL문만 지원한다. 플러그인은 옵션 중 하나만 수락할 것이다. statement 구성 파라미터 뿐만 아니라 파일에서도 statement을 읽을 수 있다.

 

Configuring multiple SQL statement

여러개의 SQL 문을 구성하는 것은 다른 데이터베이스 테이블이나 뷰에서 데이터를 쿼리하고 수집해야 할 경우 유용하다. 각 statement에 대해 별도의 Logstash 구성 파일을 정의하거나 단일 구성 파일에 여러 개의 statement를 정의할 수 있다. 단일 Logstash 구성 파일에서 여러 개의 statement를 사용할 경우 각 statement은 별도의 jdbc 입력(jdbc driver, 연결 문자열 및 기타 필요한 파라미터 포함)으로 정의해야 한다.

 

statement에서 sql_last_value 파라미터를 사용하는 경우(예: 마지막 실행 이후 변경된 데이터만 수집) 각 입력은 last_run_metadata_path 파라미터를 정의애햐 한다. 그렇지 않으면 모든 입력이 동일한(기본) 메타데이터 파일에 상태를 저장하여 서로의 sql_last_value를 효과적으로 덮어쓰게 되므로 원치 않는 동작이 발생한다.

 

Predefined Parameters

일부 파라미터는 내장되어 있으며 쿼리 내에서 사용할 수 있다. 목록은 다음과 같다.

 

sql_last_value

쿼리할 행을 계산하는데 사용되는 값. 쿼리를 실행하기 전에, 이것은 1970년 1월 1일 목요일 또는 use_column_value가 true이고 tracking_column이 설정된 경우 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

   }

}

 

Prepared Statements

서버측에서 prepared statement를 사용하면 서버가 쿼리 계획 및 실행을 최적화할 때 실행 시간이 단축될 수 있다.

 

모든 JDBC 엑세스 가능 기술이 prepared statement를 지원하지는 않는다.

 

Prepared Statement의 도입으로 다른 코드 실행 경로와 몇가지 새로운 설정이 제공된다. 기존 설정의 대부분은 여전히 유용하지만 Prepared Statement에 대해 읽을 수 있는 몇가지 새로운 설정이 있다. 이 실행 모드를 활성화하려면 부울 설정 use_prepared_statements를 사용해야 한다. prepared_statement_name 설정을 사용하여 Prepared Statement의 이름을 지정하고, 이것은 로컬 및 원격으로 prepared statement를 식별하며, 구성과 데이터베이스에서 고유해야 한다. prepared_statement_bind_values 배열 설정을 사용하여 바인딩 값을 지정하고, 앞에서 언급한 사전정의된 파라미터에 대해 정확한 문자열 :sql_last_value(필요한 경우 여러번)을 사용해야 한다. statement(또는 statement_path) 설정은 여전히 SQL문을 보관하지만 바인딩 변수를 사용하려면 prepared_statement_bind_values 배열에서 찾은 정확한 순서로 '?' 문자를 자리 표시자로 사용해야 한다.

 

현재 prepared statement를 중심으로 한 개수 조회는 지원되지 않으며, jdbc 페이징은 후드 아래에서 개수 조회를 사용하기 때문에, 현재 jdbc 페이징도 prepared statements는 지원되지 않는다. 따라서 jdbc_paging_enabled, jdbc_page_size 설정은 prepared statements를 사용할 때 무시된다.

 

예시:

input {

   jdbc {

      statement => "SELECT * FROM mgd.seq_sequence WHERE _sequence_key > ? AND _sequence_key < ? + ? ORDER BY _sequence_key ASC"

      prepared_statement_bind_values => [":sql_last_value", ":sql_last_value", 4]

      prepared_statement_name => "foobar"

      use_prepared_statements => true

      use_column_value => true

      tracking_column_type => "numeric"

      tracking_column => "_sequence_key"

      last_run_metadata_path => "/elastic/tmp/testing/confs/test-jdbc-int-sql_last_value.yml"

      # ... other configuration bits

   }

}