박철우의 블로그

subscribeOn, observeOn 이 두 가지의 차이에 대해 비교해 놓은 글이 상당히 많다. 

그냥 아래 다섯 가지만 기억하자.

1. observeOn 은 다운스트림에만 영향을 준다.

2. subscribeOn 은 업스트립, 다운스트림 양쪽에 영향을 준다.

3. 한 Observable에 대한 두 번 이상의 subscribeOn 호출은 첫 번째 호출만 유효하다.

4. 한 Observable에 대한 observeOn 호출은 몇 번이고 유효하다.

5. observeOn으로 변경된 쓰레드는 subscribeOn으로 변경할 수 없다.

출처:

https://proandroiddev.com/rx-java-subscribeon-and-observeon-a7d95041ce96

JUnit 5 는 JDK 8+ 을 요구한다. 

때문에 org.junit.jupiter.api.Assertions.. 를 사용하면 오류가 발생한다. (내부에서 Function 시리즈를 사용함.)

JUnit api 는 JUnit 4 이하의 org.junit.Assert... 를 사용해야 한다.

그리고 JUnit 5 에서, 이전 버전과의 런타임 호환성을 위한 vintage 를 의존성에 추가한다:

	testImplementation 'org.junit.jupiter:junit-jupiter-api:5.5.0'
	testImplementation 'org.junit.jupiter:junit-jupiter-api:5.5.0'
	testImplementation "junit:junit:4.12"
	testRuntimeOnly 'org.junit.vintage:junit-vintage-engine:5.5.0'
	testRuntimeOnly 'org.junit.jupiter:junit-jupiter-engine:5.5.0'

5.6.0 이상을 사용하니 아래와 같은 오류가 발생했다. 고쳐서 사용할 수 있는 방법이 있을 수 있으나, 일단 5.5.0 을 사용하기로 한다.

* What went wrong: 
Execution failed for task ':compileTestJava'. 
> Could not resolve all files for configuration ':testCompileClasspath'. 
   > Could not resolve org.junit.jupiter:junit-jupiter-api:5.6.0. 
     Required by: 
         project : 
      > Cannot choose between the following variants of org.junit.jupiter:junit-jupiter-api:5.6.0: 
          - javadocElements 
          - sourcesElements 
        All of them match the consumer attributes: 
          - Variant 'javadocElements' capability org.junit.jupiter:junit-jupiter-api:5.6.0: 
              - Unmatched attributes: 
                  - Found org.gradle.category 'documentation' but wasn't required. 

iif(condition: () => boolean, trueResult: SubscribebaleOrPromise = EMPTY, falseResult: SubscribableOrPromise = EMPTY): Observable

첫 번째 인자로 주어진 predicate fucntion을 실행하여, true일 경우 두 번째 인자가 반환하는 Subscribable 또는 Promise를, false일 경우 세 번째 인자가 반환하는 Subscribable 또는 Promise를 구독한다.

iff 사용 시 주의할 점이 있다.

아래 코드를 실행한다고 하면,

...
const source = of('Some value');
const whenTrue => (v) => {console.log('Do you expect it to be executed only if true?') return of('true!')};
const whenFalse => (v) => {console.log('Do you expect it to be executed only if false?') return of('false!')};

source.pipe(
	mergeMap(v => 
    	iif(_ => v === 'Some value',
			whenTrue(v),
			whenFalse(v)
        ))
).subscribe(console.log);

source의 값은 'Some value' 이기에, 콘솔에는 다음과 같이 찍힐 거라고 생각할 수 있다:

Do you expect it to be executed only if true?
true!

실행 결과는 다음과 같다:

Do you expect it to be executed only if true?
Do you expect it to be executed only if false?
true!

whenTrue, whenFalse는 iff의 실행 시점에 인자 evaluation시에 실행되고, predicate function의 결과가 true이니 'true!'를 출력했다.

아주 당연한 결과이지만, iif 를 분기 동작에 사용하려고 할 때 쉽게 실수할 수 있는 부분인 것 같아 굳이 정리해둔다.

Thymeleaf 를 사용하면 meta, link 태그 등의 닫기 태그가 없어 SAX 파싱 예외가 발생하는 경우가 있다. 일반적인 html에서는 저런 태그를 닫아주지 않아도 이런 경우가 없는데, 정확히 어느 버전까지인지는 모르겠지만, 예전 버전의 Thymeleaf lib 사용 시 xhtml의 엄격한 룰이 적용되어 이와 같은 현상이 발생한다고 한다.

이를 피하기 위해서는,

1. application.properties 에 다음 프로퍼티를 설정한다:

spring.thymeleaf.mode=LEGACYHTML5

2. nekohtml 의존성을 추가한다:

net.sourceforge.nekohtml:nekohtml

ps: nekohtml은 버전 1.9.15 이상을 사용하라는 권고가 있음.

select

- 전통적인 방식으로, 대부분의 os가 지원.

- 프로세스가 커널에 파일 디스크립터(이하 FD) 상태를 직접 조회.

- 한 번에 다수의 FD를 조회하여 I/O 상태를 관찰.

- 때문에 무한 루프 방식으로 지속된 polling 필요 (CPU 낭비).

- 한 번에 조회할 수 있는 FD의 수는 1024로 제한됨.

