에이전트 설치 문제해결

이 페이지는 Monitoring 에이전트의 설치 또는 실행 문제를 진단하는 데 도움이 됩니다.

체크리스트

Monitoring 에이전트를 설치하거나 사용하는 데 문제가 있는 경우 다음 사항을 확인하세요.

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

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

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

      Get-Service -Name StackdriverMonitoring
      

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

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

      sudo service stackdriver-agent status
      

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

      sudo service stackdriver-agent restart
      

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

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

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

    • Windows의 경우 Monitoring 에이전트는 Windows 이벤트 로그에 메시지를 작성합니다.

    • Linux의 경우 Monitoring 에이전트는 collectd 패키지이며 메시지를 /var/log/syslog 또는 /var/log/messages에 작성합니다. 로그 메시지에는 collectd 또는 stackdriver-agent라는 프리픽스가 붙습니다.

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

      • 프록시 문제가 발생하는 경우 HTTP 프록시를 올바르게 구성했는지 확인합니다. Linux에 설치하기 또는 Windows에 설치하기의 안내를 참조하세요.

      • API 액세스 또는 승인 문제가 발생하거나 'collectd 엔드포인트를 확인할 수 없음'과 같은 오류 메시지가 나타나는 경우 다음에 나오는 프로젝트 및 사용자 인증 정보 확인하기 섹션을 참조하세요.

      • 로그에 '지원되지 않는 collectd 플러그인/유형 조합' 또는 '지원되지 않는 collectd id'와 같은 오류가 있는 경우 지원되지 않는 에이전트 측정항목을 전송 중일 수 있습니다. 에이전트 타사 애플리케이션 구성 중 하나를 수정한 경우 이 오류가 발생할 수 있습니다. 변경사항을 되돌리려면 관련 문서 페이지의 안내에 따라 특정 플러그인의 구성을 다시 설치하면 됩니다. 에이전트를 사용하여 해당 측정항목을 Monitoring에 전송하려면 커스텀 측정항목으로 전환을 검토하세요.

  • 에이전트가 정상적으로 실행되는 것 같지만 수신 데이터가 없거나 알림 정책이 예상대로 작동하지 않는 경우 에이전트가 올바른 프로젝트에 데이터를 전송하고 있는지 확인해야 합니다. 다음에 나오는 프로젝트 및 사용자 인증 정보 확인하기 섹션을 참조하세요.

프로젝트 및 사용자 인증 정보 확인하기

에이전트가 액세스 또는 승인 오류를 보고하거나, 에이전트가 정상적으로 실행되는 것 같지만 데이터가 없거나, 알림 정책이 예상대로 작동하지 않는 경우 올바른 프로젝트가 지정되었는지, 그리고 VM 인스턴스의 사용자 인증 정보가 올바른지 확인해야 합니다.

  • Monitoring에서 데이터를 수신하고 있는지 확인하려면 시계열 데이터의 일부를 읽어봅니다. 에이전트와 프로젝트 연결 확인하기의 안내를 참조하세요. 데이터가 표시되면 에이전트 문제가 아닙니다.

  • 비공개 키가 아닌 표준 사용자 인증 정보로 Google Compute Engine VM 인스턴스를 사용하고 있는 경우 데이터가 잘못된 프로젝트로 전송될 가능성은 거의 없지만 사용자 인증 정보가 부족할 수 있습니다. 사용자 인증 정보에 대한 자세한 내용은 에이전트 승인하기를 참조하세요. 사용자 인증 정보를 확인하려면 Compute Engine 사용자 인증 정보 확인하기를 참조하세요.

  • Amazon EC2 VM 인스턴스를 사용하고 있거나, Google Compute Engine 인스턴스에 비공개 키 사용자 인증 정보를 사용하고 있는 경우 사용자 인증 정보가 유효하지 않거나 잘못된 프로젝트에서 가져온 것일 수 있습니다. AWS 계정의 경우 에이전트에 사용되는 프로젝트는 일반적으로 "AWS Link..."라는 이름이 지정된 AWS 커넥터 프로젝트여야 합니다. 사용자 인증 정보에 대한 자세한 내용은 에이전트 승인하기를 참조하세요. 사용자 인증 정보를 확인하려면 비공개 키 사용자 인증 정보 확인하기를 참조하세요.

그래도 문제가 해결되지 않으면 에이전트 다시 설치하기를 참조하세요.

에이전트 데이터 확인하기

에이전트가 측정항목을 제대로 전송하고 있는지 확인하려면 Monitoring API의 timeseries.list 메소드를 사용하여 VM 인스턴스의 최근 시계열 데이터를 찾아봅니다. 메소드의 문서 페이지 하단에 있는 API 탐색기 양식을 사용하여 메소드를 호출할 수 있습니다. 데이터가 표시되지 않으면 에이전트가 잘못된 프로젝트에 데이터를 전송 중일 수 있습니다. 이를 확인하려면 프로젝트 및 사용자 인증 정보 확인하기를 참조하세요.

