Logging 에이전트 구성

이 페이지에서는 Cloud Logging 에이전트의 기본 구성과 커스텀 구성을 자세히 설명합니다.

대부분의 사용자는 이 페이지를 읽을 필요가 없습니다. 다음의 경우 이 페이지를 읽으세요.

• Cloud Logging 에이전트의 구성에 대하여 기술 세부정보를 자세히 알아보고 싶은 경우.

• Cloud Logging 에이전트의 구성을 변경하려는 경우.

기본 구성

Logging 에이전트 google-fluentd는 fluentd 로그 데이터 수집기의 수정 버전입니다. Logging 에이전트는 기본 구성으로 제공되며 일반적인 경우에는 대개 추가 구성이 필요하지 않습니다.

기본 구성에서는 Logging 에이전트가 기본 로그 목록에 포함된 로그를 Cloud Logging으로 스트리밍합니다. 추가 로그를 스트리밍하도록 에이전트를 구성할 수 있습니다. 자세한 내용은 이 페이지의 Logging 에이전트 구성 맞춤설정을 참조하세요.

Logging 에이전트는 fluentd 입력 플러그인을 사용하여 디스크 상의 파일과 같은 외부 소스에서 이벤트 로그를 검색하고 가져오거나 수신되는 로그 레코드를 파싱합니다. 입력 플러그인은 에이전트와 함께 번들로 제공되거나 Ruby gem으로 별도 설치가 가능합니다. 번들로 제공되는 플러그인 목록을 참조하세요.

Logging 에이전트는 fluentd의 기본 제공 in_tail 플러그인을 통해 VM 인스턴스의 로그 파일에 저장된 로그 레코드를 읽습니다. 각 로그 레코드는 Cloud Logging에 적합한 로그 항목 구조로 변환됩니다. 각 로그 레코드의 콘텐츠는 대부분 로그 항목의 페이로드에 기록되지만 로그 항목에는 타임스탬프와 심각도 같은 기본 요소도 포함되어 있습니다. Logging 에이전트는 각 로그 레코드에 문자열 형식의 태그를 붙이도록 하고 있습니다. 즉, 모든 쿼리와 출력 플러그인이 특정 태그 세트와 일치합니다. 로그 이름은 일반적으로 projects/[PROJECT-ID]/logs/[TAG]와 같은 형식을 따릅니다. 예를 들어 이 로그 이름에는 structured-log 태그가 포함되어 있습니다.

projects/my-sample-project-12345/logs/structured-log

출력 플러그인은 내부화되고 구조화된 각 메시지를 Cloud Logging의 로그 항목으로 변환합니다. 페이로드는 텍스트 또는 JSON 페이로드가 됩니다.

다음 섹션에서는 기본 구성에 관하여 자세히 설명합니다.

기본 구성 정의

다음 섹션에서는 syslog, forward 입력 플러그인, 기본 로그 목록에 나열된 타사 애플리케이션 로그의 입력 구성, Google Cloud fluentd 출력 플러그인의 기본 구성 정의를 설명합니다.

루트 구성 파일 위치

• Linux: /etc/google-fluentd/google-fluentd.conf

  이 루트 구성 파일은 /etc/google-fluentd/config.d 폴더의 모든 구성 파일도 내보냅니다.

• Windows: C:\Program Files (x86)\Stackdriver\LoggingAgent\fluent.conf

  v1-5 이전 버전의 Logging 에이전트를 실행 중인 경우: C:\GoogleStackdriverLoggingAgent\fluent.conf

Syslog 구성

참고: google-fluentd-catch-all-config 패키지의 일부인 다음 기본값 syslog 구성은 Linux 운영체제 전용입니다.

• 구성 파일 위치: /etc/google-fluentd/config.d/syslog.conf

• 설명: 이 파일에는 syslog를 로그 입력으로 지정하는 구성이 포함되어 있습니다.

• 구성 저장소를 검토하세요.

구성 이름	유형	기본값	설명
format	문자열	/^(?<message>(?<time>[^ ]*\s*[^ ]* [^ ]*) .*)$/	syslog의 형식입니다.
path	문자열	/var/log/syslog	syslog 파일의 경로입니다.
pos_file	문자열	/var/lib/google-fluentd/pos/syslog.pos	이 로그 입력의 위치 파일 경로입니다. fluentd는 마지막으로 읽은 위치를 이 파일에 기록합니다. 자세한 내용은 fluentd 문서를 검토하세요.
read_from_head	부울	true	파일의 하단이 아니라 상단에서부터 로그를 읽기 시작해야 하는지 여부입니다. 자세한 내용은 fluentd 문서를 검토하세요.
tag	문자열	syslog	이 로그 입력의 로그 태그입니다.

in_forward 입력 플러그인 구성

참고: google-fluentd-catch-all-config 패키지의 일부인 다음 기본값 in_forward 플러그인 구성은 Linux 운영체제 전용입니다.

• 구성 파일 위치: /etc/google-fluentd/config.d/forward.conf

• 설명: 이 파일에는 in_forward fluentd 입력 플러그인을 구성하는 구성이 포함되어 있습니다. in_forward 입력 플러그인을 사용하면 TCP 소켓을 통해 로그를 전달할 수 있습니다.

• 이 플러그인과 구성 저장소에 대한 자세한 내용은 fluentd 문서를 검토하세요.

구성 이름	유형	기본값	설명
port	정수	24224	모니터링할 포트입니다.
bind	문자열	127.0.0.1	모니터링할 바인드 주소입니다. 기본적으로 localhost의 연결만 허용됩니다. 바인드를 풀려면 이 구성을 0.0.0.0으로 변경해야 합니다.

타사 애플리케이션 로그 입력 구성

참고: google-fluentd-catch-all-config 패키지의 일부인 다음 기본 타사 애플리케이션 로그 구성은 Linux 운영체제 전용입니다.

• 구성 파일 위치: /etc/google-fluentd/config.d/[APPLICATION_NAME].conf

