에이전트 문제해결

이 페이지는 Logging 에이전트 설치 또는 상호작용 시 공통적으로 발견되는 문제를 해결하기 위한 지침을 제공합니다.

체크리스트

Logging 에이전트를 설치하거나 사용하는 데 문제가 있으면 다음 사항을 확인합니다.

  • Linux 설치 명령어에서 오류가 발생하면 설치 명령어의 프리픽스가 sudo인지 확인합니다.

  • 에이전트 서비스가 VM 인스턴스에서 실행되는지 확인합니다.

    • Windows VM의 경우 다음 PowerShell 명령어를 사용합니다.

      Get-Service -Name StackdriverLogging
      

      Stackdriver Monitoring이라는 서비스를 검색합니다. 에이전트가 실행되고 있지 않으면 에이전트를 다시 시작해야 할 수도 있습니다.

    • Linux VM의 경우 다음 명령어를 사용합니다.

      sudo service google-fluentd status
      

      에이전트가 실행되고 있지 않으면 다음 명령어를 사용하여 다시 시작해야 할 수도 있습니다.

      sudo service google-fluentd restart
      

      다시 시작할 수 없고 로그 출력에 '메타데이터를 통해 사용 중지됨'이 표시되는 경우 기본적으로 Logging 에이전트가 중지된 Google Cloud Marketplace에서 이미지가 실행되고 있을 가능성이 있습니다. 이 문제는 google-logging-enable 인스턴스 메타데이터 키(값 0)로 제어됩니다. 에이전트를 다시 사용 설정하려면 이 키를 삭제하거나 값을 1로 설정합니다(인스턴스 메타데이터 설정 참조).

      에이전트가 메타데이터를 통해 사용 중지되지 않았으면 에이전트를 다시 설치합니다. 다음 섹션인 에이전트 다시 설치하기를 참조하세요.

  • 에이전트가 로그에 오류 메시지를 작성했는지 확인합니다.

    • Windows에서 Logging 에이전트(v1-9 버전 기준)는 로그를 C:\Program Files (x86)\Stackdriver\LoggingAgent\fluentd.log에 저장합니다.

      이전 버전의 에이전트 로그를 가져올 수 있는 방법은 없습니다.

    • Linux에서 Logging 에이전트는 fluentd 패키지이고 메시지를 /var/log/google-fluentd/google-fluentd.log에 로깅합니다.

      • HTTP 429 오류가 발생하는 경우 Logging API 할당량을 초과했을 수 있습니다. Cloud Console에서 API 및 서비스 > 대시보드를 선택하여 사용 가능한 할당량을 확인할 수 있습니다. Logging API를 선택합니다.

      • API 액세스 또는 승인 관련 문제가 발생하면 Compute Engine 사용자 인증 정보 확인하기를 참조하세요.

  • 에이전트가 정상적으로 실행 중인 것 같지만 데이터가 수신되지 않는 경우에는 에이전트가 데이터를 올바른 프로젝트에 전송하고 있는지 확인해야 합니다. 다음 섹션인 Compute Engine 사용자 인증 정보 확인하기를 참조하세요.

에이전트 설치 확인

설치가 성공적인지 확인하려면 로그 뷰어에서 에이전트의 테스트 로그 항목을 찾아보세요.

로그 뷰어로 이동

  1. 페이지 상단에서 사용자의 VM 인스턴스가 포함된 프로젝트를 선택합니다.

    • Compute Engine VM 인스턴스의 경우 VM 인스턴스가 포함된 프로젝트를 선택합니다.
    • Amazon EC2 VM 인스턴스의 경우 AWS 계정을 작업공간에 연결할 때 Cloud Monitoring에서 만드는 AWS LINK 프로젝트를 선택합니다.
    • Compute Engine VM 인스턴스가 없는 작업공간 프로젝트를 선택하지 마세요.
  2. 창 탭에서 VM 인스턴스의 리소스를 선택합니다.

    • Compute Engine의 경우 GCE VM 인스턴스를 선택합니다.
    • Amazon EC2의 경우, AWS EC2 인스턴스를 선택합니다.
    • syslog(Linux), fluent.info(Windows), 모든 로그 중에서 하나를 선택합니다.

