업스트림 Fluentd의 구성 호환성

Logging 에이전트에서 업스트림 Fluentd로 마이그레이션할 때 시작 오류를 방지하기 위해 해결 방법이 필요한 구성 비호환성이 발생할 수 있습니다. 이 문서에서는 구성 비호환성을 해결하는 방법을 설명합니다.

기존 Logging 에이전트와 업스트림 Fluentd 간의 구문 변경사항

기존 Logging 에이전트는 Fluentd v0.12 구문을 사용하는 반면 업스트림 Fluentd는 v1 표준을 채택합니다. 이 전환에는 다양한 매개변수의 지원 중단과 핵심 기능을 처리하기 위한 새로운 중첩 지시문의 도입이 포함되며, 이전에 사용된 플랫 구성 구조를 대체합니다.

시작 실패를 방지하고 로그가 올바르게 처리되도록 하려면 지원 중단된 매개변수를 삭제하거나 대체해야 합니다. 다음 섹션에서는 지원 중단된 매개변수를 업데이트하는 방법을 설명합니다.

출력 플러그인 구성

오류를 방지하기 위해 출력 플러그인 구성에서 업데이트해야 하는 매개변수는 다음 표에 나와 있습니다.

기존 Logging 에이전트 문법 업스트림 Fluentd 구문 참고
해당 사항 없음 <buffer> Fluentd 출력 플러그인은 <match> 섹션 아래에 <buffer> 섹션을 지원하여 이벤트 버퍼링을 구성합니다. 자세한 내용은 Fluentd 문서의 Config: Buffer Section을 참고하세요.
buffer_type @type
buffer_path path
buffer_chunk_limit chunk_limit_size
disable_retry_limit retry_forever
retry_limit retry_max_times
max_retry_wait retry_max_interval
num_threads flush_thread_count
partial_success 해당 사항 없음 이 매개변수를 삭제합니다. 업스트림 Fluentd는 기본적으로 부분 성공을 영구적으로 사용 설정하여 잘못된 행만 삭제합니다.

다음은 기존 Logging 에이전트의 google-cloud 출력 플러그인 구성의 예시입니다.

<match **>
  @type google_cloud
  buffer_type file
  buffer_path /var/log/google-fluentd/buffers
  buffer_chunk_limit 512KB
  flush_interval 5s
  disable_retry_limit false
  retry_limit 3
  retry_wait 10
  max_retry_wait 300
  num_threads 8
</match>

업데이트를 실행한 후 구성은 다음과 같습니다.

<match **>
  @type google_cloud
  <buffer>
    @type file
    path /var/log/google-fluentd/buffers
    chunk_limit 512KB
    flush_interval 5s
    retry_forever false
    retry_max_times 3
    retry_wait 10
    retry_max_interval 300
    flush_thread_count 8
  </buffer>
</match>

입력 플러그인 구성

오류를 방지하기 위해 입력 플러그인 구성에서 업데이트해야 하는 매개변수는 다음 표에 나와 있습니다.

기존 Logging 에이전트 문법 업스트림 Fluentd 구문 참고
format <parse> 자세한 내용은 구성: 파싱 섹션 Fluentd 문서를 참고하세요.
protocol_type <transport> syslog 전송의 프로토콜(udp, tcp, 또는 tls)을 나타냅니다.
auto_typecast json 파싱 플러그인 내에서 사용되는 경우 이 매개변수를 삭제합니다.

다음은 기존 Logging 에이전트의 입력 플러그인 구성의 예시입니다.

<source>
    @type tail
    path /var/log/my-app.log
    format json
</source>

업데이트를 실행한 후 구성은 다음과 같습니다.

<source>
    @type tail
    path /var/log/my-app.log
    <parse>
      @type json
    </parse>
</source>

Ruby Time 객체 직렬화