• 설명: 이 디렉터리에는 타사 애플리케이션의 로그 파일을 로그 입력으로 지정하는 구성 파일이 포함되어 있습니다. syslog.conf와 forward.conf를 제외하고 각 파일은 하나의 애플리케이션을 나타냅니다. 예를 들어 apache.conf는 Apache 애플리케이션을 나타냅니다.

• 구성 저장소를 검토하세요.

구성 이름	유형	기본값	설명
format^1	문자열	애플리케이션에 따라 다름	로그의 형식입니다. 자세한 내용은 fluentd 문서를 검토하세요.
path	문자열	애플리케이션에 따라 다름	로그 파일 경로입니다. 경로가 여러 개이면 ','로 구분하여 지정하고, * 및 strftime 형식을 포함하여 감시 파일을 동적으로 추가/삭제할 수 있습니다. 자세한 내용은 fluentd 문서를 검토하세요.
pos_file	문자열	애플리케이션에 따라 다름	이 로그 입력의 위치 파일 경로입니다. fluentd는 마지막으로 읽은 위치를 이 파일에 기록합니다. 자세한 내용은 fluentd 문서를 검토하세요.
read_from_head	부울	true	파일의 하단이 아니라 상단에서부터 로그를 읽기 시작해야 하는지 여부입니다. 자세한 내용은 fluentd 문서를 검토하세요.
tag	문자열	다양함. 애플리케이션의 이름.	이 로그 입력의 로그 태그입니다.

¹ <parse> 스탠자를 사용하는 경우 @type를 사용하여 로그 형식을 지정합니다.

Google Cloud fluentd 출력 플러그인 구성

• 구성 파일 위치:

  • Linux: /etc/google-fluentd/google-fluentd.conf

  • Windows: C:\Program Files (x86)\Stackdriver\LoggingAgent\fluent.conf

    v1-5 이전 버전의 Logging 에이전트를 실행 중인 경우: C:\GoogleStackdriverLoggingAgent\fluent.conf

• 설명: 이 파일에는 Google Cloud fluentd 출력 플러그인 동작을 제어하는 구성 옵션이 포함되어 있습니다.

• 구성 저장소로 이동합니다.

구성 이름	유형	기본값	설명
buffer_chunk_limit	문자열	512KB	로그 레코드가 들어올 때 다운스트림 구성요소로 빨리 기록될 수 없는 레코드는 청크 큐로 푸시됩니다. 이 구성은 각 청크의 크기 제한을 설정합니다. 기본적으로 Google은 Logging API의 쓰기 요청당 5MB라는 권장 청크 크기를 초과하지 않기 위해 청크 제한을 보수적으로 설정합니다. API 요청의 로그 항목은 모든 추가 메타 데이터가 첨부되어 원래 로그 크기보다 5~8배 더 클 수 있습니다. 다음 두 가지 조건 중 하나가 충족되면 버퍼 청크가 플러시됩니다. 1. flush_interval이 시작됩니다. 2. 버퍼 크기가 buffer_chunk_limit에 도달합니다.
flush_interval	문자열	5s	로그 레코드가 들어올 때 다운스트림 구성요소로 빨리 기록될 수 없는 레코드는 청크 큐로 푸시됩니다. 이 구성은 청크 버퍼를 플러시하기 전 대기 시간을 설정합니다. 다음 두 가지 조건 중 하나가 충족되면 버퍼 청크가 플러시됩니다. 1. flush_interval이 시작됩니다. 2. 버퍼 크기가 buffer_chunk_limit에 도달합니다.
disable_retry_limit	부울	false	버퍼 청크의 플러시 실패 시 재시도 횟수를 제한합니다. retry_limit, retry_wait, max_retry_wait에서 자세한 사양을 검토하세요.
retry_limit	정수	3	버퍼 청크가 플러시되지 않으면 fluentd가 기본적으로 나중에 다시 시도합니다. 이 구성은 문제가 있는 버퍼 청크 하나를 삭제하기 전 수행할 재시도 횟수를 설정합니다.
retry_wait	정수	10s	버퍼 청크가 플러시되지 않으면 fluentd가 기본적으로 나중에 다시 시도합니다. 이 구성은 첫 번째 재시도 전 대기 시간(초)을 설정합니다. 이 대기 시간은 retry_ limit 또는 max_retry_wait에 도달할 때까지 재시도할 때마다 두 배씩 증가합니다(20초, 40초,...).
max_retry_wait	정수	300	버퍼 청크가 플러시되지 않으면 fluentd가 기본적으로 나중에 다시 시도합니다. 이 대기 시간은 재시도할 때마다 두 배씩 증가합니다(20초, 40초,...). 이 구성은 최대 대기 시간(초)을 설정합니다. 대기 시간이 이 한계에 도달하면 더 이상 두 배씩 증가하지 않습니다.
num_threads	정수	8	출력 플러그인이 처리할 수 있는 동시 로그 플러시 횟수입니다.
use_grpc	부울	true	Logging API와 통신할 때 REST/JSON 대신 gRPC를 사용할지 여부입니다. gRPC를 사용 설정하면 일반적으로 CPU 사용량이 더 적습니다.
grpc_compression_algorithm	열거형	none	gRPC를 사용하는 경우 사용할 압축 스키마를 설정합니다. none 또는 gzip일 수 있습니다.
partial_success	부울	true	로그 수집에 대한 부분적인 성공을 지원할지 여부입니다. true인 경우 전체 세트에서 유효하지 않은 로그 항목은 삭제되고 유효한 로그 항목은 Logging API로 성공적으로 수집됩니다. false인 경우 유효하지 않은 로그 항목이 포함되어 있으면 전체 세트가 삭제됩니다.
enable_monitoring	부울	true	true로 설정하면 Logging 에이전트가 내부 원격 분석을 내보냅니다. 자세한 내용은 출력 플러그인 원격 분석을 참조하세요.
monitoring_type	문자열	opencensus	모니터링 유형입니다. 지원되는 옵션은 opencensus 및 prometheus입니다. 자세한 내용은 출력 플러그인 원격 분석을 참조하세요.
autoformat_stackdriver_trace	부울	true	true로 설정한 경우 구조화된 페이로드 필드 logging.googleapis.com/trace가 ResourceTrace traceId 형식과 일치하면 trace 형식이 다시 지정됩니다. 자동 형식 지정에 대한 자세한 내용은 이 페이지의 구조화된 페이로드의 특수 필드에서 확인할 수 있습니다.