- timeout 사용 방식에 따라 blocking이 될 수도, non-blocking이 될 수도 있음.

poll

- 기본적인 작동 방식은 select와 유사함.

- 조회 FD의 개수 제한이 없음.

- select에 비해 os specific하여, 이식성이 상대적으로 나쁨.

epoll

- 개선된 poll으로, 이벤트 기반으로 작동.

- 관리 FD 개수 무제한.

- 커널이 FD의 상태를 직접 관리하며, 상태가 변경된 FD를 던져줌.

- 때문에 커널로의 통신에 따른 오버헤드가 대폭 줄어듦.

IOCP (Input/Output Completion Port / Overlapped IO)

- 입출력을 담당할 포트를 지정하여 처리.

- 내부에 큐를 두어, 입출력이 완료되었음을 큐에 저장.

- non-blocking. 백그라운드로 작동.

- async 방식으로, 콜백 사용 가능.

IO

- NIO가 나오면서 자바의 기존 IO 방식은 OIO(Old I/O)라고도 불림.

- *InputStream, *OutputStream, *Reader, *Writer...

- 전통적인 blocking call 방식.

- 때문에 FD(소켓, 파일...) 당 하나의 쓰레드가 필요함.

- 때문에, 동시 요청이 자주 발생하는 어플리케이션의 경우 필연적으로 쓰레드 풀을 사용하게 됨.

NIO

- New I/O 로, 자바 1.4에서 등장.

- 주요 요소: Buffer, Charset, Channel, Selector.

- Buffer: NIO의 데이터 저장 컨테이너로, 다이렉트 버퍼, 논 다이렉트 버퍼(힙 버퍼)로 나뉨. 다이렉트 버퍼는 네이티브 메모리를 사용하고, 논 다이렉트 버퍼는 JVM의 힙 메모리를 사용함.

- Channel: 데이터가 오고 가는 양방향 통로.

- Selector: non-blocking, 이벤트 방식으로, 지정한 채널에 발생한 이벤트를 수신하여 이벤트 유형에 맞는 동작을 처리할 수 있음. 

- 결정적으로, OIO에서는 다수의 요청을 받아들이기 위해 많은 수의 쓰레드를 필요로 했지만, NIO에서는 Selector를 조회하는 하나의 쓰레드만으로 다수의 요청을 커버할 수 있음. 물론 요청의 성격에 따라 별도의 처리 쓰레드가 필요할 수 는 있다.

- 자바 6 부터는 epoll을 지원하여, 런타임 os가 리눅스 커널 2.6 이상이라면 epoll을 디폴트로 한다. poll을 사용하려면 아래와 같이 시스템 프로퍼티로 제어 가능함.

System.setProperty("java.nio.channels.spi.SelectorProvider", "sun.nio.ch.PollSelectorProvider");

- 이렇게, NIO는 os specific하다. os의 기능을 차용하여, 아래와 같이 런타임 os에 따라 동작을 달리한다.

Windows: select

Mac OS: Kqueue

리눅스 커널 2.6+: epoll

솔라리스: poll

NIO2

- 그냥 NIO로 통틀어 말하기도 함. 자바 1.7에서 등장. 네트워킹 I/O에는 마이너한, 파일 I/O에는 메이저한 변화가 있었음.

- Async* 시리즈의 등장으로, 비동기 콜백 방식의 I/O를 지원함.

7.6.0 릴리즈 버전 기준으로 작성됨

==

Filebeat는 lumberjack 프로토콜(over TCP)을 통해 Logstash(이하 로그스태시)로 다이렉트로 이벤트 전송이 가능하다.

로그스태시를 아웃풋으로 두려면 엘라스틱서치 아웃풋은 사용하지 않아야 한다. 그리고 아래와 같이 로그스태시 url을 설정한다.

output.logstash:
  hosts: ["127.0.0.1:5044"]

이 설정을 위해서는 반드시 엘라스틱서치 인덱스 템플릿을 로드해야 한다. 인덱스 템플릿을 자동으로 불러오는 옵션은 엘라스틱서치 아웃풋일 때만 작동한다.

옵션

아래 옵션들은 filebeat.yml 의 logstash 섹션에 지정한다.

enabled (디폴트: true)

이 아웃풋을 활성화하는지 지정한다. 아웃풋을 사용하지 않으려면 false로 세팅한다.

hosts

Filebeat가 연결할 로그스태시 서버 주소를 설정한다. 로드밸런싱 적용 시 둘 이상의 호스트를 설정한다. 디폴트 포트는 5044가 된다.

compression_level (디폴트: 3, 사용안함: 0)

gzip 압축 레벨을 설정한다. 압축을 사용하지 않으려면 0 을 세팅한다. 세팅 범위는 1~9이다. 값이 낮을수록 압축률은 떨어지고 속도는 올라간다. 높을수록 네트워크 사용량을 줄어들지만 cpu 사용률이 올라간다.

escape_html (디폴트: false)

HTML 문자열 이스케이핑 설정. true로 세팅하면 이스케이핑을 활성화한다.

worker

logstash로 이벤트를 전송하는 워커의 수를 설정한다. 설정되는 수는 host 당 워커의 수이다. 2개의 호스트를 설정하고 worker 값이 3이라면 총 워커의 수는 6이 된다.

loadbalance (디폴트: false)

