기존 Logging 에이전트에서 업스트림 Fluentd로 마이그레이션

기존 Logging 에이전트를 사용하고 구성이 고도로 맞춤설정된 경우 오픈소스 Fluentd로 마이그레이션하는 것이 좋습니다. Cloud Logging에서 로그 수집을 중단하지 않고 Logging 에이전트 환경의 동작을 유지하도록 Fluentd를 구성할 수 있습니다. 이 문서에서는 마이그레이션 프로세스를 설명합니다.

기능 비교

다음 표에서는 기존 Logging 에이전트와 업스트림 Fluentd 간의 주요 기능 패리티를 비교합니다.

기능	기존 Logging 에이전트	업스트림 Fluentd
Cloud Logging에 로그 수집	예	예
표준 시스템 로그 (syslog)	예	예
사전 구성된 서드 파티 애플리케이션 입력	예	예 ^†
구조화된 (JSON) 및 구조화되지 않은 (텍스트) 로그 처리	예	예
여러 줄 예외 병합	예	예
Google Cloud 메타데이터 보강	예	예
Kubernetes 메타데이터 보강	예	예
고유 로그 항목 ID	예	예
로그 필드 변환	예	예
심각도 매핑	예	예
인증 (ADC 및 서비스 계정 키)	예	예
REST 및 gRPC 전송 프로토콜	예	예
모니터링 통합	예	예

^†  google-fluentd-catch-all-config 패키지는 업스트림 Fluentd 및 플러그인의 표준 설치에 포함되지 않지만 이 가이드에 자세히 설명된 이전 단계를 따라 사전 구성된 입력 기능을 유지할 수 있습니다.

시작하기 전에

마이그레이션을 시작하기 전에 다음 사항을 확인하세요.

• Google Cloud 프로젝트의 지원되는 VM 인스턴스
• Cloud Logging과의 통신을 승인하는 VM 인스턴스의 사용자 인증 정보. 대개 Compute Engine VM 인스턴스에는 기본적으로 올바른 사용자 인증 정보가 있습니다. 적절한 사용자 인증 정보가 있는지 확인하려면 Logging 에이전트 승인 절차를 실행하세요.

Fluentd로 마이그레이션

이 섹션에서는 기존 Logging 에이전트에서 제공하는 주요 기능을 유지하면서 업스트림 Fluentd 버전으로 마이그레이션하는 단계를 간략하게 설명합니다.

설정을 이전하려면 다음 단계를 완료하세요.

1. 기존 Logging 에이전트 종료
2. 안정적인 버전의 fluentd-package 설치
3. 플랫폼 플러그인 Google Cloud 설치
4. 입력 플러그인 구성 파일 마이그레이션
5. syslog 구성 업데이트
6. Fluentd 구성 파일 업데이트
7. Fluentd 에이전트가 올바르게 실행되고 있는지 확인
8. 기존 Logging 에이전트 제거

참고: 이 섹션에는 Linux 명령어 예시가 포함되어 있습니다. Windows를 사용하는 경우 명령어 단계를 해당 환경에 맞게 조정합니다.

기존 Logging 에이전트 종료

업스트림 Fluentd 에이전트를 설치하기 전에 충돌을 방지하기 위해 기존 Logging 에이전트를 중지해야 합니다. 이전 중에 대기 중인 로그가 손실되지 않도록 종료 시 버퍼링된 모든 로그를 플러시해야 합니다.

기존 Logging 에이전트를 정상적으로 종료하려면 다음을 실행하세요.

1. SSH 또는 유사한 도구를 사용하여 VM 인스턴스와의 터미널 연결을 열고 sudo 액세스 권한이 있는지 확인합니다.

2. 기존 Logging 에이전트를 종료하기 전에 버퍼링된 로그를 플러시하려면 flush_at_shutdown 옵션을 사용 설정하세요.

   1. flush_at_shutdown 플래그를 true로 설정하도록 /etc/google-fluentd/google-fluentd.conf 파일을 업데이트합니다.

      # Configure the agent to flush all buffer chunks on shutdown
      <match **>
        @type google_cloud
        flush_at_shutdown true
      </match>
      

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

      sudo service google-fluentd restart
      

3. 기존 Logging 에이전트를 중지합니다.

   sudo service google-fluentd stop
   

안정적인 버전의 fluentd-package 설치