모니터링 구성

출력 플러그인 원격 분석

enable_monitoring 옵션은 Google Cloud fluentd 출력 플러그인이 내부 원격 분석을 수집하는지 여부를 제어합니다. true로 설정하면 Logging 에이전트가 Cloud Logging으로 전송되도록 요청된 로그 항목의 수와 Cloud Logging에서 성공적으로 수집된 실제 로그 항목 수를 추적합니다. false로 설정하면 출력 플러그인에서 측정항목이 수집되지 않습니다.

monitoring_type 옵션은 에이전트가 이 원격 분석을 노출하는 방식을 제어합니다. 측정항목 목록은 다음을 참조하세요.

prometheus로 설정된 경우 Logging 에이전트가 Prometheus 엔드포인트에서 Prometheus 형식으로 측정항목을 노출합니다(기본적으로 localhost:24231/metrics, 이를 맞춤설정하는 방법에 대한 자세한 내용은 prometheus 및 prometheus_monitor 플러그인 구성 참조). Compute Engine VM에서 이러한 측정항목을 Monitoring API에 기록할 수 있으려면 Monitoring 에이전트를 설치하고 실행해야 합니다.

opencensus(v1.6.25부터 기본값)로 설정된 경우 Logging 에이전트가 고유 상태 측정항목을 Monitoring API에 기록합니다. 이를 위해서는 Monitoring 에이전트가 설치되지 않은 경우에도 roles/monitoring.metricWriter 역할을 Compute Engine 기본 서비스 계정에 부여해야 합니다.

다음 측정항목은 opencensus 모드의 Monitoring 에이전트 및 Logging 에이전트에 의해 Monitoring API에 기록됩니다.

• version 라벨의 agent.googleapis.com/agent/uptime: Logging 에이전트의 업타임입니다.
• response_code 라벨의 agent.googleapis.com/agent/log_entry_count: Logging 에이전트로 기록된 로그 항목 수입니다.
• response_code 라벨의 agent.googleapis.com/agent/log_entry_retry_count: Logging 에이전트로 기록된 로그 항목 수입니다.
• response_code 라벨의 agent.googleapis.com/agent/request_count: Logging 에이전트의 API 요청 수입니다.

이러한 측정항목에 대해서는 에이전트 측정항목 페이지에서 더 자세히 설명합니다.

또한 다음 Prometheus 측정항목이 prometheus 모드의 출력 플러그인에 의해 노출됩니다.

• version 라벨의 uptime: Logging 에이전트의 업타임입니다.
• grpc 및 code 라벨의 stackdriver_successful_requests_count: Logging API에 대한 성공한 요청 수입니다.
• grpc 및 code 라벨의 stackdriver_failed_requests_count: 오류 코드로 분류된 실패한 Logging API 요청 수입니다.
• grpc 및 code 라벨의 stackdriver_ingested_entries_count: Logging API에서 수집된 로그 항목 수입니다.
• grpc 및 code 라벨의 stackdriver_dropped_entries_count: Logging API에서 거부된 로그 항목 수입니다.
• grpc 및 code 라벨의 stackdriver_retried_entries_count: 일시적인 오류로 인해 Google Cloud fluentd 출력 플러그인에서 수집되지 못하고 재시도된 로그 항목 수입니다.

prometheus 및 prometheus_monitor 플러그인 구성

참고: 다음 기본 모니터링 구성은 Linux 운영체제 전용입니다.

• 구성 파일 위치: /etc/google-fluentd/google-fluentd.conf

• 설명: 이 파일에는 prometheus 및 prometheus_monitor 플러그인의 동작을 제어하는 구성 옵션이 포함되어 있습니다. prometheus_monitor 플러그인은 Fluentd의 핵심 인프라를 모니터링합니다. prometheus 플러그인은 Prometheus 형식의 로컬 포트를 통해 위의 prometheus_monitor 플러그인 및 google_cloud 플러그인의 측정항목을 노출합니다. 자세한 내용은 https://docs.fluentd.org/deployment/monitoring-prometheus를 참조하세요.

• 구성 저장소로 이동합니다.

Fluentd를 모니터링하기 위해 기본 제공되는 Prometheus http 측정항목 서버가 기본적으로 사용 설정됩니다. 구성에서 다음 섹션을 삭제하여 이 엔드포인트가 시작되지 않도록 방지할 수 있습니다.

# Prometheus monitoring.
<source>
  @type prometheus
  port 24231
</source>
<source>
  @type prometheus_monitor
</source>

페이로드의 처리

Logging 에이전트의 기본 구성에서 지원되는 대부분의 로그는 로그 파일에서 가져오며, 구조화되지 않은(텍스트) 페이로드로 로그 항목에 수집됩니다.

기본적으로 사용 설정되는 in_forward 입력 플러그인은 유일한 예외로, 구조화된 로그만 허용하고 로그를 구조화된(JSON) 페이로드로 로그 항목에 수집합니다. 자세한 내용은 이 페이지의 in_forward 플러그인을 통해 구조화된(JSON) 로그 레코드 스트리밍을 참조하세요.

로그 줄이 직렬화된 JSON 객체이고 detect_json 옵션이 사용 설정된 경우 출력 플러그인은 로그 항목을 구조화된 (JSON) 페이로드로 변환합니다. 이 옵션은 기본적으로 App Engine 가변형 환경과 Google Kubernetes Engine에서 실행 중인 VM 인스턴스에서 사용 설정됩니다. 이 옵션은 기본적으로 App Engine 표준 환경에서 실행 중인 VM 인스턴스에서 사용 설정되지 않습니다. detect_json 옵션을 사용 설정하여 파싱한 모든 JSON은 항상 jsonPayload로 처리됩니다.