다수의 호스트를 설정하고 이 옵션을 true로 세팅하면 로드밸런싱을 활성화한다. 어떤 호스트로 이벤트를 전송할지는 랜덤으로 결정되며, 우선순위는 없다. 다수의 호스트를 설정하더라도 이 옵션값이 false이면 로드밸런싱은 적용되지 않고, 설정된 호스트 중 오직 한 호스트로만 모든 이벤트를 전송한다 (이 때의 대상 호스트도 랜덤으로 결정). 그리고 그 호스트의 응답이 없을 경우 다른 호스트로 전송을 시도한다.

예:

output.logstash:
  hosts: ["localhost:5044", "localhost:5045"]
  loalbalance: true
  index: filebeat

호스트로의 로드밸런싱은 커넥션 레벨에서 이루어진다. 이벤트 레벨이 아니다. 이벤트는 한 번 맺어진 커넥션으로만 고정적으로 전송되며, 로드밸런싱은 로그스태시로의 기존 커넥션이 끊어지고 커넥션을 다시 맺을 때 어떤 호스트로 커넥션을 맺을지 결정하는 과정에 적용된다.

ttl (디폴트: 0 (사용안함))

로그스태시 호스트로의 커넥션 유지 시간을 설정한다. 로드밸런싱을 적용할 때 유용하다. 로그스태시로의 커넥션은 sticky하기 때문에, 로드밸런싱의 목적인 커넥션의 분산이 고르지 못하게 이루어질 수 있다. 이 옵션을 설정함으로써 일정 시간 후 커넥션을 끊었다가 다시 맺도록 하여, 커넥션이 고루 분산되도록 할 수 있다.

이 옵션은 async 로그스태시 클라이언트에는 아직 지원되지 않는다 ("pipelining" 옵션).

pipelining (디폴트: 2, 사용안함: 0)

로그스태시로부터의 ACK를 기다리는 동안 비동기로 전송할 이벤트 묶음(batch)의 수를 설정한다. 아웃풋은 많은 수의 pipelining 묶음이 한 번 작성될 때 블로킹된다.

proxy_url

로그스태시로 연결 시 SOCKS5 프록시를 사용할 URL을 설정한다. 설정 URL은 반드시 socks5:// 스킴을 포함해야 한다. 로그스태시로의 연결은 HTTP 기반이 아니기 때문에, web-proxy는 사용할 수 없다.

SOCKS5 프록시가 클라리언트 인증을 요구하는 경우, username, password는 아래와 같이 URL에 포함시킬 수 있다.

프로시를 사용할 때는 호스트 이름은 클라이언트가 아닌, 프록시 서버로 리졸빙되어야 한다. 이 설정은 proxy_use_local_resolver 옵션으로 설정한다.

예:

output.logstash:
  hosts: ["remost-host:5044"]
  proxy_url: socks5://user:password@socks5-proxy:2233

proxy_usr_local_resolver (디폴트: false)

프록시를 사용할 때, 로그스태시 호스트 이름이 로컬에서 리졸빙되도록 설정한다. 디폴트는 false로, 즉 프록시를 사용하면서 호스트 이름의 리솔루션은 프록시 서버에서 수행한다는 의미이다.

index

이벤트에 작성할 인덱스 루트 이름을 설정한다. 디폴트는 Beat 이름이 된다.

ssl

로그스태시 연결을 위한 SSL 파라미터 옵션을 설정한다 (예: root CA). SSL을 사용하려면 반드시 로그스태시의 비트 인풋 플러그인 설정을 통해 SSL/TLS를 사용해야 한다.

timeout (디폴트: 30 (초))

로그스태시 서버와의 타임아웃을 시간을 초 단위로 설정한다. 여기에 설정된 시간동안 로그스태시 호스트로부터 응답이 없으면 타임아웃.

bulk_max_size (디폴트: 2048, 사용안함: value <= 0 )

로그스태시로의 한 번의 요청에 담길 수 있는 이벤트의 최대 개수를 설정한다. Beat가 보내는 하나 하나의 이벤트들은 모아져서 묶음이 되는데, Beat가 bulk_max_size의 값을 넘어서는 이벤트 묶음을 발행하면 이 묶음을 쪼갠다.

이벤트 묶음을 더 크게 설정하면, 이벤트 전송 횟수가 줄어들고, 결국 이벤트 전송 시 발생하는 오버헤드가 줄어들어 성능을 향상시킬 수 있다. 하지만 동시에, 큰 이벤트 묶음은 처리 시간을 늘어나게 할 수 있는데, 이는 API 에러, 커넥션의 끊어짐, 요청 타임아웃 등의 원인이 되어 결과적으로 처리량에 악영향을 미치게 된다.

bulk_max_size에 0 보다 작거나 같은 값을 설정하여 이 기능을 비활성화하면, 한 이벤트 묶음에 포함될 이벤트의 수는 큐가 결정하게 된다.

slow_start (디폴트: false)

true로 설정 시, 트랜잭션 당 한 이벤트 묶음의 부분 집합만을 전송한다. 에러가 없다면 전송되는 이벤트의 수는 최대 bulk_max_size까지 증가한다. 에러 발생 시 전송되는 이벤트의 수는 다시 줄어든다.

backoff.init (디폴트: 1s)