VM 인스턴스에 안정적인 Fluentd (fluentd-package) 배포를 설치합니다. 자세한 내용은 Fluentd fluent-package 설치 문서를 참고하세요.

Google Cloud 플랫폼 플러그인 설치

Fluentd가 Cloud Logging과 상호작용하고 특정 로그 형식을 처리하도록 하려면 다음 플러그인을 설치하세요.

1. 아직 설치하지 않았다면 확장 프로그램 컴파일을 위한 빌드 도구를 설치합니다.

   Debian 또는 Ubuntu

   Debian 또는 Ubuntu에서 다음 명령어를 실행합니다.

   sudo apt-get update
   sudo apt-get install -y build-essential
   

   CentOS 또는 RHEL

   CentOS 또는 RHEL에서 다음 명령어를 실행합니다.

   sudo yum update
   sudo yum groupinstall -y "Development Tools"
   

2. fluent-plugin-google-cloud 플러그인을 설치합니다.

   sudo fluent-gem install fluent-plugin-google-cloud
   

3. fluent-plugin-detect-exceptions 플러그인을 설치합니다.

   sudo fluent-gem install fluent-plugin-detect-exceptions
   

4. 선택사항: 기존 Logging 에이전트 배포가 Kubernetes 클러스터 내에서 실행되는 애플리케이션의 로그를 수집하는 경우 fluent-plugin-kubernetes_metadata_filter 플러그인을 설치합니다.

   sudo fluent-gem install fluent-plugin-kubernetes_metadata_filter
   

5. 선택사항: 기존 Logging 에이전트가 Prometheus 형식으로 측정항목을 수집하고 노출하는 경우 다음 gem을 설치합니다.

   sudo fluent-gem install prometheus-client -v 0.9.0
   sudo fluent-gem install fluent-plugin-prometheus -v 1.4.0
   

   경고: 0.10.0 이상의 prometheus-client 버전은 호환되지 않으므로 시작 중에 Fluentd가 비정상 종료됩니다.

입력 플러그인 구성 파일 이전

Fluentd 설치의 기존 구성 및 위치 파일을 이전하려면 다음 단계를 완료하세요.

1. Fluentd 구성 및 위치 파일의 디렉터리를 만듭니다.

   # Create the destination directory for Fluentd configuration files
   sudo mkdir -p /etc/fluent/config.d
   
   # Create the destination directory for position files
   sudo mkdir -p /var/lib/fluent/pos
   