추가 리소스에서 구조화된 로그 데이터 수집을 지원하도록 에이전트 구성을 맞춤설정할 수 있습니다. 자세한 내용은 구조화된(JSON) 로그 레코드를 Cloud Logging으로 스트리밍을 참조하세요.

커스텀 구성된 Logging 에이전트가 스트리밍하는 로그 레코드의 페이로드는 구조화되지 않은 단일 텍스트 메시지(textPayload)이거나 구조화된 JSON 메시지(jsonPayload)일 수 있습니다.

구조화된 페이로드의 특수 필드

Logging 에이전트는 구조화된 로그 레코드를 수신하면 다음 테이블과 일치하는 키를 LogEntry 객체의 해당 필드로 옮깁니다. 그렇지 않으면 키가 LogEntry.jsonPayload 필드의 일부가 됩니다. 이 동작을 통해 Logging API에 기록되는 LogEntry 객체의 특정 필드를 설정할 수 있습니다. 예를 들어 구조화된 로그 레코드에 severity 키가 포함된 경우 Logging 에이전트가 LogEntry.severity 필드를 채웁니다.

JSON 로그 필드	LogEntry 필드	Cloud Logging 에이전트 함수	예시 값
severity	severity	Logging 에이전트는 Logging API가 인식하는 LogSeverity 문자열의 목록을 포함한 다양한 일반적인 심각도 문자열을 일치시키려고 시도합니다.	"severity":"ERROR"
message	textPayload(또는 jsonPayload의 일부)	로그 탐색기의 로그 항목 줄에 표시되는 메시지입니다.	"message":"There was an error in the application." 참고: message가 Logging 에이전트가 다른 특수 목적 필드를 이동하고 남은 유일한 필드이고 detect_json이 사용 설정되어 있지 않은 경우 textPayload로 저장되며, 그렇지 않으면 message는 jsonPayload로 남습니다. detect_json은 Google Kubernetes Engine과 같은 관리형 로깅 환경에 적용되지 않습니다. 로그 항목에 예외 스택 트레이스가 포함된 경우 예외 스택 트레이스는 이 message JSON 로그 필드에 설정되어야 하므로 예외 스택 트레이스를 파싱하고 Error Reporting에 저장할 수 있습니다.
log(기존 Google Kubernetes Engine만 해당)	textPayload	기존 Google Kubernetes Engine에만 적용됩니다. 특수 목적 필드를 이동한 후 log 필드만 남으면 그 필드는 textPayload로 저장됩니다.
httpRequest	httpRequest	LogEntry HttpRequest 필드 형식의 구조화된 레코드	"httpRequest":{"requestMethod":"GET"}
시간 관련 필드	timestamp	자세한 내용은 시간 관련 필드를 참조하세요.	"time":"2020-10-12T07:20:50.52Z"
logging.googleapis.com/insertId	insertId	자세한 내용은 LogEntry 페이지의 insertId를 참조하세요.	"logging.googleapis.com/insertId":"42"
logging.googleapis.com/labels	labels	이 필드의 값은 구조화된 레코드여야 합니다. 자세한 내용은 LogEntry 페이지의 labels를 참조하세요.	"logging.googleapis.com/labels": {"user_label_1":"value_1","user_label_2":"value_2"}
logging.googleapis.com/operation	operation	또한 이 필드의 값은 로그 탐색기에서 관련 로그 항목을 그룹화하는 데 사용됩니다. 자세한 내용은 LogEntry 페이지의 operation를 참조하세요.	"logging.googleapis.com/operation": {"id":"get_data","producer":"github.com/MyProject/MyApplication", "first":"true"}
logging.googleapis.com/sourceLocation	sourceLocation	로그 항목과 연결된 소스 코드 위치 정보(있는 경우) 자세한 내용은 LogEntry 페이지의 LogEntrySourceLocation를 참조하세요.	"logging.googleapis.com/sourceLocation": {"file":"get_data.py","line":"142","function":"getData"}
logging.googleapis.com/spanId	spanId	로그 항목과 연결된 trace 내의 스팬 ID입니다. 자세한 내용은 LogEntry 페이지의 spanId를 참조하세요.	"logging.googleapis.com/spanId":"000000000000004a"
logging.googleapis.com/trace	trace	로그 항목과 연결된 trace의 리소스 이름입니다(있는 경우). 자세한 내용은 LogEntry 페이지의 trace를 참조하세요.	"logging.googleapis.com/trace":"projects/my-projectid/traces/0679686673a" 참고: stdout 또는 stderr에 쓰지 않는 경우 이 필드의 값은 로그 탐색기와 Trace 뷰어가 로그 항목을 그룹화하고 trace와 나란히 표시하는 데 사용할 수 있도록 projects/[PROJECT-ID]/traces/[TRACE-ID] 형식으로 지정되어야 합니다. autoformat_stackdriver_trace가 true이고 [V]가 ResourceTrace traceId의 형식과 일치하는 경우 LogEntry trace 필드는 projects/[PROJECT-ID]/traces/[V]를 값으로 가집니다.
logging.googleapis.com/trace_sampled	traceSampled	이 필드의 값은 true 또는 false이어야 합니다. 자세한 내용은 LogEntry 페이지의 traceSampled를 참조하세요.	"logging.googleapis.com/trace_sampled": false

시간 관련 필드

일반적으로 로그 항목에 대한 시간 관련 정보는 LogEntry 객체의 timestamp 필드에 저장됩니다.

{
insertId: "1ad8d08f-6529-47ea-832e-467f869a2da4"
...
resource: {2}
timestamp: "2023-10-30T16:33:15.505196Z"
}