네트워크 에러 발생 후 로그스태시로의 재연결을 시도하기까지 대기하는 시간을 초 단위로 설정한다. 재연결 시도가 실패하면 대기 시간은 재연결 시도 횟수에 비례하여 증가하는데, 최대 backoff.max까지 증가한다. 연결에 성공하면 타이머는 리셋된다.

backoff.max (디폴트: 60s)

네트워크 에러 발생 후 로그스태시로의 재연결을 시도하기까지 대기하는 시간의 최대치를 설정한다.

7.6.0 릴리즈 버전 기준으로 작성됨

==

인풋, 모듈 설정을 외부 파일에서 불러올 수 있다.

인풋 설정

예:

filebeat.config.inputs:
    enabled: true
    path: inputs.d/*.yml

path 에서 잡히는 각 파일은 반드시 하나 이상의 input 설정을 가지고 있어야 하며, 각 파일의 첫 라인은 반드시 인풋 선언으로 시작해야 한다 (- type).

예:

- type: log
  paths: 
    - /var/log/mysql.log
  scan_frequency: 10s
  
- type: log
  paths: 
    - /var/log/apache.log
  scan_frequency: 5s

서로 다른 두 인풋이 같은 파일 경로를 대상으로 삼지 않돌고 해야한다. 둘 이상의 하베스터가 같은 파일을 동시에 읽게 되면 예상할 수 없는 상황이 발생할 수 있다.

모듈 설정

설정 방법은 인풋과 유사하지만, 모듈 설정을 불러오는 디폴트 경로는 modules.d 디렉토리라는 점이 다르다.

예:

filebeat.config.modules:
    enabled: true
    path: ${path.config}/modules.d/*.yml

modules 커맨드로 모듈 설정을 활성화/비활성화하려면 path는 반드시 modules.d 디렉토리로 설정해야한다.

path 에서 잡히는 각 파일은 반드시 하나 이상의 module 설정을 가지고 있어야 하며, 각 파일의 첫 라인은 반드시 모듈 선언으로 시작해야 한다 (- module).

예:

- module: apache
  access: 
    enabled: true
    var.paths: [/var/log/apache2/access.log*]
  error:
    enabled: true
    var.paths: [/var/log/apache2/error.log*]

7.6.0 릴리즈 버전 기준으로 작성됨.

==

여기의 옵션들은 모든 인풋에 사용할 수 있다. 한 곳에 설정하면 모든 인풋에 적용된다는 뜻이 아니다(general configuration). 인풋 타입이 관계 없이 사용할 수 있다는 뜻이다.

enabled (디폴트: true)

이 인풋의 활성화/비활성화를 설정한다.

tags

Filebeat가 발행하는 각 이벤트의 tags 필드에 포함될 태그를 설정한다. 태그는 키바나에서 특정 이벤트를 선택하는 일이나 Logstash에서의 조건부 필터링 적용에 유용하게 사용된다. 여기에 설정한 태그는 일반 설정(general configuration) 태그에 추가된다.

예: tags ["json", "note"]

fields

커스텀 필드 설정. 아웃풋에 포함될 추가적인 정보를 설정한다. 예로, 로그 데이터 필터링에 사용하기 위한 필드를 추가할 수 있다. 필드는 스칼라 값, 배열, 딕셔너리 혹은 이들이 중첩된 다른 어떠한 것이든 가능하다. 기본적으로 여기에 지정하는 필드는 아웃풋 도규먼트의 fields 서브딕셔너리로 그룹핑된다. fields_under_root 옵션을 true로 설정하여 커스텀 필드를 탑 레벨 필드로 둘 수 있다. 일반 설정(general configuration)의 필드와 중복 시 여기의 필드가 우선한다.

fields_under_root (디폴트: false)

true로 지정 시 아웃풋의 커스텀 필드를 탑 레벨 필드로 설정한다. false이면 fields의 서브딕셔너리로 그룹핑된다. 

processors

인풋 데이터에 적용되는 프로세서 목록이다.

pipeline

인풋이 생성하는 이벤트의 Ingest node 파이프라인 ID를 설정한다. 엘라스틱서치 아웃풋의 ID와 겹친다면 여기의 것이 우선한다.

keep_null (디폴트: false)

true로 지정 시 null 값을 지닌 필드도 아웃풋에 포함된다.

index

포맷팅된 문자열을 통해 인풋이 생성하는 이벤트의 인덱스를 설정하는데, 엘라스틱서치 아웃풋에 대해서는 index를 덮어쓰고, 다른 아웃풋에 대해서는 메타데이터의 raw_index 필드를 세팅한다. 설정 문자열에 사용할 수 있는 동적 필드는 에이전트 이름, 버전, 이벤트 타임스탬프가 있다. 다른 동적 필드를 사용하고 싶다면 output.elasticsearch.index 혹은 processor를 사용해야 한다.

예: "%{[agent.name]}-myindx-%{+yyyy.MM.dd}"

- 결과: "filebeat-myindex-2019.11.01"

7.6.0 릴리즈 버전 기준으로 작성됨

==

Filebeat에서 대표적으로 사용되는 input(이하 인풋)인 Log 설정 옵션들.

필수값은 옆에 필수라고 표시함.

paths (필수 / N개 설정 허용)

Go Glob 패턴 기반의 문자열로 수집 대상 로그 파일(혹은 경로)를 설정한다.

예: /var/log/*/*.log