'gRPC를 Logging API로 성공적으로 전송'이라는 로그 항목이 표시되면 에이전트 설치가 완료된 것입니다. 이 메시지는 에이전트가 설치될 때 생성되고 에이전트를 다시 시작할 때마다 생성됩니다.

로그 뷰어에 관한 자세한 내용은 로그 보기를 참조하세요.

에이전트 테스트

에이전트의 작동 여부가 의심스러울 경우 실행되고 있는지 확인하여 Logging에 테스트 메시지를 전송해 보세요.

Linux 인스턴스

아래의 절차는 Linux를 실행하는 Compute Engine과 Amazon EC2 VM 인스턴스 모두에서 작동합니다.

  1. VM 인스턴스에서 다음 명령어를 실행하여 Logging 에이전트가 실행되는지 확인합니다.

    ps ax | grep fluentd
    

    다음과 비슷한 출력이 표시됩니다.

     2284 ?        Sl     0:00 /opt/google-fluentd/embedded/bin/ruby /usr/sbin/google-fluentd [...]
     2287 ?        Sl    42:44 /opt/google-fluentd/embedded/bin/ruby /usr/sbin/google-fluentd [...]
    
  2. VM 인스턴스에서 다음 명령어를 실행하여 테스트 로그 메시지를 전송합니다.

    logger "Some test message"
    

Windows 인스턴스

Logging 에이전트의 Windows 서비스 이름은 다음 두 가지입니다.

  • 버전 v1-5 이상의 경우 StackdriverLogging
  • 그 이전 버전의 경우 fluentdwinsvc

둘 중 한 에이전트 서비스를 실행하고 있을 것입니다. VM 인스턴스에서 PowerShell을 사용하여 다음 명령어를 실행합니다.

  1. 두 서비스의 상태를 요청합니다. 어떤 서비스가 실행될지 알고 있다면 그 서비스의 이름을 사용하면 됩니다.

    Get-Service StackdriverLogging,fluentdwinsvc
    
  2. 서비스가 실행되고 있지 않으면 오류 메시지가 표시됩니다. 서비스가 실행되고 있으면 다음과 같은 출력이 표시됩니다.

    Status    Name                DisplayName
    ------    ----                -----------
    Running  StackdriverLogging   Cloud Logging
    
  3. 두 서비스를 모두 쿼리할 경우 오류 메시지 하나와 Running 상태 하나가 표시됩니다.

    • Running 상태가 표시되지 않는다면 Logging 에이전트가 실행되고 있지 않은 것입니다.
    • StackdriverLogging이 실행되고 있는 것이 보인다면 에이전트의 최신 버전을 실행하고 있는 것입니다. 구체적인 버전을 확인하려면 버전 가져오기를 참조하세요.
    • fluentdwinsvc가 실행되고 있음을 확인하면 에이전트를 최신 버전으로 업그레이드해야 합니다.
  4. 관리자 권한 필요: 에이전트의 특정 버전이 실행되고 있다면 다음과 같은 PowerShell 명령어를 실행하여 테스트 로그 메시지를 전송합니다.

    New-EventLog   -LogName Application -Source "Test Source"
    Write-EventLog -LogName Application -Source "Test Source" -EntryType Information -EventID 1 -Message "Testing 123 Testing."
    

테스트 메시지 찾기

테스트 메시지를 전송한 후 로그 뷰어에서 해당 테스트 메시지를 찾으세요.