로그 항목의 소스가 구조화된 데이터인 경우 Logging 에이전트는 다음 규칙을 사용하여 jsonPayload 항목의 필드에서 시간 관련 정보를 검색합니다.

1. UTC 에포크 기준의 부호가 있는 초와 음수가 아닌 초(소수)를 나타내는 seconds 및 nanos 필드가 포함된 JSON 객체인 timestamp 필드를 검색합니다.

   jsonPayload: {
     ...
     "timestamp": {
       "seconds": CURRENT_SECONDS,
       "nanos": CURRENT_NANOS
     }
   }
   

2. 이전 검색이 실패하면 timestampSeconds 및 timestampNanos 필드 쌍을 검색합니다.

   jsonPayload: {
     ...
     "timestampSeconds": CURRENT_SECONDS,
     "timestampNanos": CURRENT_NANOS
   }
   

3. 이전 검색이 실패하면 RFC 3339 형식의 문자열인 time 필드를 검색합니다.

   jsonPayload: {
     ...
     "time": CURRENT_TIME_RFC3339
   }
   

시간 관련 정보가 발견되면 Logging 에이전트가 이 정보를 사용하여 LogEntry.timestamp 값을 설정하고 구조화된 레코드의 정보를 LogEntry.jsonPayload 객체에 복사하지 않습니다.

LogEntry.timestamp 필드 값을 설정하는 데 사용되지 않는 시간 관련 필드는 구조화된 레코드에서 LogEntry.jsonPayload 객체로 복사됩니다. 예를 들어 구조화된 레코드에 timestamp JSON 객체와 time 필드가 포함되어 있으면 timestamp JSON 객체의 데이터를 사용하여 LogEntry.timestamp 필드를 설정합니다. 이 필드는 LogEntry.timestamp 값을 설정하는 데 사용되지 않았으므로 LogEntry.jsonPayload 객체에 time 필드가 포함됩니다.

에이전트 구성 맞춤설정

Logging 에이전트가 기본적으로 스트리밍하는 기본 로그 목록 이외에 입력 구성을 추가하여 Logging 에이전트가 Logging에 추가 로그를 전송하도록 맞춤설정하거나 에이전트 설정을 조정할 수 있습니다.

이 섹션에서 설명하는 구성 정의는 fluent-plugin-google-cloud 출력 플러그인에만 적용되며 로그가 변환되어 Cloud Logging으로 수집되는 방식을 지정합니다.

• 기본 구성 파일 위치:

  • Linux: /etc/google-fluentd/google-fluentd.conf

  • Windows: C:\Program Files (x86)\Stackdriver\LoggingAgent\fluent.conf

    v1-5 이전 버전의 Logging 에이전트를 실행 중인 경우: C:\GoogleStackdriverLoggingAgent\fluent.conf

• 설명: 이 파일에는 fluent-plugin-google-cloud 출력 플러그인 동작을 제어하는 구성 옵션이 포함되어 있습니다.

• 구성 저장소를 검토하세요.

추가 입력을 통한 로그 스트리밍

입력 구성을 추가하여 Logging 에이전트가 Logging에 추가 로그를 전송하도록 맞춤설정할 수 있습니다.

로그 파일을 통해 구조화되지 않은(텍스트) 로그 스트리밍

참고: 이 섹션에는 Linux 명령어 예시가 포함되어 있습니다. Windows를 사용하는 경우 명령어 단계를 해당 환경에 맞게 조정해야 합니다. C:\Program Files (x86)\Stackdriver\LoggingAgent\config.d는 Windows용 서드 파티 구성 디렉터리입니다. 또한 Windows용 구성 파일에서 슬래시(/)를 사용해야 합니다. 슬래시가 필요한 이유에 대한 자세한 내용은 Windows에서는 경로의 와일드 카드 패턴이 작동하지 않음을 참조하세요.

1. Linux 명령어 프롬프트에서 로그 파일을 만듭니다.

   touch /tmp/test-unstructured-log.log
   

2. 추가 구성 디렉터리 /etc/google-fluentd/config.d에 test-unstructured-log.conf로 라벨이 지정된 새 구성 파일을 만듭니다.

   sudo tee /etc/google-fluentd/config.d/test-unstructured-log.conf <<EOF
   <source>
       @type tail
       <parse>
           # 'none' indicates the log is unstructured (text).
           @type none
       </parse>
       # The path of the log file.
       path /tmp/test-unstructured-log.log
       # The path of the position file that records where in the log file
       # we have processed already. This is useful when the agent
       # restarts.
       pos_file /var/lib/google-fluentd/pos/test-unstructured-log.pos
       read_from_head true
       # The log tag for this log input.
       tag unstructured-log
   </source>
   EOF
   

   새 파일을 만드는 대신 기존 구성 파일에 구성 정보를 추가할 수도 있습니다.

3. 에이전트를 다시 시작하여 구성 변경사항을 적용합니다.

   sudo service google-fluentd restart
   

4. 로그 파일에 로그 레코드를 생성합니다.

   echo 'This is a log from the log file at test-unstructured-log.log' >> /tmp/test-unstructured-log.log
   

5. 로그 탐색기에서 수집된 로그 항목을 확인합니다.

   {
     insertId:  "eps2n7g1hq99qp"
     labels: {
     compute.googleapis.com/resource_name:  "add-unstructured-log-resource"
     }
     logName:  "projects/my-sample-project-12345/logs/unstructured-log"
     receiveTimestamp:  "2018-03-21T01:47:11.475065313Z"
     resource: {
     labels: {
       instance_id:  "3914079432219560274"
       project_id:  "my-sample-project-12345"
       zone:  "us-central1-c"
     }
     type:  "gce_instance"
     }
     textPayload:  "This is a log from the log file at test-unstructured-log.log"
     timestamp:  "2018-03-21T01:47:05.051902169Z"
   }
   

로그 파일을 통해 구조화된(JSON) 로그 스트리밍