- /var/log 아래(1 depth) 모든 서브폴더 안의 .log 파일을 수집 대상으로 설정한다 (/var/log 자신은 대상이 아님). 

recursive_glob.enabled (디폴트: true)

** 를 사용하여 재귀적 경로 탐색을 활성화한다.

예: /foo/** 

- /foo, /foo/*, /foo/*/* ... 가 대상 경로가 된다.

** 는 8 depth까지 적용된다.

encoding

파일에서 데이터를 읽을 때 적용되는 인코딩 설정.

exclude_lines (정규식)

정규식을 지정하여 해당 정규식이 매칭되는 라인은 수집 대상에서 제외한다.

multiline 설정이 지정되어 있을 경우, 멀티라인 메시지를 한 줄로 취급하여 정규식 매칭을 시도한다.

예: exclude_lines: ['^DBG']

- 'DBG' 로 시작하는 라인은 제외

include_lines (정규식)

정규식을 지정하여 해당 정규식이 매칭되는 라인만을 수집 대상으로 삼는다.

multiline 설정이 지정되어 있을 경우, 멀티라인 메시지를 한 줄로 취급하여 정규식 매칭을 시도한다.

예: exclude_lines: ['^ERR', '^WARN']

- 'ERR' 혹은 'WARN' 으로 시작하는 라인만 수집

include_lines 와 exclude_lines 가 혼용될 경우, include_lines 를 먼저 적용하여 수집 대상을 선별하고, 여기에 exclude_lines 를 적용하여 제외한다. 설정 순서는 영향 없음.

harvester_buffer_size (디폴트: 16384)

각 하베스터가 파일을 읽을 때 사용하는 버퍼 바이트 사이즈

max_bytes (디폴트: 10MB (10485760))

하나의 로그 메시지의 수집에 허용되는 최대 사이즈. 로그 메시지가 이 사이즈를 넘어가면, 넘어가는 바이트부터는 버려진다.

json 관련 옵션들

이 옵션들은 Filebeat가 JSON 형식의 로그를 디코딩하는 데에 사용된다. Filebeat는 로그를 라인 단위로 읽기 때문에, JSON 디코딩은 한 라인 당 하나의 JSON 객체가 존재할 경우에만 적용된다.

이 디코딩은 라인 필터링과 멀티라인 전에 적용된다. message_key 옵션을 통해 JSON 디코딩을 필터링 및 멀티라인과 함께 적용할 수 있다. 어플리케이션 로그가 JSON 객체로 래핑되어 있는 경우에 유용하다. 

아래 JSON 옵션 중 최소 하나를 지정하여야 JSON 파싱 모드가 활성화된다.

json.keys_under_root (디폴트: false)

디코딩된 JSON이 기본적으로 아웃풋 결과의 "json" 키 아래 놓이도록 한다.

json.overwrite_keys

keys_under_root와 이 옵션을 함께 적용하면, 디코딩된 JSON 객체의 값이 Filebeat가 기본적으로 추가하는 값을 덮어쓰도록 한다 (type, source, offset, 기타 등). 

json.add_eror_key

JSON 언마샬링 에러가 발생하거나, message_key가 설정되어 있으나 사용할 수 없는 경우에 Filebeat가 "error.message" 및 "error.type:json" 을 추가하도록 한다.

json.message_key

라인 필터링과 멀티라인 세팅에 적용되는 JSON key를 지정한다. 이 옵션을 활성화할 경우, 지정된 key는 반드시 JSON 객체의 탑 레벨 키여야 하며, 이 키에 매핑되는 값은 반드시 문자열이여야 한다. 그렇지 않으면 필터링 또는 멀티라인 취합은 적용되지 않는다.

json.document_id

document id 설정을 위한 JSON key를 지정한다. 키가 지정되면 원본 json document의 필드는 제거되고, @metadata.id로 저장된다.

json.ignore_decoding_error (디폴트: false)

발생한 JSON 디코딩 에러를 로그로 남길 것이냐를 설정한다.

multiline

Filebeat가 멀티라인 메시지를 다루는 방법을 설정한다.

multiline.pattern (정규식)

멀티라인 메시지임을 판단하는 정규식 패턴을 지정한다. 여기에 매칭되는 라인은 이전 라인에서 이어지는 멀티라인 혹은 새로운 멀티라인의 시작으로 간주한다. 이전 라인에서 이어지는 라인인지, 새 멀티라인인지는 아래 multiline.negate, muliline.match 설정에 따라 달라진다.

multiline.negate (디폴트: false)

multiline.pattern 매칭을 부정으로 적용한다.

multiline.match (after/before)

멀티라인 매칭을 적용하는 방식을 지정한다. after이면 pattern메 매칭되는 라인을 이전 라인에서 이어지는(appended) 메시지로 판단하고, before면 pattern에 매칭되는 라인을 다음에 나올, 매칭되지 않을 라인 이전에 등장하는(prepanded) 메시지로 판단한다. 이 옵션의 동작은 multiline.negate 설정과 밀접하게 관련되어 있다. 

위 옵션에 따른 멀티라인 매칭은 별도 글에서 자세히 설명한다.

multiline.flush_pattern (정규식)

지정된 정규식에 매칭되는 라인을 만나면, 멀티라인 메시지를 내보낸다 (flushing). 멀티라인의 끝을 의미한다.