2. google-fluentd 구성 파일을 Fluentd의 구성 디렉터리에 복사합니다.

   sudo cp /etc/google-fluentd/config.d/* /etc/fluent/config.d/
   

3. google-fluentd에서 사용하는 모든 위치 (.pos) 파일을 Fluentd의 위치 파일 디렉터리에 복사합니다.

   sudo cp /var/lib/google-fluentd/pos/*.pos /var/lib/fluent/pos/
   

   위치 파일은 로그 파일의 읽기 위치를 추적하는 데 사용됩니다. 이를 이전하면 Fluentd가 google-fluentd가 사용하던 동일한 지점에서 시작할 수 있습니다.

4. 새 Fluentd 구성 파일에서 pos_file 경로를 업데이트하여 새 위치 파일 디렉터리를 가리키도록 합니다.

   sudo sed -i 's#/var/lib/google-fluentd#/var/lib/fluent#g' /etc/fluent/config.d/*.conf
   

5. Fluentd 서비스 사용자(_fluentd)에 /var/lib/fluent/ 디렉터리에 대한 읽기 및 쓰기 액세스 권한을 부여합니다.

   sudo chown -R _fluentd:_fluentd /var/lib/fluent/
   

6. _fluentd 사용자에게 syslog 파일에 대한 읽기 액세스 권한을 부여합니다.

   sudo usermod -a -G adm _fluentd
   

syslog 구성 업데이트

업스트림 Fluentd는 권한이 없는 사용자로 실행되므로 1024 미만의 권한 포트에 바인딩할 수 없습니다. 기존 Logging 에이전트 설정에 port 514에서 @type syslog를 사용하여 네트워크 기반 syslog 수집이 포함된 경우 구성을 조정해야 합니다.

포트 구성을 업데이트하려면 다음 단계를 따르세요.

1. /etc/fluent/config.d/syslog_endpoint.conf 파일의 전체 콘텐츠를 다음 구성으로 바꿉니다.

   sudo tee /etc/fluent/config.d/syslog_endpoint.conf > /dev/null <<EOF
   <source>
     @type syslog
     port 5140
     <transport tcp>
     </transport>
     bind 127.0.0.1
     tag syslog
   </source>
   EOF
   

2. /etc/rsyslog.d/40-fluentd-forward.conf 파일을 만들어 syslog 메시지를 새 Fluentd 포트로 전달합니다.

   sudo tee /etc/rsyslog.d/40-fluentd-forward.conf > /dev/null <<EOF
   # Forward all syslog messages to Fluentd on localhost:5140 via TCP
   *.* @@127.0.0.1:5140
   EOF
   

3. rsyslog 서비스를 다시 시작하여 변경사항을 적용합니다.

   sudo systemctl restart rsyslog.service
   

기본 Fluentd 구성 파일 업데이트

에이전트의 구성 파일(google-fluentd.conf)에서 /etc/fluent/fluentd.conf에 있는 기본 Fluentd 구성 파일로 설정을 복제하여 업스트림 Fluentd 에이전트를 구성합니다.

참고: Google 플러그인을 설치하면 Fluentd의 업스트림 버전이 기존 Logging 에이전트의 모든 기능을 지원합니다. 자세한 내용은 Logging 에이전트 구성을 참고하세요.

업스트림 Fluentd 에이전트를 구성하려면 다음 단계를 완료하세요.

1. google-fluentd.conf 파일의 전체 콘텐츠를 복사하여 기본 업스트림 Fluentd 구성 파일을 덮어씁니다.

   sudo cp /etc/google-fluentd/google-fluentd.conf /etc/fluent/fluentd.conf
   

2. Fluentd 구성 파일의 buffer_path을 새 Fluentd 디렉터리를 가리키도록 업데이트합니다.

   sudo sed -i 's#/var/log/google-fluentd#/var/log/fluent#g' /etc/fluent/fluentd.conf
   

3. fluentd.conf 파일을 검사하여 구성에 다음이 포함되어 있는지 확인합니다.

   • @include config.d/*.conf는 모든 입력 플러그인 구성을 가져오기 위해 존재합니다.
   • <match **> @type google_cloud 블록은 Cloud Logging으로 로그를 스트리밍하도록 구성되어 있습니다.
   • 이제 출력 플러그인 내의 buffer_path가 /var/lib/fluent/를 가리킵니다.
   • 입력 플러그인 내의 모든 pos_file 지시문은 /var/lib/fluent/을 가리킵니다.

4. 드라이 런을 실행하여 Fluentd 구성을 확인합니다.

   sudo fluentd -c /etc/fluent/fluentd.conf --dry-run
   

   결과 출력에서 error 또는 warn 알림을 확인합니다. 계속 진행하려면 확인된 문제를 해결해야 합니다. 구문 변경사항에 관한 자세한 내용은 업스트림 Fluentd의 구성 호환성을 참고하세요.

5. Fluentd 에이전트를 다시 시작합니다.

   sudo service fluentd restart
   

Fluentd 에이전트가 올바르게 실행되고 있는지 확인

Fluentd를 시작한 후 로그가 Cloud Logging으로 전송되는지 확인합니다.

1. Fluentd가 오류 없이 실행되고 있는지 확인합니다.

   $ sudo service fluentd status
   

   서비스 상태가 활성 (실행 중)이어야 합니다.

2. Fluentd 로그를 확인하여 오류나 경고가 없는지 확인합니다.

   sudo tail -n 100 /var/log/fluent/fluentd.log | grep -iE "error|warn|failed|exception" || true
   

   오류나 경고가 표시되지 않아야 합니다.

3. Cloud Logging을 확인하여 VM 인스턴스에서 로그를 수신하고 있는지 확인합니다. 로그를 보는 방법에 대한 자세한 내용은 로그 탐색기 사용을 참고하세요.

기존 Logging 에이전트 삭제

새 Fluentd가 Cloud Logging에 로그를 성공적으로 전송하는지 확인한 후에만 기존 Logging 에이전트와 구성 파일을 삭제하세요.

Debian 또는 Ubuntu

  sudo apt-get remove --purge google-fluentd

CentOS 또는 RHEL

  sudo yum remove google-fluentd