로그 Pipeline 사용 설명서¶
Pipeline은 다양한 형식의 로그 데이터에 대한 텍스트 파싱을 지원합니다. Pipeline 스크립트를 작성하면 요구사항에 맞는 구조화된 로그를 직접 파싱할 수 있으며, 파싱된 필드를 속성으로 사용할 수 있습니다. 속성 필드를 활용하면 관련 로그를 빠르게 필터링하고 데이터 연관 분석을 수행하여 문제를 신속하게 파악하고 해결할 수 있습니다.
Guance는 공식 Pipeline 스크립트 라이브러리를 제공하며, 다양한 로그 파싱 Pipeline이 내장되어 있습니다. 또한 사용자가 사용자 지정 Pipeline 스크립트를 생성할 수 있도록 지원합니다. 이제 사용자 지정 Pipeline 기능을 사용하는 방법을 소개합니다.
전제 조건¶
- 먼저 Guance 계정을 만들고 호스트에 DataKit을 설치해야 합니다.
- 로그 수집기를 활성화하고 구성 파일에서 Pipeline 기능을 켭니다.
사용자 지정 Pipeline 스크립트 파일¶
1단계: 로그 수집기 활성화(DataKit 로그 예시)¶
호스트에 DataKit을 설치한 후 /usr/local/datakit/conf.d/log 디렉토리에서 logging.conf.sample을 복사하여 logging.conf로 이름을 바꾸고, logging.conf를 편집하여 DataKit 로그가 저장되는 경로와 로그 소스를 구성합니다. 예:
logfiles = ["/var/log/datakit/log"]source = "datakit"
참고: 로그 수집기에서 Pipeline 기능은 기본적으로 활성화되어 있으며, Pipeline = ""에 구체적인 Pipeline 스크립트 이름을 입력하지 않아도 source와 동일한 이름의 스크립트 파일이 자동으로 매칭됩니다. 로그 소스와 Pipeline 파일 이름이 일치하지 않으면 로그 수집기 구성에서 Pipeline = "xxxxxx.p"로 설정해야 합니다.
[[inputs.logging]]
## required
logfiles = [
"/var/log/datakit/log",
]
# only two protocols are supported:TCP and UDP
# sockets = [
# "tcp://0.0.0.0:9530",
# "udp://0.0.0.0:9531",
# ]
## glob filteer
ignore = [""]
## your logging source, if it's empty, use 'default'
source = "datakit"
## add service tag, if it's empty, use $source.
service = ""
## grok pipeline script name
## pipeline을 구체적으로 지정하지 않으면 source와 동일한 이름의 스크립트를 자동으로 찾습니다
pipeline = ""
구성이 완료되면 명령줄에서 datakit --restart를 실행하여 DataKit을 재시작하고 구성을 적용합니다.
2단계: 수집된 로그를 기반으로 파싱 필드 결정¶
로그 수집기를 활성화하면 Guance 워크스페이스에서 수집된 DataKit 로그를 확인할 수 있습니다. DataKit 로그를 관찰하고 분석하여 로그 생성 시간, 로그 레벨, 로그 모듈, 모듈 내용, 로그 내용 등 로그 파싱에 필요한 필드를 결정합니다.
3단계: 사용자 지정 Pipeline 생성¶
Guance 워크스페이스의 로그 > Pipelines에서 Pipeline 생성을 클릭하여 새 Pipeline 파일을 만듭니다.
로그 필터링¶
로그 소스로 "datakit"를 선택합니다. 선택한 로그 소스를 기준으로 동일한 이름의 Pipeline이 자동으로 생성됩니다.
파싱 규칙 정의¶
로그의 파싱 규칙을 정의하며, 다양한 스크립트 함수를 지원합니다. 편집 영역에는 기본적으로 소스 코드가 표시되며, 플로우 차트로 전환하여 분기와 반복의 처리 관계를 확인하거나 단계 모드로 전환하여 스크립트를 항목별로 읽을 수 있습니다. 세 가지 모드는 동일한 스크립트를 공유하며, 함수 라이브러리를 클릭하면 함수 설명과 구문 형식을 확인할 수 있습니다.
플로우 차트 또는 단계 모드에서 노드를 클릭하면 매개변수나 노드 소스 코드를 수정할 수 있으며, 적용을 클릭하면 전체 스크립트에 동기화됩니다. 또한 노드를 삽입, 삭제, 위아래로 이동하거나 동일한 코드 블록 내에서 드래그하여 정렬할 수 있습니다. 구체적인 작업 방법과 사용 제한 사항은 파싱 규칙 편집을 참조하세요.
이 예시에서는 로그 관찰 결과를 바탕으로 Pipeline 스크립트 파일을 작성할 수 있습니다. add_pattern() 스크립트 함수를 사용하여 먼저 pattern을 정의한 뒤 Grok에서 사용자 지정 pattern을 참조하여 로그를 파싱할 수 있습니다. 아래 예시에서 rename과 default_time은 파싱된 필드를 최적화하는 데 사용됩니다.
add_pattern('_dklog_date', '%{YEAR}-%{MONTHNUM}-%{MONTHDAY}T%{HOUR}:%{MINUTE}:%{SECOND}%{INT}')
add_pattern('_dklog_level', '(DEBUG|INFO|WARN|ERROR|FATAL)')
add_pattern('_dklog_mod', '%{WORD}')
add_pattern('_dklog_source_file', '(/?[\\w_%!$@:.,-]?/?)(\\S+)?')
add_pattern('_dklog_msg', '%{GREEDYDATA}')
grok(_, '%{_dklog_date:log_time}%{SPACE}%{_dklog_level:level}%{SPACE}%{_dklog_mod:module}%{SPACE}%{_dklog_source_file:code}%{SPACE}%{_dklog_msg:msg}')
rename("time", log_time) # log_time을 time으로 이름 변경
default_time(time) # time 필드를 출력 데이터의 타임스탬프로 사용
Pipeline 파싱 규칙에 대한 자세한 내용은 텍스트 데이터 처리(Pipeline) 문서를 참조하세요.
로그 샘플 테스트¶
스크립트 규칙 작성이 완료되면 테스트 샘플에 로그를 직접 입력하거나 샘플 자동 가져오기를 클릭합니다. 로그 샘플은 Message만, 전체 필드(JSON), 전체 필드(라인 프로토콜)의 세 가지 형식을 지원합니다.
샘플 추가를 클릭하면 샘플을 추가할 수 있으며, 최대 3개까지 탭으로 전환하며 편집할 수 있습니다. 테스트 시작을 클릭하면 비어 있지 않은 모든 샘플이 실행되며, 결과는 편집 영역 오른쪽의 별도 오버레이에 샘플별로 표시됩니다. 오버레이를 닫은 후 결과 보기를 통해 다시 열 수 있고, 확대, 복사 또는 고정 후 드래그할 수도 있습니다.
스크립트나 샘플을 수정하면 이전 결과가 재테스트 필요로 표시되므로, 현재 파싱 결과를 확인하려면 다시 실행하세요. 자세한 작업 방법은 테스트 샘플 및 테스트 결과 보기를 참조하세요.
참고:
- 로그 샘플 테스트는 필수 항목이 아닙니다.
- 사용자 지정 Pipeline을 저장하면 로그 샘플 테스트 데이터도 함께 저장됩니다.
- JSON 샘플은 유효한 객체여야 하며, 테스트와 저장 전에 현재 선택되지 않은 탭을 포함한 모든 샘플을 검증합니다.
4단계: Pipeline 파일 저장¶
필수 항목 구성을 모두 완료한 후 Pipeline 파일을 저장하면 로그 Pipelines 목록에서 사용자 지정 Pipeline 파일을 확인할 수 있습니다.
Guance 워크스페이스에서 생성한 Pipeline 파일은 /usr/local/datakit/Pipeline_remote 디렉토리에 저장됩니다.
참고: DataKit에는 두 개의 Pipeline 디렉토리가 있으며, DataKit은 해당 디렉토리의 Pipeline 파일을 자동으로 매칭합니다.
Pipeline: 공식 라이브러리의 Pipeline 파일 디렉토리Pipeline_remote: Guance 워크스페이스의 사용자 지정 Pipeline 파일 디렉토리- 두 디렉토리에 동일한 이름의 Pipeline 파일이 있으면 DataKit은
Pipeline_remote의 Pipeline 파일을 우선적으로 매칭합니다.
5단계: Guance에서 파싱된 필드 확인¶
Guance 워크스페이스의 로그에서 datakit 로그를 선택하면 로그 상세 페이지의 "속성"에서 필드와 필드 값을 확인할 수 있습니다. 이것이 로그 파싱 후 표시되는 필드와 필드 값입니다. 예:
code: container/input.go:167level: ERRORmodule: container
공식 라이브러리 Pipeline 스크립트 파일 복제¶
1단계: Nginx 수집기 활성화¶
호스트에 DataKit을 설치한 후 /usr/local/datakit/conf.d/nginx 디렉토리에서 nginx.conf.sample을 복사하여 nginx.conf로 이름을 바꾸고, nginx.conf를 편집하여 Nginx 로그가 저장되는 경로와 Pipeline을 구성합니다. 예:
files = ["/var/log/nginx/access.log","/var/log/nginx/error.log"]Pipeline = "nginx.p"(여기서""에 구체적인 Pipeline 스크립트 이름을 입력하지 않아도 DataKit이 source와 동일한 이름의 스크립트 파일을 자동으로 매칭합니다)
참고: Pipeline을 활성화하면 DataKit은 로그 소스를 기준으로 Pipeline 스크립트 파일을 자동으로 매칭합니다. 로그 소스와 Pipeline 파일 이름이 일치하지 않으면 수집기에서 설정해야 합니다. 예를 들어 로그 소스가 nginx이고 Pipeline 파일 이름이 nginx1.p라면 Pipeline = "nginx1.p"로 설정해야 합니다.
[[inputs.nginx]]
url = "http://localhost/server_status"
# ##(optional) collection interval, default is 30s
# interval = "30s"
use_vts = false
## Optional TLS Config
# tls_ca = "/xxx/ca.pem"
# tls_cert = "/xxx/cert.cer"
# tls_key = "/xxx/key.key"
## Use TLS but skip chain & host verification
insecure_skip_verify = false
# HTTP response timeout (default: 5s)
response_timeout = "20s"
[inputs.nginx.log]
files = ["/var/log/nginx/access.log","/var/log/nginx/error.log"]
# # grok pipeline script path
pipeline = "nginx.p"
[inputs.nginx.tags]
# some_tag = "some_value"
# more_tag = "some_other_value"
# ...
구성이 완료되면 명령줄에서 datakit --restart를 실행하여 DataKit을 재시작하고 구성을 적용합니다.
Nginx 수집기 구성에 대한 자세한 내용은 Nginx를 참조하세요.
2단계: 수집된 로그를 기반으로 파싱 필드 결정¶
Nginx 수집기를 활성화하고 로그 파일 경로를 구성한 다음 Pipeline을 활성화하면 Guance 워크스페이스에서 수집된 Nginx 로그를 확인할 수 있습니다. 로그 상세에서 Pipeline 파일을 기준으로 파싱된 필드 속성을 확인할 수 있습니다. 로그를 관찰하고 분석하여 파싱 필드의 최적화가 필요한지 결정합니다.
3단계: 공식 라이브러리 Pipeline 복제 및 사용자 지정¶
Guance 워크스페이스의 로그 > Pipelines에서 Pipeline 공식 라이브러리를 클릭하고 nginx.p Pipeline 파일을 확인한 후 복제합니다.
- 로그 필터링에서 "nginx"를 선택합니다.
- 파싱 규칙 정의에서 파싱 규칙을 최적화합니다.
- 테스트 샘플에 nginx 로그 데이터를 입력하고 테스트 시작을 클릭한 후 결과 오버레이에서 각 샘플의 파싱 결과를 확인합니다.
참고:
- Pipeline 공식 라이브러리에는 여러 로그 샘플 테스트 데이터가 포함되어 있으며, "복제" 전에 필요에 맞는 로그 샘플 테스트 데이터를 선택할 수 있습니다.
- 복제한 Pipeline을 수정하여 저장하면 로그 샘플 테스트 데이터도 함께 저장됩니다.
2022/02/23 14:26:19 [error] 632#632: *62 connect() failed (111: Connection refused) while connecting to upstream, client: ::1, server: _, request: "GET /server_status HTTP/1.1", upstream: "http://127.0.0.1:5000/server_status", host: "localhost"
4단계: Pipeline 파일 저장¶
필수 항목 구성을 모두 완료한 후 Pipeline 파일을 저장하면 로그 Pipelines 목록에서 사용자 지정 Pipeline 파일을 확인할 수 있습니다.
Guance 워크스페이스에서 생성한 Pipeline 파일은 /usr/local/datakit/Pipeline_remote 디렉토리에 저장됩니다.
참고: DataKit에는 두 개의 Pipeline 디렉토리가 있으며, DataKit은 해당 디렉토리의 Pipeline 파일을 자동으로 매칭합니다.
Pipeline: 공식 라이브러리의 Pipeline 파일 디렉토리Pipeline_remote: Guance 워크스페이스의 사용자 지정 Pipeline 파일 디렉토리- 두 디렉토리에 동일한 이름의 Pipeline 파일이 있으면 DataKit은
Pipeline_remote의 Pipeline 파일을 우선적으로 매칭합니다.
5단계: Guance에서 파싱된 필드 확인¶
Guance 워크스페이스의 로그에서 nginx 로그를 선택하면 로그 상세 페이지의 "속성"에서 필드와 필드 값을 확인할 수 있습니다. 이것이 로그 파싱 후 표시되는 필드와 필드 값입니다. 예:
http_method: GEThttp_url: /server_statushttp_version: 1.1
추가 자료¶
이상으로 Guance 워크스페이스 로그 Pipeline 사용 설명서를 마칩니다. Pipeline 및 로그 수집·파싱에 대한 자세한 내용은 다음 문서를 참조하세요.







