Como solucionar problemas do agente

Nesta página, você verá instruções para solucionar problemas comuns encontrados durante a instalação ou a interação com o agente do Logging.

Lista de verificação

Se você estiver com problemas para instalar ou usar o agente do Logging, veja alguns itens a serem verificados:

  • 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 StackdriverLogging
      

      Procure um serviço chamado Stackdriver Logging. 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 google-fluentd status
      

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

      sudo service google-fluentd restart
      

      Se a reinicialização falhar e a saída do registro mostrar "Desativada por metadados", é provável que você esteja executando uma imagem do Google Cloud Marketplace, em que o agente do Logging está desativado por padrão. Isso é controlado pela chave de metadados da instância google-logging-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, a partir da versão v1-9, o agente do Logging salva os registros em C:\Program Files (x86)\Stackdriver\LoggingAgent\fluentd.log.

      Não há como conseguir os registros das versões anteriores do agente.

    • No Linux, o agente do Logging é um pacote fluentd e registra mensagens para /var/log/google-fluentd/google-fluentd.log:

  • Se a execução do agente parece normal, mas você não está recebendo dados, verifique se ele está enviando dados para o projeto correto. Consulte a seção a seguir, Como verificar as credenciais do Compute Engine.

Como verificar a instalação do agente

Para verificar se a instalação foi bem-sucedida, procure a entrada de registro de teste do agente no visualizador de registros.

Acessar o visualizador de registros

  1. Na parte superior da página, escolha o projeto que contém sua instância de VM:

    • Para instâncias de VM do Compute Engine, escolha o projeto em que está a instância de VM.
    • Para instâncias de VM do Amazon EC2, escolha o projeto AWS LINK que o Google Cloud Monitoring cria quando você conecta sua conta do AWS a um espaço de trabalho.
    • Não escolha um projeto do espaço de trabalho, a não ser que o projeto contenha sua instância de VM do Compute Engine.
  2. Nas guias das janelas, escolha o recurso da instância da VM:

    • Para Compute Engine, escolha Instância da VM do GCE.
    • No Amazon EC2, escolha Instância do AWS EC2.
    • Selecione syslog (Linux), fluent.info (Windows) ou Todos os registros.

Se você vir uma entrada de registro, "gRPC enviado com sucesso para a API do Logging", a instalação do agente foi concluída. Essa mensagem é gerada quando o agente é instalado e também quando cada agente é reiniciado.

Para mais informações sobre o visualizador de registros, consulte esta página.

Como testar o agente

Se você suspeitar que o agente não está funcionando, verifique se ele está em execução e tente enviar uma mensagem de teste para o Logging:

Instância do Linux

O procedimento a seguir funciona em instâncias de VM do Compute Engine e do Amazon EC2 que executam o Linux:

  1. Verifique se o agente do Logging está executando os seguintes comandos na instância de VM:

    ps ax | grep fluentd
    

    O resultado será semelhante a:

     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. Envie uma mensagem de registro de teste executando o seguinte comando na instância de VM:

    logger "Some test message"
    

Instância do Windows

O agente do Logging tem dois nomes de serviço do Windows:

  • StackdriverLogging para as versões v1-5 e posteriores
  • fluentdwinsvc para versões anteriores

Você precisa ter um serviço de agente em execução. Execute os seguintes comandos na instância de VM usando o PowerShell:

  1. Solicite o status dos dois serviços. Se você souber qual serviço precisa estar em execução, use apenas o nome desse serviço:

    Get-Service StackdriverLogging,fluentdwinsvc
    
  2. Se não houver um serviço em execução, você receberá uma mensagem de erro. Caso contrário, você verá um resultado como este:

    Status    Name                DisplayName
    ------    ----                -----------
    Running  StackdriverLogging   Cloud Logging
    
  3. Se você consultar os dois serviços, verá uma mensagem de erro e um status Running:

    • Se você não vir nenhum status Running, então o agente do Logging não está em execução.
    • Se StackdriverLogging estiver funcionando, então você está executando uma versão recente do agente. Para determinar a versão específica, consulte Como conseguir a versão.
    • Se você vir que fluentdwinsvc está em execução, faça o upgrade do seu agente para a versão mais recente.
  4. Requer privilégios de administrador: caso haja alguma versão de agente em execução, envie uma mensagem de registro de teste executando os seguintes comandos do PowerShell:

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

Como localizar a mensagem de teste

Depois de enviar uma mensagem de teste, procure-a no visualizador de registros:

Acessar o visualizador de registros

  1. Na parte superior da página, escolha o projeto que contém sua instância de VM:

    • Para instâncias de VM do Compute Engine, escolha o projeto em que está a instância de VM.
    • Para instâncias de VM do Amazon EC2, escolha o projeto AWS LINK que o Google Cloud Monitoring cria quando você conecta a conta do AWS a um espaço de trabalho.
    • Não escolha um projeto do espaço de trabalho, a menos que seja o projeto em que está sua instância de VM do Compute Engine.
  2. Nas guias das janelas, escolha o recurso da instância da VM:

    • Para Compute Engine, escolha Instância da VM do GCE.
    • No Amazon EC2, escolha Instância do AWS EC2.
    • Selecione syslog (Linux), fluent.info (Windows) ou Todos os registros.
  3. Você precisa ver uma entrada de registro com a mensagem de teste. Em caso afirmativo, o agente do Logging está funcionando corretamente.

Como verificar as credenciais do Compute Engine

Para que uma instância de VM do Compute Engine execute o agente sem credenciais de chave privada, a instância precisa ter escopos de acesso e a identidade da conta de serviço usada pela instância precisa ter permissões adequadas do Cloud IAM.

Quando você cria uma instância de VM, as configurações de escopo padrão e de conta de serviço são suficientes para executar os agentes. As instâncias mais anteriores, ou as instâncias para que você alterou as configurações padrão, podem não ter credenciais adequadas.

Como verificar escopos de acesso

Para verificar os escopos de acesso, faça o seguinte:

  1. Abra a página Compute Engine > Instâncias de VM:

    Abrir a página "Instâncias"

  2. Clique no nome da instância de VM. A página "Detalhes" da instância é exibida.

  3. Na seção Escopos de acesso da API Cloud, clique em Detalhes para ver a lista de APIs. Procure as entradas a seguir:

    1. Se você vir "Esta instância tem acesso total à API a todos os serviços do Google Cloud", os escopos de acesso serão adequados.
    2. Se, ao lado de API Cloud Logging, você vir que tem a permissão Somente gravação ou Completa, os escopos de acesso da instância são adequados para o agente do Cloud Logging.
    3. Se, ao lado de API Cloud Monitoring, você vir que tem a permissão Somente gravação ou Completa, os escopos de acesso da instância são adequados para o agente do Cloud Monitoring.

Como corrigir o problema

Se você não tiver escopos de acesso adequados na instância do Compute Engine, adicione os escopos de acesso necessários à instância.

A tabela a seguir mostra os escopos relevantes para os agentes do Logging e do Monitoring:

Escopo de acesso Permissões do agente
https://www.googleapis.com/auth/logging.write Adequado para o agente do Logging
https://www.googleapis.com/auth/monitoring.write Adequado para o agente do Monitoring

Como verificar a permissão da conta de serviço padrão

Mesmo que os escopos de acesso da instância da VM do Compute Engine sejam adequados, a conta de serviço padrão da instância talvez não forneça as permissões certas do Cloud IAM para o agente.

Para verificar a permissão da conta de serviço padrão, comece localizando a conta de serviço padrão:

  1. Abra o painel do Compute Engine do seu projeto:

    Abrir a página "Instâncias" do Compute Engine

  2. Clique no nome da instância de VM. A página "Detalhes" da instância é exibida.

  3. Procure o título da conta de serviço na página. A conta de serviço padrão da instância é listada. Pode parecer com esta:

    [ID]-compute@developer.gserviceaccount.com
    
  4. Abra a página IAM e administrador > IAM do projeto. O título da página é Permissões do projeto [PROJECT_NAME]:

    Abrir a página do IAM

  5. Selecione Ver por: membros. Você precisa ver uma lista de pessoas, grupos e contas de serviço. Na coluna Papel estão os papéis que cada membro tem no projeto.

  6. Na linha da conta de serviço padrão da instância, você precisa ver um ou mais papéis:

    • Se você vir Editor, esse papel é adequado para todos os agentes. Editor é o papel padrão atribuído às contas de serviço do Compute Engine.
    • Se você vir Gravador de registros, esse papel é adequado para o agente do Logging. Para outros papéis do Logging que incluem a permissão de gravação, consulte Guia de controle de acesso do Cloud Logging.
    • Se você vir Gravador de métricas do Monitoring, esse papel será suficiente para o agente do Monitoring. Para outros papéis do Monitoring que incluem a permissão de gravação, consulte Guia de controle de acesso do Cloud Monitoring.

Como corrigir o problema

Se a conta de serviço padrão não tiver papéis adequados, tente editar os papéis da conta de serviço na página IAM e administrador > IAM. Adicione os papéis do Logging ou do Monitoring adequados para autorizar os agentes: Logging > Gravador de registros ou Monitoring > Gravador de métricas do Monitoring.

Como verificar credenciais de chave privada

Em instâncias de VM do Compute Engine, configure o agente para usar uma conta de serviço não padrão sem a autorização apropriada. Em instâncias de VM do AWS EC2, você precisa configurar o agente para usar uma conta de serviço assim.