참고: 이 섹션에는 Linux 명령어 예시가 포함되어 있습니다. Windows를 사용하는 경우 명령어 단계를 해당 환경에 맞게 조정해야 합니다. C:\Program Files (x86)\Stackdriver\LoggingAgent\config.d는 Windows용 서드 파티 구성 디렉터리입니다. 또한 Windows용 구성 파일에서 슬래시(/)를 사용해야 합니다. 슬래시가 필요한 이유에 대한 자세한 내용은 Windows에서는 경로의 와일드 카드 패턴이 작동하지 않음을 참조하세요.

특정 로그 입력에 대한 각 로그 항목의 구조화를 요구하도록 Logging 에이전트를 구성할 수 있습니다. 또한 Logging 에이전트를 맞춤설정하여 로그 파일에서 JSON 형식의 콘텐츠를 수집할 수도 있습니다. 에이전트가 JSON 콘텐츠를 수집하도록 구성되면 입력은 반드시 각 JSON 객체가 줄바꿈되도록 포맷해야 합니다.

    {"name" : "zeeshan", "age" : 28}
    {"name" : "reeba", "age" : 15}

JSON 형식의 콘텐츠를 수집하도록 Logging 에이전트를 구성하려면 다음 안내를 따르세요.

1. Linux 명령어 프롬프트에서 로그 파일을 만듭니다.

   touch /tmp/test-structured-log.log
   

2. 추가 구성 디렉터리 /etc/google-fluentd/config.d에 test-structured-log.conf로 라벨이 지정된 새 구성 파일을 만듭니다.

   sudo tee /etc/google-fluentd/config.d/test-structured-log.conf <<EOF
   <source>
       @type tail
       <parse>
           # 'json' indicates the log is structured (JSON).
           @type json
       </parse>
       # The path of the log file.
       path /tmp/test-structured-log.log
       # The path of the position file that records where in the log file
       # we have processed already. This is useful when the agent
       # restarts.
       pos_file /var/lib/google-fluentd/pos/test-structured-log.pos
       read_from_head true
       # The log tag for this log input.
       tag structured-log
     </source>
     EOF
   

   새 파일을 만드는 대신 기존 구성 파일에 구성 정보를 추가할 수도 있습니다.

3. 에이전트를 다시 시작하여 구성 변경사항을 적용합니다.

   sudo service google-fluentd restart
   

4. 로그 파일에 로그 레코드를 생성합니다.

   echo '{"code": "structured-log-code", "message": "This is a log from the log file at test-structured-log.log"}' >> /tmp/test-structured-log.log
   

5. 로그 탐색기에서 수집된 로그 항목을 확인합니다.

   {
     insertId:  "1m9mtk4g3mwilhp"
     jsonPayload: {
     code:  "structured-log-code"
     message:  "This is a log from the log file at test-structured-log.log"
     }
     labels: {
     compute.googleapis.com/resource_name:  "add-structured-log-resource"
     }
     logName:  "projects/my-sample-project-12345/logs/structured-log"
     receiveTimestamp:  "2018-03-21T01:53:41.118200931Z"
     resource: {
     labels: {
       instance_id:  "5351724540900470204"
       project_id:  "my-sample-project-12345"
       zone:  "us-central1-c"
     }
     type:  "gce_instance"
     }
     timestamp:  "2018-03-21T01:53:39.071920609Z"
   }
   

   로그 탐색기에서 리소스 유형 및 logName structured-log로 필터링합니다.

일반적인 타사 애플리케이션에서 로그 입력 형식을 맞춤설정하는 추가 옵션은 일반적인 로그 형식과 파싱 방법을 참조하세요.

in_forward 플러그인을 통해 구조화된(JSON) 로그 스트리밍

또한 fluentd in_forward 플러그인을 통해 로그를 전송할 수 있습니다. fluentd-cat은 로그를 in_forward 플러그인으로 간편하게 전송하도록 돕는 기본 도구입니다. 이 도구에 대한 자세한 내용은 fluentd 문서를 참조하세요.

fluentd in_forward 플러그인을 통해 로그를 전송하려면 다음 안내를 읽어보세요.

1. Logging 에이전트가 설치된 VM에서 다음 명령어를 실행합니다.

   echo '{"code": "send-log-via-fluent-cat", "message": "This is a log from in_forward plugin."}' | /opt/google-fluentd/embedded/bin/fluent-cat log-via-in-forward-plugin
   

2. 로그 탐색기에서 수집된 로그 항목을 확인합니다.

   {
     insertId:  "1kvvmhsg1ib4689"
     jsonPayload: {
     code:  "send-log-via-fluent-cat"
     message:  "This is a log from in_forward plugin."
     }
     labels: {
     compute.googleapis.com/resource_name:  "add-structured-log-resource"
     }
     logName:  "projects/my-sample-project-12345/logs/log-via-in-forward-plugin"
     receiveTimestamp:  "2018-03-21T02:11:27.981020900Z"
     resource: {
     labels: {
       instance_id:  "5351724540900470204"
       project_id:  "my-sample-project-12345"
       zone:  "us-central1-c"
     }
     type:  "gce_instance"
     }
     timestamp:  "2018-03-21T02:11:22.717692494Z"
   }
   

애플리케이션 코드를 통해 구조화된(JSON) 로그 레코드 스트리밍

다양한 언어의 커넥터를 사용하여 애플리케이션 코드에서 구조화된 로그를 보낼 수 있습니다. 자세한 내용은 fluentd 문서를 참조하세요. 이러한 커넥터는 in_forward 플러그인을 기반으로 빌드됩니다.

로그 항목 라벨 설정

다음 구성 옵션을 사용하면 Cloud Logging에 로그를 수집할 때 LogEntry 라벨 및 MonitoredResource 라벨을 우선 적용할 수 있습니다. 모든 로그 항목은 모니터링되는 리소스와 연결됩니다. 자세한 내용은 Cloud Logging 모니터링 리소스 유형 목록을 참조하세요.