multiline.max_lines (디폴트: 500)

하나의 멀티라인 메시지의 최대 라인 수를 설정한다. 이 수를 초과하는 라인부터는 버려진다.

multiline.timeout (디폴트: 5s)

멀티라인이 명시적으로 끝나지 않아도, 지정된 시간이 지나면 멀티라인 메시지를 내보낸다 (flushing).

exclude_files (정규식 / N개 설정 허용)

Filebeat의 읽기 대상에서 제외할 파일을 정규식으로 지정한다. 이 파일명이 정규식에 매칭되는 파일은 읽지 않는다.

예: exclude_files: ['\.gz$']

- .gz 확장자 파일을 제외한다.

ignore_older (디폴트: 0 (disabled))

시간을 설정하여 파일의 최종변경일시로부터 현재까지의 경과 시간이 여기 설정된 시간에 도달하면 Filebeat의 읽기 대상에서 제외한다. paths에 지정된 경로에 로그 파일을 오랜 기간 보관하는 경우에 특히 유용한 옵션. 예를 들어 최근 7주일 안에 수정된 파일들만 대상으로 삼고자 하는 시나리오 등에 사용할 수 있다.

예: ignore_older: 2h

- 최근 2시간 안에 갱신된 파일만 읽는다.

예: ignore_older: 5m

- 최근 5분 안에 갱신된 파일만 읽는다.

이 설정에 영향을 받는 파일은 다음 두 카테고리로 나뉜다.

1. 한 번도 수집되지 않은 파일

2. 수집된 적이 있으나 ignore_older 보다 긴 시간동안 수정되지 않은 파일

한 번도 수집되지 않은 파일의 경우, 오프셋 상태는 파일의 끝으로 잡힌다. 이미 상태가 존재하는(수집된 적이 있는) 경우, 오프셋은 변경되지 않는다. 후에 파일이 변경되면 이전에 기록된 오프셋에서부터 읽기 시작한다.

ignore_older는 파일의 최종변경일시에 의존한다. 만약 파일에 새로운 내용이 쓰여졌는데 최종변경일시가 갱신되지 않는다면 Filebeat는 새로운 내용을 읽지 못한다.

Filebeat가 ignore_older에 따라 파일을 읽기 대상에서 제외하도록 하려면, 반드시 그 파일은 닫힌 상태여야 한다. 이를 확실하게 하기 위해서는 ignore_older를 close_inactive보다 길게 잡아야한다.

만약 현재 읽고 있는 파일이 ignore_older의 제외 대상에 들어가면, 하베스터는 먼저 읽기 작업을 마치고, 후에 close_inactive에 도달하면 파일을 닫고, 파일을 대상에서 제외한다. 즉 적용 순서는 close_inactive -> ignore_older 가 된다.

close_*

하베스터를 닫는 특정 조건이나 시간을 설정한다. 하베스터를 닫는다는 것은 파일 핸들러를 닫는다는 의미이다. 파일 핸들러가 닫힌 뒤 파일이 갱신되면, 해당 파일을 다시 읽는 작업은 scan_frequency만큼의 시간이 지난 뒤에 시작된다. 파일 핸들러가 닫혔을 때 해당 파일이 사라지면 Filebeat는 파일로의 작업을 재개하지 못하고, 읽지 못한 데이터는 유실된다. close_* 설정은 Filebeat가 파일을 읽으려 시도할 때 동기적으로 적용된다. 말하자면, Filebeat가 어떤 이유로 블록 상태에 빠져 있다면, 닫혀야 할 파일은 Filebeat가 다시 파일로 읽기 작업을 시도할 때까지 open 상태로 남게 된다.

close_inactive (디폴트: 5m)

파일 핸들러의 타임아웃 설정. 시간을 지정하여 이 시간동안 파일 읽기 작업이 발생하지 않으면 해당 파일 핸들을 닫는다. 시간 카운터는 하베스터가 파일로부터 마지막 로그 라인을 읽은 때부터 시작된다. 

이 시간 설정은 수집 대상 로그 파일의 최소 갱신 빈도보다 크게 설정할 것을 권장한다. 예로, 로그 파일에 수 초 주기로 새 데이터가 작성된다면, close_inacitve는 안전하게 1m으로 잡는 것이 좋다. 대상 로그 파일들의 갱신 빈도가 서로 심하게 다르다면, close_inactive를 서로 다른 값으로 여러개를 설정할 수 있다.

close_inactive를 적게 설정한다는 것은 파일 핸들을 그만큼 일찍 닫는다는 의미이다. 이렇게 되면 새로운 로그 라인을 실시간에 가깝게 읽고 전송하는 데에 문제가 될 수 있다.

이 설정의 동작은 파일의 최종변경일시와는 무관하다. Filebeat는 내부적으로 파일을 마지막으로 읽은 시간을 가지고 있다. close_inactive 카운트다운은 이 시간에서부터 시작된다.

close_renamed

파일 이름이 변경되면 Filebeat가 파일 핸들을 닫도록 한다. 예로, rotating 파일의 경우 이런 상황이 발생할 수 있다. 기본적으로 파일 핸들러는 파일 이름에 의존하지 않기 때문에, 파일 이름이 변경되어도 하베스터는 파일을 열고 있는다. 이 옵션을 활성화하고 파일 이름을 변경하거나 파일을 paths 설정에서 벗어나는 곳으로 이동시키면 그 파일로의 작업은 다시 이루어지지 않고, Filebeat는 읽기 작업을 완료하지 못한다.

