Solução de problemas da instalação do agente

Nesta página, você aprende a diagnosticar problemas na instalação ou na execução do agente do Monitoring.

Lista de verificação

Se você tiver problemas para instalar ou usar o agente do Monitoring, siga estas etapas:

  • Se os comandos de instalação do Linux resultarem em erros, certifique-se de prefixar os comandos de instalação com sudo.

  • Confira se o serviço do agente está em execução na instância da VM:

    • Para VMs do Windows, use o seguinte comando do PowerShell:

      Get-Service -Name StackdriverMonitoring
          

      Pesquise um serviço chamado Stackdriver Monitoring. Se o agente não estiver em execução, talvez seja necessário reiniciá-lo.

    • Para VMs do Linux, use o seguinte comando:

      sudo service stackdriver-agent status
          

      Se o agente não estiver em execução, talvez seja necessário reiniciá-lo com o seguinte comando:

      sudo service stackdriver-agent restart
          

      Se a reinicialização falhar e a saída do registro mostrar "Desativado por meio de metadados", é provável que você esteja executando uma imagem do Cloud Marketplace, em que o agente do Monitoring está desativado por padrão. Isso é controlado pela chave de metadados da instância google-monitoring-enable, com o valor 0. Para reativar o agente, remova essa chave ou defina o valor como 1. Consulte Como configurar metadados de instância.

      Se o agente não estiver desativado por meio dos metadados, reinstale-o. Consulte esta seção.

  • Verifique se o agente tem mensagens de erro gravadas nos registros.

    • No Windows, o agente do Monitoring grava mensagens no log de eventos do Windows.

    • No Linux, o agente do Monitoring é um pacote collectd e registra mensagens em /var/log/syslog ou /var/log/messages. As mensagens de registro são prefixadas por collectd ou stackdriver-agent:

      • Se forem exibidos erros HTTP 429, talvez você tenha excedido as cotas da API Monitoring. É possível ver sua cota disponível selecionando APIs e serviços > Painel no Console do Cloud. Escolha a API Monitoring.

      • Se houver problemas de proxy, verifique se o proxy HTTP foi configurado corretamente. As instruções estão incluídas em Como instalar no Linux e no Windows.

      • Se houver problemas de autorização e de acesso à API ou mensagens de erro como "Não foi possível determinar o endpoint collectd", consulte a seção Como verificar o projeto e as credenciais a seguir.

      • Se forem exibidos os erros "Combinação de tipo/plug-in collectd incompatível" ou "Código de collectd incompatível" nos registros, talvez você esteja enviando métricas de agentes incompatíveis. Isso pode acontecer nos seguintes cenários:

        • Você modificou uma das configurações de aplicativos de terceiros do agente. Para reverter as alterações, reinstale a configuração do plug-in específico seguindo as instruções na página de documentação relevante. Se você quiser usar o agente para enviar essa métrica ao Monitoring, converta-os em métricas personalizadas.

        • Um dos plug-ins de aplicativos de terceiros está enviando novas métricas que são desconhecidas para o Monitoring. Consulte a página de suporte para detalhes sobre como enviar uma solicitação para que essas métricas sejam analisadas e categorizadas.

  • Se o agente está em execução normalmente, mas você não recebe dados, ou as políticas de alertas não funcionam como esperado, é recomendável verificar se o agente está enviando dados ao projeto correto. Consulte a seção a seguir Como verificar o projeto e as credenciais.

Como verificar o projeto e as credenciais

Quando o agente informa erros de acesso ou de autorização, é recomendável verificar se as credenciais da instância de VM estão corretas, inclusive se especificam o projeto certo. Isso também é necessário quando parece que o agente está sendo executado normalmente e não há dados ou quando as políticas de alertas apresentam um comportamento inesperado. Veja como proceder:

  • Para verificar se os dados estão chegando no Monitoring, tente ler alguns dos dados da série temporal. Consulte Como verificar a conexão entre o agente e o projeto para mais instruções. Se você consegue ver os dados, o problema não é com o agente.

  • Se estiver usando uma instância de VM do Google Compute Engine com credenciais padrão, e não uma chave particular, é pouco provável que os dados estejam indo para o projeto errado. Talvez suas credenciais ainda estejam incompletas. Para informações sobre credenciais, consulte Como autorizar o agente. Para verificar as credenciais, consulte Como verificar credenciais do Compute Engine.

  • Se você estiver usando uma instância de VM do Amazon EC2 ou credenciais de chave particular na instância do Google Compute Engine, as credenciais poderão ser inválidas ou provenientes do projeto errado. Em contas da AWS, o projeto usado pelo agente precisa ser o projeto de conector da AWS, normalmente chamado de "AWS Link...". Para informações sobre credenciais, consulte Como autorizar o agente. Consulte Como verificar credenciais de chave privada para verificar as credenciais.

Se ainda não tiver resolvido o problema, consulte Como reinstalar o agente.

Como verificar os dados do agente