다음은 timeseries.list 메소드 사용에 대한 자세한 안내입니다.

  1. 에이전트를 설치한 VM 인스턴스의 인스턴스 ID를 확인합니다.

    • Compute Engine: 인스턴스에 대한 Compute Engine의 세부정보 페이지로 이동합니다. 페이지 하단에서 동등한 REST를 클릭합니다. ID는 19자리 숫자입니다.

    • Amazon EC2: 각 인스턴스의 ID가 인스턴스 목록에 표시됩니다. ID 형식은 i-1a2b3c4d와 같습니다.

  2. timeseries.list 메소드의 문서 페이지로 이동합니다.

    timeseries.list 페이지 열기

  3. 사용해 보기 섹션에서 OAuth 2.0을 사용하여 요청 승인 스위치를 클릭합니다. 양식을 그대로 수락하고 승인을 클릭합니다.

  4. API 탐색기 양식을 작성합니다.

    1. VM 인스턴스를 포함하는 프로젝트로 이름을 설정합니다. 이때 projects/를 프리픽스로 사용합니다(예: projects/[YOUR_PROJECT_ID]). Amazon EC2 인스턴스의 경우 Amazon 계정에 AWS 커넥터 프로젝트를 사용해야 합니다. AWS 커넥터 프로젝트 이름은 일반적으로 "AWS Link"로 시작합니다.

    2. 필터를 다음 줄로 설정하여 VM 인스턴스에서 에이전트 측정항목을 선택합니다. 에이전트 측정항목을 복사하여 API 탐색기에 붙여넣은 다음 VM 인스턴스 ID를 변경합니다.

      metric.type = "agent.googleapis.com/memory/bytes_used" AND resource.label.instance_id = "[YOUR-VM-INSTANCE-ID]"
      
    3. 검색 시간 간격을 설정합니다. 약 5분 간격이 적당합니다.

      • interval.endTimetime.is/GMT에서 확인할 수 있는 현재 GMT 시간으로 설정합니다. 시간 형식은 다음 예시와 같아야 합니다. 시간을 큰따옴표로 묶지 마세요.

        2016-10-31T14:10:00Z
        
      • 동일한 형식을 사용하여 interval.startTime을 종료 시간 약 5분 전으로 설정합니다.

    4. 다른 필드는 모두 비워 둡니다.

  5. 실행을 클릭합니다.

다음과 같은 출력이 표시되어야 합니다.