데이터가 유실될 수 있는 여지가 있음을 이해하고 사용해야 한다.

close_removed (디폴트: true)

파일이 삭제되면 Filebeat가 해당 파일을 담당하는 하베스터를 닫도록 한다. 일반적으로는 close_inactive에 도달하여 inacitve가 된 파일만이 삭제되어야 하지만, 그렇지 못한 상태에서 파일이 삭제되면 Filebeat는 하베스터의 작업 완료를 위해 파일을 연 상태로 유지한다. 이 옵션으로 인해 너무 일찍 삭제된 파일을 다 읽지 못하게 된다면, 이 옵션을 비활성화하도록 한다.

이 옵션을 비활성화 한다면 clean_removed도 반드시 함께 비활성화 해야 한다.

close_eof (디폴트: false)

EOF에 도달하는 즉시 Filebeat가 파일을 닫도록 한다. 파일이 한 번 작성된 후에 갱신되지 않는 경우에 유용하다. 예로. 모든 로그 이벤트를 새 파일에 작성하는 경우가 있다.

데이터가 유실될 수 있는 여지가 있음을 이해하고 사용해야 한다.

close_timeout (디폴트: 0 (disabled))

하베스터에 미리 정의된 수명을 설정한다. 하베스터가 파일을 읽는 중에라도 이 시간에 도달하면 작업을 중단한다. 각 파일에 대해 정해진 시간만큼만 작업을 수행하고자 할 때 사용할 수 있다. 로그가 계속 쓰여지고 있는 상황에 close_timeout으로 기존 하베스터가 작업을 중단하게 되면, scan_prequency가 경과한 뒤 새로운 하베스터가 시작되어 작업을 재개한다. 이 새 하베스터에도 물론 새로운 close_timeout 카운트다운이 시작된다.

아웃풋이 블록되어 Filebeat가 디스크에서 삭제된 파일의 파일 핸들러를 열고 있는 상황에 유용할 수 있다. close_timeout을 5m으로 설정하면 어떤 작업 중이든 5분마다 파일 핸들을 닫아서 os가 파일을 해제할 수 있도록 한다.

close_timeout을 ignore_older과 같게 설정하면, 하베스터가 닫힌 뒤 파일이 수정되어도 파일을 다시 읽지 않는다. 데이터가 유실될 수 있다.

close_timeout을 멀티라인 이벤트를 포함한 로그에 사용하면 하베스터가 멀티라인을 읽는 중에 작업이 중단될 수 있다. 이렇게 되면 멀티라인 메시지의 일부만 아웃풋으로 전송되게 된다. 이렇게 된 뒤에 하베스터가 다시 시작되면 나머지 부분만을 전송한다.

clean_*

레지스트리 파일에서 상태 정보를 삭제한다. 레지스트리 파일의 사이즈를 줄이는 데에 사용될 수 있다. 잠재적인 inode 재사용 문제를 막을 수도 있다.

clean_inacitve

시간을 설정하여 이 시간이 경과될 때까지 갱신되지 않은 파일 상태 정보를 삭제한다. 삭제될 상태 정보는 ignore_older로 작업 대상에서 제외된 파일에 대한 것만을 대상으로 해야 한다. 때문에 clean_inactive는 반드시 ignore_older + scan_frequency보다 크게 설정하여, 아직 읽히고 있는 파일의 상태를 삭제하는 일이 없도록 해야 한다. 그렇지 않으면 Filebeat가 이미 전송한 파일 데이터 전체를 다시 전송하게 될 수 있다 (파일에 대한 기존 작업 상태 정보가 삭제되어 없는데, ignore_older로 제외되지 않으면 다시 작업 대상이 되기 때문). 상태 정보가 삭제된 파일이 갱신되거나 복구되면 파일을 처음부터 읽는다.

이 설정은 레지스트리 파일의 사이즈를 줄이는 데에 사용될 수 있고, inode 재사용 문제를 방지하는 데에도 도움이 될 수 있다.

파일 이름이 변경되면 파일 상태가 갱신되고 clean_inactive도 0으로 초기화된다.

Filebeat가 clean_inactive로 파일 상태 정보를 삭제하는 시점은 레지스트리 파일을 읽는 때이고, 레지스트리 파일은 다른 파일을 읽기 위한 상태 정보를 조회할 때 읽힌다. 즉 clean_inactive 시간에 도달해도 Filebeat가 다른 파일을 읽지 않는다면 상태 정보는 삭제되지 않는다.

clean_removed (디폴트: true)

삭제된 파일의 상태 정보를 레지스트리 파일에서 삭제한다. 파일이 삭제되었는지는 마지막에 저장된 상태 정보의 파일의 full path를 바탕으로 판단한다. 때문에 하베스터가 작업을 마친 뒤 파일 이름이 변경되었다면 이 파일도 삭제된 것으로 간주하고 상태 정보를 삭제한다.

공유 드라이브가 잠시 사라졌다가 복구되는 경우, 레지스트리 파일이 삭제되기 때문에 모든 파일을 처음부터 다시 읽기 시작한다. 때문에 이런 가능성이 있는 경우 clean_removed를 false로 설정할 것을 권한다.