로그 뷰어로 이동

  1. 페이지 상단에서 사용자의 VM 인스턴스가 포함된 프로젝트를 선택합니다.

    • Compute Engine VM 인스턴스의 경우 VM 인스턴스가 포함된 프로젝트를 선택합니다.
    • Amazon EC2 VM 인스턴스의 경우 AWS 계정을 작업공간에 연결할 때 Cloud Monitoring에서 만드는 AWS LINK 프로젝트를 선택합니다.
    • Compute Engine VM 인스턴스가 없는 작업공간 프로젝트를 선택하지 마세요.
  2. 창 탭에서 VM 인스턴스의 리소스를 선택합니다.

    • Compute Engine의 경우 GCE VM 인스턴스를 선택합니다.
    • Amazon EC2의 경우, AWS EC2 인스턴스를 선택합니다.
    • syslog(Linux), fluent.info(Windows), 모든 로그 중에서 하나를 선택합니다.
  3. 테스트 메시지가 포함된 로그 항목이 표시됩니다. 그러면 Logging 에이전트가 올바르게 작동하는 것입니다.

Compute Engine 사용자 인증 정보 확인하기

Compute Engine VM 인스턴스가 비공개 키 사용자 인증 정보 없이 에이전트를 실행하는 경우 인스턴스의 액세스 범위가 적절해야 하고 인스턴스가 사용하는 서비스 계정 ID에 적절한 Cloud IAM 권한이 있어야 합니다.

VM 인스턴스를 만들 때 기본 범위와 서비스 계정 설정으로도 충분히 에이전트를 실행할 수 있습니다. 인스턴스가 아주 오래되었거나 기본 설정을 변경한 인스턴스의 경우에는 사용자 인증 정보가 적절하지 않을 수 있습니다.

액세스 범위 확인하기

액세스 범위를 확인하려면 다음 안내를 따르세요.

  1. Compute Engine > VM 인스턴스 페이지를 엽니다.

    인스턴스 페이지 열기

  2. VM 인스턴스의 이름을 클릭합니다. 인스턴스의 세부정보 페이지가 나타납니다.

  3. Cloud API 액세스 범위 섹션에서 세부정보를 클릭하여 API 목록을 확인합니다. 다음 항목을 찾습니다.

    1. '이 인스턴스에 모든 Google Cloud 서비스에 대한 전체 API 액세스 권한이 있습니다'가 표시되면 액세스 범위가 적절한 것입니다.
    2. 쓰기 전용 또는 전체 권한이 Cloud Logging API 옆에 표시되면 인스턴스의 액세스 범위가 Cloud Logging 에이전트에 적합한 것입니다.
    3. 쓰기 전용 또는 전체 권한이 Cloud Monitoring API 옆에 표시되면 인스턴스의 액세스 범위가 Cloud Monitoring 에이전트에 적합한 것입니다.

문제 해결

Compute Engine 인스턴스의 액세스 범위가 적절하지 않으면 인스턴스에 필요한 액세스 범위를 추가합니다.

다음 표에서는 Logging 및 Monitoring 에이전트와 관련된 범위를 보여줍니다.

액세스 범위 에이전트 권한
https://www.googleapis.com/auth/logging.write Logging 에이전트에 적절함
https://www.googleapis.com/auth/monitoring.write Monitoring 에이전트에 적절함

기본 서비스 계정 권한 확인

Compute Engine VM 인스턴스의 액세스 범위가 적합하더라도 인스턴스의 기본 서비스 계정이 에이전트에 적합한 Cloud IAM 권한을 제공하지 않을 수 있습니다.