구성 이름	유형	기본값	설명
label_map	hash	nil	JSON 객체로 지정된 label_map은 값이 구조화된 페이로드의 일부가 아니라 라벨로 전송되는 fluentd 필드 이름의 정렬되지 않은 집합입니다. 이 맵의 각 항목은 {field_name:label_name} 쌍입니다. 입력 플러그인에서 파싱한 field_name이 발견되면 해당 label_name을 사용하는 라벨이 로그 항목에 추가됩니다. 필드의 값이 라벨의 값으로 사용됩니다. 이 맵은 라벨 이름을 지정할 때 fluentd 필드 이름의 일부로는 적합하지 않은 문자를 사용할 수 있다는 점 등 유연성이 강화되었습니다. 구조화된 로그 항목의 라벨 설정에서 관련 예시를 참조하세요.
labels	hash	nil	JSON 객체로 지정된 labels는 구성 시 제공되는 커스텀 라벨의 집합입니다. 이 라벨은 메시지마다 추가 환경 정보를 삽입하거나 자동 감지되지 않도록 맞춤설정할 수 있게 해줍니다. 이 맵의 각 항목은 {label_name:label_value} 쌍입니다.

Logging 에이전트 출력 플러그인은 다음과 같은 세 가지 LogEntry 라벨 설정 방법을 지원합니다.

• 구조화된 항목의 특정 라벨을 다른 라벨로 바꿉니다(동적). 자세한 내용은 이 페이지의 구조화된 로그 항목의 라벨 설정을 참조하세요.
• 값이 발생할 때마다 라벨을 붙입니다(정적). 자세한 내용은 이 페이지의 정적으로 라벨 설정을 참조하세요.

구조화된 로그 항목의 라벨 설정

다음과 같은 구조화된 로그 항목 페이로드를 작성했다고 가정해 보겠습니다.

{ "message": "This is a log message", "timestamp": "Aug 10 20:07:00", "env": "production" }

그리고 페이로드 필드 env를 메타 데이터 라벨 environment에 번역하려는 경우를 생각해 봅시다. 이렇게 하려면 기본 구성 파일(Linux의 경우 /etc/google-fluentd/google-fluentd.conf, Windows의 경우 C:\Program Files (x86)\Stackdriver\LoggingAgent\fluent.conf)의 출력 플러그인 구성에 다음을 추가합니다.

# Configure all sources to output to Cloud Logging
<match **>
  @type google_cloud
  label_map {
    "env": "environment"
  }
  ...
</match>

여기서 label_map 설정이 페이로드의 env 라벨을 environment로 교체하므로 결과 로그 항목에는 production 값을 가진 environment 라벨이 있습니다.

정적으로 라벨 설정

이 정보가 페이로드에 없어서 간단히 environment라는 정적 메타데이터 라벨을 추가하려면 기본 구성 파일(Linux의 경우 /etc/google-fluentd/google-fluentd.conf, Windows의 경우 C:\Program Files (x86)\Stackdriver\LoggingAgent\fluent.conf)의 출력 플러그인 구성에 다음을 추가합니다.

# Configure all sources to output to Cloud Logging
<match **>
  @type google_cloud
  labels {
    "environment": "production"
  }
  ...
</match>

이 경우 맵을 사용해 한 라벨을 다른 라벨로 바꾸는 대신 로그 항목의 라벨 지정 유무에 관계없이 labels 설정을 사용하여 로그 항목에 지정된 리터럴 값이 있는 라벨을 연결합니다. 이 방법은 구조화되지 않은 로그를 전송하는 경우에도 사용할 수 있습니다.

labels, label_map, 기타 Logging 에이전트 설정의 구성 방법에 대한 자세한 내용은 이 페이지의 로그 항목 라벨 설정을 참조하세요.

로그 레코드 수정

Fluentd는 로그 항목을 수정하는 데 사용할 수 있는 기본 필터 플러그인을 제공합니다.

가장 일반적으로 사용되는 필터 플러그인은 filter_record_transformer입니다. 이 플러그인을 사용하면 다음을 수행할 수 있습니다.

• 로그 항목에 새 필드 추가
• 로그 항목의 필드 업데이트
• 로그 항목의 필드 삭제

일부 출력 플러그인을 사용하여 로그 항목을 수정할 수도 있습니다. fluent-plugin-record-reformer 출력 플러그인은 로그 태그를 수정할 수 있게 해주는 기능을 제외하고 filter_record_transformer 필터 플러그인과 비슷한 기능을 제공합니다. 이 플러그인을 사용하면 리소스 사용량이 더욱 증가할 수 있습니다. 로그 태그가 업데이트될 때마다 새 태그가 있는 새 로그 항목이 생성되기 때문입니다. 구성에서 tag 필드는 필수입니다. 또한 데드 루프를 입력하지 않도록 이 필드를 수정하는 것이 좋습니다.

fluent-plugin-detect-exceptions 출력 플러그인은 구조화되지 않은 텍스트 로그 레코드 또는 JSON 형식의 로그 레코드에서 여러 줄로 구성된 예외 스택 trace용 로그 스트림을 검색합니다. 여러 로그 항목의 연속 시퀀스가 예외 스택 trace를 형성할 경우 이러한 로그 항목이 하나의 조합된 로그 메시지로 전달됩니다. 그렇지 않은 경우 로그 항목이 있는 그대로 전달됩니다.

기본 이외의 고급 구성 정의

Logging 에이전트의 구성을 기본 구성 이상으로 맞춤설정하려면 이 페이지를 계속 읽어보세요.

버퍼 관련 구성 옵션

다음 구성 옵션을 사용하여 Logging 에이전트의 내부 버퍼링 메커니즘을 조정할 수 있습니다.