{
 "timeSeries": [
  {
   "metric": {
    "labels": {
     "state": "buffered"
    },
    "type": "agent.googleapis.com/memory/bytes_used"
   },
   "resource": {
    "type": "[GCP-OR-AWS-INSTANCE-TYPE]",
    "labels": {
     "instance_id": "[YOUR-VM-INSTANCE-ID]",
     "zone": "[YOUR-INSTANCE-ZONE]",
     "project_id": "[YOUR-PROJECT-ID]"
    }
   },
   "metricKind": "GAUGE",
   "valueType": "DOUBLE",
   "points": [
    {
     "interval": {
      "startTime": "[START_TIME]",
      "endTime": "[END_TIME]"
     },
     "value": {
      "doubleValue": 27451392
     }
    },
    ...

위와 같이 API 호출이 VM 인스턴스의 시계열 데이터를 반환하는 경우 에이전트가 제대로 작동하고 있는 것이므로 사용자가 더 이상 수행할 작업은 없습니다.

시계열 데이터가 표시되지 않는 경우 다음을 확인합니다.

  • API 호출로 인해 오류 메시지가 나타나면 에이전트 문제가 아닙니다. API 탐색기 필드가 올바르게 채워졌는지 확인합니다. 프로젝트 ID, 필터, 2가지 타임스탬프의 철자와 형식을 확인하세요. '승인되지 않음' 오류는 프로젝트 ID의 철자가 잘못되었음을 의미할 수 있습니다. '찾을 수 없음' 오류는 '이름' 필드에 필수 projects/ 프리픽스가 누락되었음을 나타낼 수 있습니다. 문제를 수정하고 API 호출을 다시 시도하세요.

  • API 호출은 성공했지만 빈 응답({ })만 표시되면 필터와 시간 간격이 올바른지 확인합니다. 타임스탬프 형식이 잘못된 경우 데이터가 반환되지 않습니다. 아무 문제도 없어 보이지만 수신 데이터가 없는 경우 에이전트가 측정항목 데이터를 전송하고 있지 않거나 사용자 예상과 다른 프로젝트에 데이터를 전송하고 있는 것입니다. 이는 사용자 인증 정보 문제를 의미하는 것일 수 있습니다. 비공개 키 사용자 인증 정보 확인하기를 참조하세요.

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

GCP Console의 Compute Engine > VM 인스턴스 페이지를 사용하여 Compute Engine VM 인스턴스가 Monitoring 에이전트에 적절한 사용자 인증 정보를 갖고 있는지 확인합니다. 사용자 인증 정보는 대개 모든 새 Compute Engine VM 인스턴스의 기본 서비스 계정에 추가되지만 인스턴스를 만들 때 이러한 기본값을 덮어쓸 수 있습니다.

Compute Engine 인스턴스 페이지 열기

  1. 필요한 경우 현재 GCP 프로젝트를 Compute Engine VM 인스턴스와 연결된 프로젝트로 변경합니다. 예를 들어 결제 사용 설정 메시지가 나타나면 현재 프로젝트에 Compute Engine VM 인스턴스가 없는 것입니다.
  2. VM 인스턴스 페이지에서 VM 인스턴스의 이름을 클릭합니다. VM 인스턴스의 세부정보 페이지가 나타납니다.
  3. VM 인스턴스 세부정보 페이지에서 Cloud API 액세스 범위 제목 아래를 봅니다.
    1. '모든 Cloud APIs에 대한 전체 액세스 허용'이 표시되면 적절한 사용자 인증 정보가 있는 것입니다.
    2. Stackdriver Monitoring API 옆에 쓰기 전용 또는 전체 권한이 있는 것으로 표시되면 적절한 사용자 인증 정보가 있는 것입니다.
    3. 그렇지 않으면 에이전트에 필요한 사용자 인증 정보가 인스턴스의 기본 서비스 계정에 없는 것입니다. 인스턴스에서 에이전트를 사용하려면 비공개 키 서비스 계정 사용자 인증 정보를 추가해야 합니다. 사용자 인증 정보 추가하기의 안내를 참조하세요.

올바른 기본 사용자 인증 정보가 있으면 Linux에 설치하기 또는 Microsoft Windows에 설치하기를 진행합니다.

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

VM 인스턴스에 유효한 비공개 키 사용자 인증 정보가 설치되어 있는지 확인하려면 먼저 사용자 인증 정보 파일이 예상 위치에 있는지 확인한 다음 사용자 인증 정보 파일의 정보가 유효한지 확인합니다. GCP 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는 서비스 계정의 비공개 키를 식별합니다. 이 정보를 GCP Console의 IAM 및 관리자 > 서비스 계정 섹션에 표시된 정보와 비교합니다.

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

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

서비스 계정에 문제가 없지만 비공개 키가 취소된 경우 새 비공개 키를 만들어 인스턴스에 복사할 수 있습니다. 그렇지 않으면 다음에 나오는 사용자 인증 정보 추가하기 섹션의 설명에 따라 새 서비스 계정을 만들어야 합니다.

새 사용자 인증 정보 생성하기

사용자 인증 정보가 유효하지 않은 경우 다음 단계를 따르세요.

  1. 비공개 키로 승인해야 하는 인스턴스(모니터링 범위 없이 만든 모든 AWS 커넥터 프로젝트 및 Compute Engine 인스턴스)를 포함하는 연결된 각 프로젝트에 대해 서비스 계정을 만들고 비공개 키를 생성합니다(없는 경우). 다음 단계를 따르세요.

    1. 여기에서 작업공간에 연결된 프로젝트 목록을 엽니다.
      • AWS의 경우 해당 프로젝트의 Cloud Console로 바로 이동하는 링크를 사용합니다.
      • GCP의 경우 해당 Compute Engine 리소스를 포함하는 프로젝트를 식별하고 Cloud Console로 이동합니다.
    2. Cloud Console에서 IAM 서비스 계정 페이지로 이동합니다.
    3. 새 서비스 계정을 만들고 해당 비공개 키를 새로 생성합니다.

      가장 간단한 방법은 올바른 구성의 비공개 키를 다운로드하는 것입니다. 현재 페이지에서 URL을 수정(즉, URL 끝에 &createStackdriverServiceAccount 추가)하여 이 키를 얻을 수 있습니다. 자세한 내용은 서비스 계정 만들기를 참조하세요.

  2. 문제의 서비스 계정에 해당하는 인스턴스에서 비공개 키를 바꿉니다.

    • Linux의 경우 /etc/google/auth/application_default_credentials.json에 있는 비공개 키를 바꿉니다.
    • Windows의 경우 C:\ProgramData\Google\Auth\application_default_credentials.json에 있는 비공개 키를 바꿉니다. 자세한 내용은 인스턴스에 비공개 키 복사하기를 참조하세요.
  3. 에이전트 다시 시작

    • Linux의 경우 sudo service stackdriver-agent restart를 실행합니다.
    • Windows의 경우 서비스 관리 콘솔로 이동하고 Stackdriver Monitoring 서비스를 다시 시작합니다.

새 비공개 키가 필요한 프로젝트가 여러 개인 경우 각 프로젝트에 대해 이 절차를 반복합니다.

비공개 키가 올바른지 확인하려면 사용자 인증 정보가 있나요?를 참조하세요. 구체적으로는 다음과 같습니다.

  • 인스턴스에서 비공개 키 JSON 파일을 읽습니다. 예: sudo cat /etc/google/auth/application_default_credentials.json(Linux의 경우).
  • project-id의 값이 사용자 인증 정보를 생성한 모니터링 프로젝트의 값과 일치하는지 확인합니다.

에이전트 다시 설치하기

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

이 페이지가 도움이 되었나요? 평가를 부탁드립니다.

다음에 대한 의견 보내기...

Stackdriver Monitoring
도움이 필요하시나요? 지원 페이지를 방문하세요.