Filebeat Log input 설정

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_* 옵션과 함께 사용하여 하베스터를 더 자주 정지시켜, 새 파일을 작업할 수 있도록 하기를 권한다.

 

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

 

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