기본 서비스 계정 권한을 확인하려면 기본 서비스 계정부터 찾습니다.

  1. 프로젝트의 Compute Engine 대시보드를 엽니다.

    Compute Engine 인스턴스 페이지 열기

  2. VM 인스턴스의 이름을 클릭합니다. 인스턴스의 세부정보 페이지가 나타납니다.

  3. 이 페이지에서 서비스 계정이라는 제목을 찾습니다. 인스턴스의 기본 서비스 계정이 나열됩니다. 다음과 비슷할 것입니다.

    [ID]-compute@developer.gserviceaccount.com
    
  4. 프로젝트의 IAM 및 관리자 > IAM 페이지를 엽니다. 페이지 제목은 프로젝트 [PROJECT_NAME]의 권한입니다.

    IAM 페이지 열기

  5. 보기 기준: 구성원을 선택합니다. 사람, 그룹, 서비스 계정의 목록이 표시됩니다. 역할 열에는 각 프로젝트 구성원의 역할이 표시됩니다.

  6. 인스턴스의 기본 서비스 계정 행에는 하나 이상의 역할이 표시됩니다.

    • 편집자가 표시되어 있는 경우 이 역할은 모든 에이전트에 적합합니다. 편집자는 Compute Engine의 서비스 계정에 할당되는 기본 역할입니다.
    • 로그 작성자가 표시되면 이 역할은 Logging 에이전트에 충분합니다. 쓰기 권한이 포함된 다른 Logging 역할은 Cloud Logging을 위한 액세스 제어를 참조하세요.
    • 모니터링 측정항목 작성자가 표시되면 이 역할은 Monitoring 에이전트에 충분합니다. 쓰기 권한아 포함된 다른 Monitoring 역할은 Cloud Monitoring을 위한 액세스 제어를 참조하세요.

문제 해결

기본 서비스 계정에 적절한 역할이 없으면 IAM 및 관리자 > IAM 페이지에서 서비스 계정의 역할을 수정해 보세요. 적절한 Logging 또는 Monitoring 역할을 추가하여 에이전트를 승인합니다(Logging > 로그 작성자 또는 Monitoring > 모니터링 측정항목 작성자).

비공개 키 사용자 인증 정보 확인

Compute Engine VM 인스턴스에서는 기본 서비스 계정 이외에 적절한 승인을 얻은 다른 서비스 계정을 사용하도록 에이전트를 구성할 수 있습니다. AWS EC2 VM 인스턴스에서는 이러한 서비스 계정을 사용하도록 에이전트를 구성해야 합니다.

이 같은 방식으로 에이전트를 구성하려면 지정된 서비스 계정을 위한 비공개 키 사용자 인증 정보를 만들어서 에이전트에 제공해야 합니다. 에이전트는 사용자 인증 정보를 다음 두 가지 방법으로 찾습니다.

  1. 비공개 키 사용자 인증 정보가 담긴 파일의 이름을 포함하는 환경 변수 GOOGLE_APPLICATION_CREDENTIALS를 찾습니다.
  2. 이 환경 변수가 존재하지 않는 경우 에이전트가 다음과 같이 표준 파일에서 사용자 인증 정보를 찾습니다.

Linux

 /etc/google/auth/application_default_credentials.json

Windows

C:\ProgramData\Google\Auth\application_default_credentials.json

다음 정보는 비공개 키 사용자 인증 정보 문제를 진단하는 데 도움이 됩니다.

  1. 비공개 키가 제위치에 있나요?
  2. 비공개 키가 서비스 계정에 아직 유효한가요?
  3. 서비스 계정이 에이전트에 필요한 역할을 지니고 있나요?

VM 인스턴스에 유효한 비공개 키 사용자 인증 정보가 설치되어 있는지 확인하려면 먼저 사용자 인증 정보 파일이 예상 위치에 있는지 확인한 다음 사용자 인증 정보 파일의 정보가 유효한지 확인합니다. Cloud Console의 IAM 및 관리자 > 서비스 계정 섹션을 사용하여 이전의 유효 사용자 인증 정보를 취소할 수 있습니다. 유효한 사용자 인증 정보가 없으면 사용자 인증 정보 추가를 참조하여 기존 사용자 인증 정보를 바꾸거나 새 사용자 인증 정보를 추가합니다.

사용자 인증 정보가 있나요?

비공개 키 서비스 계정 사용자 인증 정보가 인스턴스에 있는지 확인하려면 인스턴스에서 다음 Linux 명령어를 실행합니다.

sudo cat $GOOGLE_APPLICATION_CREDENTIALS
sudo cat /etc/google/auth/application_default_credentials.json