구성 이름	유형	기본값	설명
buffer_type	문자열	buf_memory	Logging API에 충분히 빨리 기록할 수 없는 레코드는 버퍼로 푸시됩니다. 이 버퍼는 메모리 또는 실제 파일에 존재할 수 있습니다. 권장 값은 buf_file입니다. 기본 buf_memory는 빠르지만 영구적이지 않습니다. 로그가 손실될 수 있습니다. buffer_type이 buf_file인 경우 buffer_path도 지정해야 합니다.
buffer_path	문자열	사용자 지정	버퍼 청크가 저장되는 경로입니다. buffer_type이 file인 경우 이 매개변수는 필수입니다. 경합 상태를 피하기 위해 이 구성은 고유해야 합니다.
buffer_queue_limit	정수	64	청크 큐의 길이 제한을 지정합니다. 버퍼 큐가 청크 개수에 도달하면 buffer_queue_full_action이 버퍼 동작을 제어합니다. 기본적으로 예외가 발생합니다. 이 옵션과 buffer_chunk_limit을 함께 사용하면 fluentd가 버퍼링에 사용할 수 있는 최대 디스크 공간을 결정합니다.
buffer_queue_full_action	문자열	exception	버퍼 큐가 가득 차면 버퍼 동작을 제어합니다. 가능한 값은 다음과 같습니다. 1. exception: 큐가 가득 차면 BufferQueueLimitError가 발생합니다. BufferQueueLimitError가 처리되는 방식은 입력 플러그인에 따라 다릅니다. 예를 들어 in_tail 입력 플러그인은 새 줄 읽기를 중지하고 in_forward 입력 플러그인은 오류를 반환합니다. 2. block: 이 모드는 버퍼가 가득 찬 상황이 해소될 때까지 입력 플러그인 스레드를 중지합니다. 이 작업은 일괄 처리와 같은 사용 사례에 유용합니다. fluentd는 BufferQueueLimitError를 피하기 위한 차단 작업 사용을 권장하지 않습니다. BufferQueueLimitError가 자주 발생하면 대상 용량이 트래픽을 처리하기에 충분하지 않다는 의미입니다. 3. drop_oldest_chunk: 이 모드는 가장 오래된 청크를 삭제합니다.

프로젝트 관련 구성 옵션과 모니터링 리소스 관련 구성 옵션

다음 구성 옵션을 사용하여 MonitoredResource 객체의 프로젝트와 특정 필드를 직접 지정할 수 있습니다. 이러한 값은 Logging 에이전트가 자동으로 수집하니 직접 지정하지 마세요.

구성 이름	유형	기본값	설명
project_id	문자열	nil	이 구성을 지정하면 Logging 에이전트가 실행되는 기본 Google Cloud 또는 AWS 프로젝트를 식별해주는 project_id가 재정의됩니다.
zone	문자열	nil	이 구성을 지정하면 영역이 재정의됩니다.
vm_id	문자열	nil	이 구성을 지정하면 VM ID가 재정의됩니다.
vm_name	문자열	nil	이 구성을 지정하면 VM 이름이 재정의됩니다.

기타 출력 플러그인 구성 옵션

구성 이름	유형	기본값	설명
detect_json^1	부울	false	로그 레코드가 파싱이 필요한 JSON 콘텐츠가 있는 텍스트 로그 항목인지 여부를 감지입니다. 이 옵션이 true이고 구조화되지 않은 텍스트 로그 항목이 JSON 형식으로 감지되면 파싱되어 구조화된(JSON) 페이로드로 전송됩니다.
coerce_to_utf8	부울	true	사용자 로그에 UTF-8이 아닌 문자를 허용할지 여부를 나타냅니다. true로 설정하면 UTF-8이 아닌 모든 문자가 non_utf8_replacement_string으로 지정된 문자열로 바뀝니다. false로 설정하면 UTF-8이 아닌 문자가 있을 경우 플러그인에서 오류가 트리거됩니다.
require_valid_tags	부울	false	유효하지 않은 태그가 있는 로그 항목을 거부할지 여부입니다. 이 옵션을 false로 설정하면 문자열이 아닌 모든 태그가 문자열로 변환되고 UTF-8이 아닌 문자나 기타 유효하지 않은 문자가 모두 정리되면서 태그가 유효해집니다.
non_utf8_replacement_string	문자열	""(공백)	coerce_to_utf8을 true로 설정하면 UTF-8이 아닌 모든 문자가 여기에 지정된 문자열로 바뀝니다.

¹이 기능은 기본적으로 App Engine 가변형 환경과 Google Kubernetes Engine에서 실행 중인 VM 인스턴스에서 사용 설정됩니다.

맞춤설정한 에이전트 구성 적용

Logging 에이전트를 맞춤설정하면 사용자가 직접 fluentd 구성 파일을 추가할 수 있습니다.

Linux 인스턴스

1. 구성 파일을 다음 디렉터리에 복사합니다.

   /etc/google-fluentd/config.d/
   

   Logging 에이전트 설치 스크립트는 이 디렉터리를 기본 포괄 구성 파일로 채웁니다. 자세한 내용은 Logging 에이전트 소스 코드 가져오기를 참조하세요.

2. (선택사항) 다음 명령어를 실행하여 구성 변경을 검증합니다.

   sudo service google-fluentd configtest
   

3. 다음 명령어를 실행하여 에이전트를 다시 시작합니다.

   sudo service google-fluentd force-reload
   

Windows 인스턴스

참고: v1-5 이전 버전의 에이전트를 실행할 경우에는 사용자가 만든 구성 파일을 추가할 수 없습니다. 최신 에이전트로 업그레이드하세요.

1. 구성 파일을 에이전트 설치 디렉터리의 config.d라는 하위 디렉터리에 복사합니다. 기본 설치 디렉터리를 사용한 경우 이 디렉터리는 다음과 같습니다.

   C:\Program Files (x86)\Stackdriver\LoggingAgent\config.d\
   

2. 명령줄 셸에서 다음 명령어를 실행하여 에이전트를 다시 시작합니다.

   net stop  StackdriverLogging
   net start StackdriverLogging
   

fluentd 구성 파일에 대한 자세한 내용은 fluentd의 성 파일 구문 문서를 참조하세요.