Para verificar se o agente está enviando as métricas corretamente, use o método timeseries.list da API Monitoring para procurar dados recentes da série temporal recebidos da instância de VM. Chame o método usando o formulário APIs Explorer, localizado na parte inferior da página de documentação do método. Se nenhum dado for exibido, é possível que o agente esteja enviando dados para o projeto errado. Para conferir isso, consulte Como verificar o projeto e as credenciais.

Veja a seguir instruções detalhadas sobre o uso do método timeseries.list:

  1. Determine o código da instância de VM em que o agente foi instalado:

    • Compute Engine: acesse a página de detalhes da instância. Na parte inferior da página, clique em REST equivalente. O código é um número de 19 dígitos.

    • Amazon EC2: o código de cada instância é mostrado na lista de instâncias. O código se parece com i-1a2b3c4d.

  2. Acesse a página de documentação do método timeseries.list:

    Abrir a página do timeseries.list

  3. Na seção Testar, clique na opção Autorizar solicitações usando o OAuth 2.0. Aceite o formulário sem fazer alterações e clique em Autorizar.

  4. Preencha o formulário do APIs Explorer:

    1. Defina um nome para o projeto que contém sua instância de VM, com o prefixo projects/. Por exemplo, projects/[YOUR_PROJECT_ID]. Para instâncias do Amazon EC2, use o projeto do conector da AWS da conta da Amazon, que normalmente tem um nome que começa com "AWS Link".

    2. Defina filtro como a linha a seguir para escolher uma métrica do agente recebida da instância de VM. Copie essa métrica e cole-a no APIs Explorer. Em seguida, altere o código da instância de VM:

      metric.type = "agent.googleapis.com/memory/bytes_used" AND resource.label.instance_id = "[YOUR-VM-INSTANCE-ID]"
          
    3. Defina o período da pesquisa. Recomendamos um intervalo de aproximadamente cinco minutos:

      • Defina interval.endTime como o horário GMT atual, que pode ser encontrado em time.is/GMT. A hora precisa ser formatada como no exemplo a seguir. Não coloque o horário entre aspas:

        2016-10-31T14:10:00Z
            
      • Defina interval.startTime como aproximadamente cinco minutos antes do horário de término usando o mesmo formato.

    4. Deixe todos os outros campos em branco.

  5. Clique em Executar.

O resultado será assim:

{
     "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
         }
        },
        ...
    

Se a chamada à API retornar dados da série temporal da instância de VM, como mostrado acima, isso significa que o agente está funcionando corretamente e você concluiu o processo.

Se nenhum dado da série temporal for mostrado, verifique o seguinte:

  • Se a chamada à API resulta em uma mensagem de erro, isso não indica um problema no agente. Verifique se os campos do APIs Explorer estão preenchidos corretamente. Verifique a ortografia e o formato do código do projeto e os dois carimbos de data/hora. A mensagem de erro "Não autorizado" pode significar que você escreveu o código do projeto errado. Erros com a mensagem "Não encontrado" podem indicar que você omitiu o prefixo projects/ obrigatório no campo "nome". Corrija os problemas e teste a chamada de API novamente.

  • Se a chamada à API for bem-sucedida, mas você ainda receber apenas uma resposta vazia, { }, verifique se o filtro e o período estão corretos. Alguns erros na formatação dos carimbos de data/hora podem impedir o recebimento de dados. Se tudo parecer correto, e ainda assim você não receber os dados, isso significa que o agente não está enviando os dados de métricas ou pelo menos não para o projeto esperado. Isso pode indicar um problema com a credencial. Consulte Como verificar as credenciais de chave privada.

Como verificar as credenciais do Compute Engine

Use a página Compute Engine > Instâncias de VM do Console do Cloud para verificar se a instância de VM do Compute Engine tem credenciais adequadas para o agente do Monitoring. Normalmente, as credenciais são adicionadas à conta de serviço padrão de todas as novas instâncias de VM do Compute Engine, mas é possível substituir esses padrões ao criar uma instância.

Ir para a página de instâncias do Compute Engine

  1. Se necessário, altere o projeto do GCP atual para associá-lo à sua instância de VM do Compute Engine. Por exemplo, se for solicitado para você Ativar o faturamento, isso significa que o projeto atual não contém nenhuma instância de VM do Compute Engine.
  2. Na página Instâncias de VMs, clique no nome da instância. A página de detalhes dela é exibida.
  3. Na página Detalhes da instância de VM, verifique o cabeçalho Escopos de acesso à API Cloud:
    1. Você tem as credenciais adequadas se a mensagem "Permitir acesso completo a todas as APIs do Cloud" for exibida.
    2. Se aparecer a permissão Somente gravação ou Total ao lado de API Cloud Monitoring, você tem as credenciais adequadas.
    3. Caso contrário, a conta de serviço padrão da instância não tem as credenciais necessárias para o agente. Para usar o agente na instância, você precisa adicionar as credenciais da conta de serviço de chave privada. Para ver instruções, consulte Como adicionar credenciais.

Se você tiver as credenciais padrão corretas, prossiga para Como instalar no Linux e Windows.

Como verificar credenciais de chave privada