두 명령어 중 하나가 다음과 같은 파일을 표시하면 인스턴스에 유효한 비공개 키 사용자 인증 정보가 있는 것입니다. 두 명령어 모두 파일을 표시하면 GOOGLE_APPLICATION_CREDENTIALS가 나타내는 파일이 사용됩니다.

{
  "type": "service_account",
  "project_id": "[YOUR-PROJECT-ID]",
  "private_key_id": "[YOUR-PRIVATE-KEY-ID]",
  "private_key": "[YOUR-PRIVATE-KEY]",
  "client_email": "[YOUR-PROJECT-NUMBER]-[YOUR-KEY@DEVELOPER].gserviceaccount.com",
  "client_id": "[YOUR-CLIENT-ID]",
  "auth_uri": "https://accounts.google.com/o/oauth2/auth",
  "token_uri": "https://accounts.google.com/o/oauth2/token",
  "auth_provider_x509_cert_url": "{x509-cert-url}",
  "client_x509_cert_url": "{client-x509-cert-url}"
}

사용자 인증 정보 파일이 없는 경우 사용자 인증 정보 추가하기를 참조하세요.

사용자 인증 정보가 유효한가요?

사용자 인증 정보 파일에서 project_id는 GCP 프로젝트이고, client_email은 프로젝트의 서비스 계정을 식별하고, private_key_id는 서비스 계정의 비공개 키를 식별합니다. 이 정보를 Cloud Console의 IAM 및 관리자 > 서비스 계정 섹션에 표시된 정보와 비교합니다.

다음 중 하나라도 해당하는 경우 사용자 인증 정보가 유효하지 않습니다.

  • Compute Engine 인스턴스를 확인하고 있지만 사용자 인증 정보 파일의 GCP 프로젝트가 인스턴스가 포함된 프로젝트가 아닙니다.
  • Amazon EC2 인스턴스를 확인하고 있지만 사용자 인증 정보 파일의 GCP 프로젝트가 AWS 계정의 커넥터 프로젝트(이름: AWS Link...)가 아닙니다.
  • 나열된 서비스 계정이 존재하지 않습니다. 삭제되었을 수 있습니다.
  • 나열된 서비스 계정에 올바른 역할이 사용 설정되어 있지 않습니다(Cloud Logging 에이전트의 로그 작성자 및 Cloud Monitoring 에이전트의 모니터링 측정 항목 작성기).
  • 비공개 키가 없습니다. 취소되었을 수 있습니다.

서비스 계정은 올바른 계정이지만 비공개 키가 취소된 경우 새 비공개 키를 만들어 인스턴스에 복사할 수 있습니다. 서비스 계정 키 만들기를 참조하세요.

그렇지 않으면 사용자 인증 정보 추가하기 섹션의 설명에 따라 새 서비스 계정을 만들어야 합니다.

에이전트 다시 설치하기

최신 버전의 에이전트를 설치하면 많은 문제가 해결됩니다.

그 외 자주 발생하는 문제

다음 표에는 Cloud Logging 에이전트에서 발생할 수 있는 일반적인 문제 일부와 해결 방법이 나와 있습니다.

Linux에서 Logging 에이전트는 /var/log/google-fluentd/google-fluentd.log에 오류를 기록합니다. Windows에서 Logging 에이전트는 오류를 C:\Program Files (x86)\Stackdriver\LoggingAgent\fluentd.log에 기록합니다(v1-9 버전부터). 오류 클래스 Google::APIClient::ClientError는 권한 또는 API 액세스에 문제가 있음을 나타냅니다.

에이전트가 성공적으로 실행 중이더라도 오류가 발생할 수 있습니다. 예를 들어 누군가가 프로젝트 또는 VM 인스턴스에서 필수 권한을 취소했을 수 있습니다.