업스트림 Fluentd에는 record_transformer와 같은 <record> 필터 내에서 사용되는 원시 Ruby Time 객체에 대한 명시적 캐스팅이 필요합니다. 명시적 캐스팅이 없으면 이러한 객체로 인해 버퍼 플러시 중에 심각한 직렬화 오류가 발생합니다.

구성에서 enable_ruby true와 함께 ${time}를 사용하는 경우 객체를 기본 유형, 정수 또는 문자열로 명시적으로 변환해야 합니다.

다음은 기존 Logging 에이전트의 필터 플러그인 구성의 예시입니다.

<filter foo.bar>
  @type record_transformer
   enable_ruby true
  <record>
    raw_timestamp ${time}
  </record>
</filter>

업데이트를 실행한 후 구성은 다음과 같습니다.

<filter foo.bar>
  @type record_transformer
   enable_ruby true
  <record>
    raw_timestamp ${time.to_i}
  </record>
</filter>

gRPC 전송 및 압축 기본값

google_cloud 출력 플러그인을 사용하면 REST/JSON 대신 gRPC를 사용하여 Cloud Logging API와 통신할지 여부를 구성할 수 있습니다.

성능 향상을 위해 gRPC 전송을 사용 설정하고 grpc_compression_algorithm gzip를 구성하는 것이 좋습니다. 이 조합은 특히 상당한 로그 볼륨을 처리할 때 네트워크 오버헤드와 CPU 사용량을 최소화합니다.

이러한 최적화를 구현하려면 다음 구성을 사용하세요.

<match **>
  @type google_cloud
  use_grpc true
  grpc_compression_algorithm gzip
</match>

또한 gRPC는 포트 443의 HTTP/2 스트리밍을 사용하므로 네트워크 인프라에서 gRPC/HTTP/2 트래픽을 허용해야 합니다. gRPC가 제한된 환경에서는 표준 HTTP/REST 통신으로 되돌리도록 use_grpc false를 명시적으로 정의해야 합니다.

RabbitMQ 정규 표현식 패턴

RabbitMQ 로그 수집을 위해 기존 Logging 에이전트에서 사용되는 정규 표현식 패턴은 최신 RabbitMQ 버전의 출력 형식과 호환되지 않는 경우가 많습니다. 이러한 불일치로 인해 수집 프로세스 중에 로그가 잘못 처리되거나 자동으로 삭제될 수 있습니다.

최신 RabbitMQ 로그는 YYYY-MM-DD HH:MM:SS.L와 같은 타임스탬프에 밀리초 정밀도를 통합하고 기존 정규 표현식이 일치하지 않는 [info] <0.213.0>와 같은 특정 심각도 및 PID 마커를 제공합니다.

Fluentd 에이전트가 RabbitMQ 로그를 수집하도록 구성된 경우 현재 로그 형식을 올바르게 처리하도록 <parser> 섹션을 업데이트해야 합니다.

다음은 기존 Logging 에이전트의 RabbitMQ 입력 플러그인 구성의 예시입니다.

<source>
  @type tail
  path /var/log/rabbitmq/*.log
  pos_file /var/lib/google-fluentd/pos/rabbitmq.pos
  tag rabbitmq
  format multiline
  format_firstline /^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}/
  format1 /^(?<time>\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}) \[(?<severity>\w+)\] (?<message>.*)/
  time_format %Y-%m-%d %H:%M:%S
</source>

업데이트를 실행한 후 구성은 다음과 같습니다.

<source>
  @type tail
  path /var/log/rabbitmq/*.log
  pos_file /var/log/fluentd/pos/rabbitmq.pos
  read_from_head true
  tag rabbitmq
  <parse>
    @type multiline
    format_firstline /^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}\.\d{3}/
    format1 /^(?<time>\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}\.\d{3}) \[(?<severity>[^\]]+)\] <(?<pid>[^>]+)> (?m:(?<message>.*))$/
    time_format %Y-%m-%d %H:%M:%S.%L
  </parse>
</source>