close_removed를 비활성화하는 경우 이 옵션도 반드시 함께 비활성화해야한다.

scan_frequency (디폴트: 10s)

Filebeat가 새로운 혹은 갱신된 파일이 있는지 확인하는 빈도를 설정한다. 확인 경로는 paths 설정을 바탕으로 한다. 1초 미만으로 설정하는 것은 권장하지 않는다.

실시간에 가까운 로그 라인 전송을 원한다면 이 값을 낮게 설정하기보다는 close_inactive를 조정하여 파일 핸들러를 open으로 유지하여 파일 폴링을 지속하도록 해야한다.

scan.sort (디폴트: 사용안함) (임시 옵션)

파일 스캐닝 시 정렬 기준을 설정한다. 오름차순/내림차순은 scan.order를 통해 설정한다. 다음 두 가지 옵션이 있다.

modtime: 최종변경일시 기준

filename: 파일 이름 기준

scan.order (디폴트: asc) (임시 옵션)

파일 스캐닝 시 정렬의 오름차순/내림차순을 설정한다. scan.sort와 함께 사용된다.

asc: 오름차순

desc: 내림차순

tail_files (디폴트: false)

true로 설정하면 파일을 끝에서부터 읽기 시작한다. 이 옵션을 로그 로테이션과 함께 사용하면 새 파일의 첫 로그는 스킵될 수 있다.

이 옵션은 Filebeat가 처음으로 읽는 파일에 대해 적용된다. 이미 읽었던 상태 정보가 남아 있는 파일에는 적용되지 않는다. 때문에 모든 파일에 대해 이 옵션을 적용하려면 Filebeat를 정지하고 모든 레지스트리 파일을 삭제해야한다.

symlinks (디폴트: 사용안함)

링크 파일을 작업 대상으로 허용한다. 파일 오픈 및 읽기 작업은 원본 파일에 대해 이루어진다.

이 옵션을 사용할 때는 원본 파일을 제외해야 한다. 단일 인풋에 링크 파일과 원본 파일이 함께 설정된 경우, Filebeat는 처음 찾은 파일만을 읽는다. 두 인풋에 개별적으로 링크 파일과 원본 파일이 설정된 경우, 두 경로 모두 작업 대상이 되고 Filebeat는 중복된 데이터를 전송하고 두 인풋은 서로의 상태 정보를 덮어쓰게 된다.

이 옵션은 로그의 링크 파일 이름에 추가적인 메타데이터가 포함되고, 메타데이터를 Logstash에서 처리하고자 하는 경우에 유용하다. 예로, 쿠버네티스 로그 파일의 경우가 그렇다.

이 옵션은 데이터 유실이 발생할 수 있다.

backoff (디폴트: 1s)

Filebeat가 파일의 EOF를 만난 뒤 새 라인이 작성되었는지 확인하기까지 대기하는 시간을 설정한다. 대부분의 경우 디폴트 설정은 1초로 충분하다. 파일에 새 라인이 추가될 때마다 타이머가 초기화된다.

max_backoff (디폴트: 10s)

Filebeat가 파일의 EOF를 만난 뒤 새 라인이 작성되었는지 확인하기까지 대기하는 시간의 리미트를 설정한다. 새 라인의 존재 여부를 체크하다가 이 설정 시간에 도달하면 더이상 확인하지 않는다. 대기 시간은 backoff_factor 설정값에 상관없이 max_backoff를 절대 초과하지 않는다.

필수 사항: backoff <= max_backoff <= scan_frequency

max_backoff를 더 높여야 한다면, 차라리 파일 핸들러를 닫고 Filebeat가 파일을 다시 잡도록 하는 편이 좋다.

backoff_factor (디폴트: 2, 최소값: 1 (backoff is disabled))

새 라인을 대기하는 시간 타이머의 속도를 설정한다. max_backoff에 도달하기까지 backoff 에 이 설정값을 곱한다. 즉 이 설정값이 클수록 max_backoff에 더 빨리 도달하게 된다. 설정 최소값인 1 로 설정하면 backoff 알고리즘은 비활성화되고 backoff 값이 대기 시간으로 적용된다.

harvester_limit (디폴트: 0 (no limit))

한 인풋에서 병렬로 작동할 수 있는 하베스터 수의 최대치를 설정한다. 이 설정값은 파일 핸들러 수의 최대치와 연결된다. 작업 대상 파일의 수가 os의 파일 핸들러 수의 최대치를 초과하는 경우에 유용하다.

하베스터 수의 최대치를 설정함이 병렬로 열리는 모든 파일의 수를 설정한다는 의미가 되진 않는다. 이 옵션은 close_* 옵션과 함께 사용하여 하베스터를 더 자주 정지시켜, 새 파일을 작업할 수 있도록 하기를 권한다.

현재는 어떤 하베스터가 작업을 시작할지는 랜덤으로 결정된다. 더 오래 대기한 하베스터가 있더라도, 막 작업을 마친 하베스터가 다음 작업자가 될 수도 있다.

이 옵션은 인풋마다 개별적으로 적용된다. 특정 인풋에 더 높은 설정값을 둠으로써 간접적으로 인풋의 우선 순위를 부여할 수 있다.