Para verificar se as credenciais de chave privada válidas estão instaladas na instância de VM, confirme primeiro se o arquivo de credenciais está na localização esperada e se as informações nele são válidas. As credenciais anteriormente válidas podem ser revogadas por meio da seção IAM e Administrador > Contas de serviço do Console do Cloud. Se não houver credenciais válidas, consulte Como adicionar credenciais para substituir as existentes ou adicionar novas.

As credenciais estão presentes?

Para ver se as credenciais da conta de serviço de chave privada estão na instância, execute os seguintes comandos do Linux na instância:

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

Se um dos comandos exibir um arquivo conforme mostrado a seguir, pode ser que a instância tenha credenciais de chave privada válidas. Se ambos os comandos exibirem um arquivo, será usado o arquivo indicado por 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}"
    }
    

Se não houver arquivos de credenciais presentes, consulte Como adicionar credenciais.

As credenciais são válidas?

No arquivo de credenciais, project_id é o projeto do GCP, client_email identifica a conta de serviço no projeto e private_key_id identifica a chave privada na conta de serviço. Combine essas informações com o que é exibido na seção IAM e Administrador > Contas de serviço do Console do Cloud.

O arquivo de credenciais não será válido se qualquer uma das afirmações a seguir for verdadeira:

  • Você está verificando uma instância do Compute Engine, mas o projeto do GCP no arquivo de credenciais não é o que contém a instância.
  • Você está verificando uma instância do Amazon EC2, mas o projeto do GCP no arquivo de credenciais não é o projeto do conector, chamado AWS Link..., para sua conta da AWS.
  • A conta de serviço listada não existe. Ela pode ter sido excluída.
  • A conta de serviço listada não tem os papéis certos ativados. Ela deve ter pelo menos roles/monitoring.metricWriter (Gravador de métricas do Monitoring) para o agente do Monitoring e roles/logging.logWriter (Gravador de registros) para o agente do Logging.
  • A chave privada não existe. Ela pode ter sido revogada.

Se a conta de serviço estiver correta, mas a chave privada tiver sido revogada, é possível criar uma nova chave privada e copiá-la na sua instância. Caso contrário, você precisa criar uma nova conta de serviço, conforme descrito na seção Como adicionar credenciais.

Como gerar novas credenciais

Se as credenciais não forem válidas, siga as etapas a seguir:

  1. Crie uma conta de serviço e gere uma chave privada caso você não as tenha para cada projeto conectado que contém instâncias que precisam ser autorizadas com uma chave privada. Isso inclui todos os projetos de conector da AWS e instâncias do Compute Engine criadas sem o escopo de monitoramento. Siga as etapas abaixo:

    1. Para ver a lista de projetos conectados ao seu espaço de trabalho, acesse o Monitoring:

      Acessar o Monitoring

    2. Se estiver no painel de navegação “Monitoramento”, selecione Configurações e, em seguida, selecione a guia Resumo:

      • Na AWS, use o link para navegar diretamente para o projeto em questão no Console do Cloud.
      • No GCP, identifique o projeto que contém os recursos do Compute Engine em questão e navegue até o Console do Cloud.
    3. No Console do Cloud, navegue até a página Contas de serviço do IAM.

    4. Crie uma nova conta de serviço e gere uma nova chave privada para ela.

      O jeito mais simples é fazer o download de uma chave privada com a configuração correta. Consiga essa chave modificando o URL da página atual: acrescente &createStackdriverServiceAccount no final do URL. Para mais informações, consulte Como criar uma conta de serviço.

  2. Substitua a chave privada pelas instâncias que correspondem à conta de serviço em questão.

    • No Linux, substitua a chave privada localizada em /etc/google/auth/application_default_credentials.json
    • No Windows, substitua a chave privada localizada em C:\ProgramData\Google\Auth\application_default_credentials.json. Para mais detalhes, consulte Como copiar a chave privada para a instância.
  3. Reinicie o agente.

    • No Linux, execute sudo service stackdriver-agent restart.
    • No Windows, acesse o console de gerenciamento de serviços e reinicie o serviço Cloud Monitoring.

Se você tiver vários projetos que precisam de novas chaves privadas, repita esse processo para cada um deles.

Para verificar se a chave privada está correta, consulte As credenciais estão presentes?. Veja algumas condições específicas:

  • Leia o arquivo JSON da chave privada na instância. Por exemplo (no Linux): sudo cat /etc/google/auth/application_default_credentials.json
  • Verifique se o valor de project-id corresponde ao valor do projeto monitorado para o qual você acabou de gerar credenciais.

Como reinstalar o agente

A instalação da versão mais recente do agente soluciona muitos problemas:

Como reiniciar o agente automaticamente

Configure um script para verificar se o agente está em execução. Depois, reinicie o agente em caso de falha.

Por exemplo, no Linux, é possível criar a seguinte entrada crontab para verificar o status do agente a cada cinco minutos:

  */5 * * * * /bin/pidof stackdriver-collectd >/dev/null 2>&1 || /usr/sbin/service stackdriver-agent restart >/dev/null 2>&1