오류 원인 해결책
Windows에서 에이전트 설치 프로그램이 실행되지 않습니다. 설치 프로그램을 시스템 디렉터리에 다운로드했을 수 있습니다. 설치 프로그램을 시스템 디렉터리가 아닌 다른 디렉터리(예: C:\Users\[USERID]\)로 옮깁니다.
프로젝트에서 API를 사용 설정하지 않았습니다. 프로젝트에서 Cloud Logging API를 사용 설정하지 않았습니다. API 콘솔로 이동하고 Cloud Logging API 상태를 ON으로 변경합니다.
요청에 잘못된 사용자 인증 정보가 있습니다.
또는
액세스 토큰을 가져올 수 없습니다(범위를 구성하지 않았나요?).
VM 인스턴스에 적절한 사용자 인증 정보가 없습니다. Amazon EC2를 사용할 경우 에이전트를 설치하기 전에 VM 인스턴스에 사용자 인증 정보를 설치해야 합니다. 사용자 인증 정보를 설치하려면 에이전트 승인을 참조하세요.
승인에 실패했습니다. Logging 에이전트를 위한 비공개 키 승인 사용자 인증 정보가 올바르게 구성되지 않았습니다. 비공개 키 사용자 인증 정보 확인하기를 참조하세요.
호출자에게 권한이 없습니다. 프로젝트에서 승인에 사용되는 서비스 계정에 권한이 충분하지 않습니다. Compute Engine 또는 App Engine 내에서 사용되는 기본 서비스 계정이거나 비공개 키 승인에 사용되는 사용자 정의 서비스 계정일 것입니다. 계정에 수정 가능 권한이 있어야 합니다. 프로젝트의 IAM 페이지에서 서비스 계정 권한을 변경합니다. 필요한 경우 인스턴스의 서비스 계정 및 액세스 범위 변경 절차를 통해 기존 VM의 액세스 범위를 수정할 수 있습니다.
프로젝트 ID를 가져올 수 없습니다. Cloud Logging 에이전트가 서비스 계정의 비공개 키 사용자 인증 정보 파일에서 프로젝트 ID를 가져올 수 없습니다. 에이전트의 프로젝트 ID를 추가 또는 재정의하려면 VM 인스턴스에서 에이전트 구성 파일인 /etc/google-fluentd/google-fluentd.conf를 수정합니다. <match **> 섹션에 다음 줄을 추가합니다.
project_id [YOUR_PROJECT_ID]
아니면 에이전트 승인을 참조하여 사용자 인증 정보를 수정 또는 교체합니다.
logrotate가 있는 상태에서 Logging 에이전트가 로그 수집을 중지합니다. copytruncate 설정으로 logrotate를 설정하면 Logging 에이전트가 입력 파일 위치를 추적하지 못할 수 있습니다. nocopytruncate 설정을 사용하면 logrotate가 파일을 자르지 않고 이동하므로 이 설정이 가장 좋습니다. copytruncate 설정을 유지하려면 정기적으로 에이전트를 다시 시작합니다. 또는 postrotate 설정을 사용하여 에이전트를 다시 시작할 수 있습니다.

최대 로그 크기 초과

로그 항목 한 개 이상이 최대 크기 한도를 초과한 경우 fluentd 로그에서 다음과 비슷한 항목을 찾을 수 있습니다.

Dropping 1 log message(s) error_class="Google::Apis::ClientError" error="Invalid request"


또는
Dropping 1 log message(s) error="3:Log entry with size 1000515 bytes exceeds maximum size of 112640 bytes" error_code="3"

이 오류를 해결하려면 최대 크기 한도를 초과하지 않도록 로그 항목을 자릅니다. 예를 들어 다음 샘플 코드는 message 필드에 데이터가 있고 mytag 태그를 사용하는 로그를 자릅니다.

# Cloud Logging only supports log entries that are up to 256 KiB in size.
# Trim the entries to just under that size to avoid dropping them.
<filter [MY_TAG]>
  @type record_transformer
  enable_ruby true
  <record>
    message ${record['message'].length > 256000 ? "[Trimmed]#{record['message'][0..256000]}..." : record['message']}
  </record>
</filter>