Para configurar o agente dessa maneira, você precisa criar credenciais de chave particular para a conta de serviço designada e fornecer essas credenciais ao agente. O agente procura as credenciais de duas maneiras:

  1. O agente procura uma variável de ambiente, GOOGLE_APPLICATION_CREDENTIALS, que mantém o nome de um arquivo que contém as credenciais de chave particular.
  2. Se a variável de ambiente não estiver presente, o agente procurará credenciais em um arquivo padrão:

Linux

 /etc/google/auth/application_default_credentials.json

Windows

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

As seguintes informações ajudam a fazer o diagnóstico de problemas de credenciais de chave particular:

  1. A chave particular está implementada?
  2. A chave particular continua sendo válida para a conta de serviço?
  3. A conta de serviço tem os papéis necessários para o agente?

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 atuais 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: Gravador de registros para o agente do Cloud Logging e o Gravador de métricas do Monitoring para o agente do Cloud Monitoring.
  • A chave privada não existe. Ela pode ter sido revogada.

Se a conta de serviço for a correta, mas a chave particular tiver sido revogada, você poderá criar uma nova chave particular e copiá-la para a instância. Consulte Como criar chaves da conta de serviço.

Do contrário, você precisará criar uma nova conta de serviço, conforme descrito na seção Como adicionar credenciais.

Como reinstalar o agente

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

Outros problemas comuns

A tabela a seguir lista alguns problemas comuns que é possível encontrar com o agente do Cloud Logging e informa como corrigi-los.

No Linux, o agente do Logging registra erros em /var/log/google-fluentd/google-fluentd.log. No Windows, o agente do Logging registra erros em C:\Program Files (x86)\Stackdriver\LoggingAgent\fluentd.log, a partir da versão v1-9. A classe de erro Google::APIClient::ClientError indica que há um problema com as permissões ou com o acesso à API.

É possível que ocorram erros depois que o agente tiver sido executado com êxito. Por exemplo, alguém pode revogar as permissões necessárias do projeto ou da instância de VM.

Erro Causa Solução
Falha na execução do instalador do agente no Windows O download do instalador pode ter sido feito para um diretório do sistema. Mova o instalador para um diretório que não seja do sistema, como C:\Users\[USERID]\.
O projeto não ativou a API Você não ativou a API Cloud Logging no seu projeto. Acesse o console de APIs e altere o status da API Cloud Logging para ON.
A solicitação tinha credenciais inválidas
ou
Não foi possível buscar o token de acesso. Nenhum escopo foi configurado?
A instância de VM não tem credenciais adequadas. Se você estiver usando o Amazon EC2, instale credenciais nas instâncias de VM antes de instalar o agente. Consulte Como autorizar o agente para instalar credenciais.
Falha na autorização As credenciais de autorização de chave privada para o agente do Logging não estão configuradas corretamente. Consulte Como verificar credenciais de chave privada.
O autor da chamada não tem permissão A conta de serviço usada para autorização no projeto não tem permissões suficientes. Pode ser a conta de serviço padrão usada no Compute Engine ou no App Engine ou pode ser uma conta de serviço definida pelo usuário usada para autorização de chave privada. A conta precisa ter a permissão Pode editar. Altere a permissão da conta de serviço na página IAM do seu projeto. Se necessário, é possível modificar o escopo de acesso para uma VM atual usando os procedimentos contidos em Como alterar a conta de serviço e os escopos de acesso de uma instância.
Não é possível conseguir o código do projeto O agente do Cloud Logging deixou de receber o ID do projeto enviado pelo arquivo de credenciais de chave privada de uma conta de serviço. Para adicionar ou modificar um ID do projeto para o agente, edite o arquivo de configuração do agente, /etc/google-fluentd/google-fluentd.conf, na instância da VM. Na seção <match **>, adicione a seguinte linha:
project_id [YOUR_PROJECT_ID]
Caso contrário, consulte Como autorizar o agente para corrigir ou substituir as credenciais.
O agente do Logging interrompe a ingestão de registros na presença de logrotate O agente do Logging pode perder o controle de onde está nos arquivos de entrada quando logrotate está configurado com a configuração copytruncate. É melhor usar a configuração nocopytruncate para garantir que o logrotate mova os arquivos em vez de truncá-los. Se você quiser manter a configuração copytruncate, a solução alternativa é reiniciar o agente periodicamente. Também é possível usar a configuração postrotate para reiniciar o agente.

Tamanho máximo do registro excedido

Se uma ou mais entradas de registro excederem o limite máximo de tamanho, será possível encontrar entradas nos registros fluentd semelhantes aos seguintes:

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


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

Para resolver esse erro, corte as entradas de registro para que elas não excedam o limite máximo de tamanho. Por exemplo, o código de amostra a seguir corta registros com a tag mytag, com os dados no campo message:

# 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>