Encontrar informações de solução de problemas do agente de operações

Neste documento, descrevemos fontes de informações de diagnóstico que podem ser usadas para identificar problemas na instalação ou execução do agente de operações.

Verificações de integridade do agente

A versão 2.25.1 introduziu verificações de integridade do horário de início para o Agente de operações. Quando o Agente de operações é iniciado, ele executa uma série de verificações de condições que impedem a execução correta do agente. Se o agente detectar uma das condições, ele registrará uma mensagem descrevendo o problema. O agente de operações verifica o seguinte:

• Problemas de conexão
• Disponibilidade de portas usadas pelo agente para relatar métricas sobre ele mesmo
• Problemas de permissão
• Disponibilidade das APIs usadas pelo agente para gravar registros ou métricas
• Um problema na própria rotina de verificação de integridade.

Para informações sobre como localizar erros de horário de início, consulte Encontrar erros de horário de início.

A versão 2.37.0 introduziu verificações de integridade do ambiente de execução para o Agente de operações. Esses erros são informados ao Cloud Logging e ao Error Reporting. Para informações sobre como localizar erros de ambiente de execução, consulte Encontrar erros de ambiente de execução.

A versão 2.46.0 introduz o código informativo LogPingOpsAgent. Esse código não representa um erro. Para mais informações, consulte Verificar a coleta de registros.

A tabela a seguir lista cada código de verificação de integridade em ordem alfabética e descreve o que cada um deles significa. Códigos que terminam com a string Err indicam erros. Enquanto outros códigos são informativos.

Código de verificação de integridade	Categoria	Significado	Sugestão
DLApiConnErr	Conectividade	Falha na solicitação para o subdomínio de downloads dl.google.com.	Verifique a conexão de Internet e as regras de firewall. Para mais informações, consulte Problemas de conectividade de rede.
FbMetricsPortErr	Disponibilidade de portas	A porta 20202, necessária para as métricas do agente de operações, não está disponível.	Verifique se a porta 20202 está aberta. Para mais informações, consulte A porta necessária não está disponível.
HcFailureErr	Genérico	A rotina de verificação de integridade do agente de operações encontrou um erro interno.	Envie um caso de suporte no console do Google Cloud. Para mais informações, acesse Como receber ajuda.
LogApiConnErr	Conectividade	Falha na solicitação à API Logging.	Verifique a conexão de Internet e as regras de firewall. Para mais informações, consulte Problemas de conectividade de rede.
LogApiDisabledErr	API	A API Logging está desativada no projeto atual do Google Cloud.	Ativar a API Logging.
LogApiPermissionErr	Permissão	A conta de serviço não tem o papel de gravador de registros (roles/logging.logWriter).	Conceda o papel de gravador de registros à conta de serviço. Para mais informações, consulte O agente não tem permissões de API.
LogApiScopeErr	Permissão	A VM não tem o escopo de acesso https://www.googleapis.com/​auth/​logging.write.	Adicione o escopo https://www.googleapis.com/​auth/​logging.write à VM. Para mais informações, consulte Verificar os escopos de acesso.
LogApiUnauthenticatedErr	API	Não foi possível autenticar a VM atual na API Logging.	Verifique se os arquivos de credenciais, os escopos de acesso da VM e as permissões estão configurados corretamente. Para mais informações, consulte Autorizar o Agente de operações.
LogPingOpsAgent		Uma mensagem de payload informativa gravada a cada 10 minutos no registro ops-agent-health. Use as entradas de registro resultantes para verificar se o agente está enviando registros. Esta mensagem não é um erro.	Essa mensagem deve aparecer a cada 10 minutos. Se a mensagem não aparecer por 20 minutos ou mais, é possível que o agente tenha encontrado um problema. Para informações sobre solução de problemas, consulte Resolver problemas do Agente de operações.
LogParseErr	Ambiente de execução	O Agente de operações não conseguiu analisar um ou mais registros.	Verifique a configuração dos processadores de geração de registros criados por você. Para mais informações, consulte Erros de análise de registros.
LogPipeLineErr	Ambiente de execução	O pipeline de geração de registros do Agente de operações falhou.	Verifique se o agente tem acesso aos arquivos do buffer, e analise se há um disco completo, além de conferir se a configuração do Agente de operações está correta. Para mais informações, consulte Erros de pipeline.
MetaApiConnErr	Conectividade	Falha na solicitação ao servidor de metadados da G C E para consultar os escopos de acesso da VM, os tokens OAuth e os rótulos de recursos.	Verifique a conexão de Internet e as regras de firewall. Para mais informações, consulte Problemas de conectividade de rede.
MonApiConnErr	Conectividade	Ocorreu uma falha na solicitação para a API Monitoring.	Verifique a conexão de Internet e as regras de firewall. Para mais informações, consulte Problemas de conectividade de rede.
MonApiDisabledErr	API	A API Monitoring está desativada no projeto atual do Google Cloud.	Ative a API Monitoring.
MonApiPermissionErr	Permissão	A conta de serviço não tem o papel de gravador de métricas do Monitoring (roles/monitoring.metricWriter).	Conceda o papel Gravador de métricas do Monitoring à conta de serviço. Para mais informações, consulte O agente não tem permissões de API.
MonApiScopeErr	Permissão	A VM não tem o escopo de acesso https://www.googleapis.com/​auth/​monitoring.write.	Adicione o escopo https://www.googleapis.com/​auth/​monitoring.write à VM. Para mais informações, consulte Verificar os escopos de acesso.
MonApiUnauthenticatedErr	API	Não foi possível autenticar a VM atual na API Monitoring.	Verifique se os arquivos de credenciais, os escopos de acesso da VM e as permissões estão configurados corretamente. Para mais informações, consulte Autorizar o Agente de operações.
OtelMetricsPortErr	Disponibilidade de portas	A porta 20201, necessária para as métricas do agente de operações, não está disponível.	Verifique se a porta 20201 está aberta. Para mais informações, consulte Uma porta obrigatória não está disponível.
PacApiConnErr	Conectividade	Falha na solicitação para o repositório de pacotes, packages.cloud.google.com.	Verifique a conexão de Internet e as regras de firewall. Para mais informações, consulte Problemas de conectividade de rede.

Encontrar erros de horário de início

A partir da versão 2.35.0, as informações de verificação de integridade são gravadas no registro ops-agent-health pela API Cloud Logging. As versões 2.33.0 e 2.34.0 usam ops-agent-health-checks. A mesma informação também é gravada em um arquivo health-checks.log da seguinte maneira:

• Linux: /var/log/google-cloud-ops-agent/health-checks.log
• Windows: C:\ProgramData\Google\Cloud Operations\Ops Agent\log\health-checks.log

Também é possível visualizar as mensagens de verificação de integridade consultando o status do serviço do Agente de operações da seguinte maneira:

• No Linux, execute o seguinte comando:

     sudo systemctl status google-cloud-ops-agent"*"
     

  Procure mensagens como "[Ports Check] Result: PASS". Outros resultados incluem "ERROR" e "FAIL".

• No Windows, use o Visualizador de eventos do Windows. Procure as mensagens "Informações", "Erro" ou "Falha" associadas ao serviço google-cloud-ops-agent.

Depois de resolver os problemas, reinicie o agente. As verificações de integridade são executadas quando o agente é iniciado. Portanto, para executá-las novamente, é necessário reiniciá-lo.

Encontrar erros de ambiente de execução

As verificações de integridade do ambiente de execução são informadas para o Cloud Logging e o Error Reporting. Se a inicialização do agente falhou, mas foi possível relatar erros antes da falha, talvez você também veja os erros de horário de início informados.

Para ver os erros do ambiente de execução do Agente de operações no Logging, faça o seguinte:

1. No painel de navegação do console do Google Cloud, selecione Logging e, depois, Explorador de registros:

   Acessar o Explorador de registros

2. Digite a seguinte consulta e clique em Executar consulta:
   

   log_id("ops-agent-health")

Para visualizar os erros de ambiente de execução do Agente de operações no Error Reporting, faça o seguinte:

1. No painel de navegação do console do Google Cloud, selecione Error Reporting e escolha seu projeto do Google Cloud:

   Acessar o Error Reporting

2. Para ver os erros do Agente de operações, filtre-os por Ops Agent.

Verifique se a coleta de registros foi bem-sucedida

A versão 2.46.0 do Agente de operações introduziu a verificação de integridade LogPingOpsAgent informativa. Essa verificação grava uma mensagem informativa no ops-agent-health a cada 10 minutos. É possível usar a presença dessas mensagens para verificar se o Agente de operações está gravando registros. Para isso, faça o seguinte:

• Pesquisar registros de uma VM específica para encontrar mensagens de ping usando a Análise de registros.
• Verifique o valor da métrica log_entry_count de uma VM específica usando o Metrics Explorer.
• Crie uma política de alertas para receber notificações caso uma VM específica não esteja atualizando a métrica log_entry_count.

Se alguma dessas opções indicar que as mensagens de registro não estão sendo ingeridas, faça o seguinte:

• Verifique se há códigos de erro indicando erros de inicialização ou erros de execução.
• Determine se o Agente de operações está funcionando.
• Execute o script de diagnóstico do agente.

Para verificar o status do Agente de operações em uma VM específica, você precisa do ID da instância. Para encontrar o ID da instância, faça o seguinte:

• No painel de navegação do console do Google Cloud, selecione Compute Engine e, depois, Instâncias de VM:

  Acessar Instâncias de VM

• Clique no nome de uma instância de VM.
• Na guia Detalhes, localize a seção Informações básicas. O ID da instância aparece como uma string numérica. Use essa string para o valor INSTANCE_ID nas próximas seções.

Pesquisar mensagens usando a Análise de registros

Para usar a Análise de registros para pesquisar mensagens de ping nos registros de uma VM, faça o seguinte:

1. No painel de navegação do console do Google Cloud, selecione Logging e clique em Análise de registros:

   Acessar a Análise de registros

2. Para buscar mensagens ping do Agente de operações em uma instância de VM específica, insira a seguinte consulta e substitua INSTANCE_ID pelo identificador para uma VM do Compute Engine, depois clique em Executar consulta:

   resource.type="gce_instance"
   resource.labels.instance_id="INSTANCE_ID"
   log_id("ops-agent-health")
   jsonPayload.code="LogPingOpsAgent"
       

Veja a métrica log_entry_count

Se quiser usar o Metrics Explorer para verificar o valor da métrica log_entry_count de uma VM, faça o seguinte:

1. No painel de navegação do console do Google Cloud, selecione Monitoramento e  Metrics Explorer:

   Acesse o Metrics explorer

2. No campo Selecionar uma métrica, faça o seguinte:
   1. Digite log entries.
   2. Em Tipo de recurso, selecione Instância de VM.
   3. Na Categoria da métrica, selecione Métricas com base em registros.
   4. Em Métrica, selecione Entradas de registro.
   5. Selecione Apply.
3. No campo Filtro , adicione os seguintes filtros:
   • Filtre pelo ID da instância de uma VM específica:
     1. Selecione o rótulo do recurso instance_id.
     2. Selecione o comparador = (igual a).
     3. Informe o INSTANCE_ID de uma VM.
   • Filtre o registro ops-agent-health:
     1. Selecione o rótulo de recurso log.
     2. Selecione o comparador = (igual a).
     3. Selecione o valor ops-agent-heath.

Crie uma política de alertas para a métrica log_entry_count

Para criar uma política de alertas que monitore o valor da métrica log_entry_count para pings de registro de uma VM específica, faça o seguinte:

1. No painel de navegação do console do Google Cloud, selecione Monitoramento e  Alertas: s

   Acessar Alertas

2. Se você não tiver criado seus canais de notificação e quiser receber uma notificação, clique em Editar canais de notificação e adicione-os. Volte para a página Alertas depois de adicionar seus canais.
3. Na página Alertas, clique em Criar política.
4. No campo Selecionar uma métrica, faça o seguinte:
   1. Digite log entries.
   2. Em Tipo de recurso, selecione Instância de VM.
   3. Na Categoria da métrica, selecione Métricas com base em registros.
   4. Em Métrica, selecione Entradas de registro.
   5. Selecione Apply.
5. No campo Filtro , adicione os seguintes filtros:
   • Filtre pelo ID da instância de uma VM específica:
     1. Selecione o rótulo do recurso instance_id.
     2. Selecione o comparador = (igual a).
     3. Informe o INSTANCE_ID de uma VM.
   • Filtre o registro ops-agent-health:
     1. Selecione o rótulo de recurso log.
     2. Selecione o comparador = (igual a).
     3. Selecione o valor ops-agent-heath.
6. Na seção Transformar dados, selecione o seguinte:
   • No campo Janela contínua, selecione 10 min. Para detectar entradas de registro ausentes em um período mais longo, insira um valor maior.
   • No campo Função de janela contínua, selecione delta.
7. Clique em Próxima.
8. As configurações da página Configurar acionador de alertas determinam quando o alerta é acionado. Preencha esta página com as configurações da tabela a seguir.
   

   Campo Configurar gatilho de alerta	Valor
   Condition type	Threshold
   Alert trigger	Any time series violates
   Threshold position	Below threshold
   Threshold value	1
   Advanced Options: Retest window	No retest

9. Clique em Próxima.
10. Opcional: para adicionar notificações à sua política de alertas, clique em Canais de notificação. Na caixa de diálogo, selecione um ou mais canais de notificação no menu e clique em OK.
11. Opcional: Atualize a Duração do fechamento automático do incidente. Este campo determina quando o Monitoring fecha incidentes na ausência de dados de métrica.
12. Opcional: clique em Documentação e adicione as informações que quer incluir em uma mensagem de notificação.
13. Clique em Nome e digite um nome para a política de alertas.
14. Clique em Criar política.

Saiba mais em Políticas de alertas.

Ferramenta de diagnóstico do agente para VMs

A ferramenta de diagnóstico do agente coleta informações essenciais de depuração local das VMs do Linux para todos os agentes a seguir: agente de operações, agente do Logging legado e agente do Monitoring legado. As informações de depuração incluem itens como informações do projeto, VMs, configuração do agente, registros do agente, status do serviço do agente e informações que normalmente exigem trabalho manual para serem coletadas. A ferramenta também verifica o ambiente da VM local para garantir que ela atenda a determinados requisitos para que os agentes funcionem corretamente, por exemplo, conectividade de rede e permissões necessárias.

Ao registrar um caso de cliente para um agente em uma VM, execute a ferramenta de diagnóstico do agente e anexe as informações coletadas ao caso. Fornecer essas informações reduz o tempo necessário para resolver problemas no seu caso de suporte. Antes de anexar as informações ao caso de suporte, edite as informações confidenciais, como senhas.

A ferramenta de diagnóstico do agente precisa ser executada dentro da VM do Linux. Portanto, você normalmente precisa executar o SSH na VM primeiro. O comando a seguir recupera e executa a ferramenta de diagnóstico do agente:

Linux

curl -sSO https://dl.google.com/cloudagents/diagnose-agents.sh
sudo bash diagnose-agents.sh

Windows

(New-Object Net.WebClient).DownloadFile("https://dl.google.com/cloudagents/diagnose-agents.ps1", "${env:UserProfile}\diagnose-agents.ps1")
Invoke-Expression "${env:UserProfile}\diagnose-agents.ps1"

Siga a saída da execução do script para localizar os arquivos que incluem as informações coletadas. Normalmente, é possível encontrá-los no diretório /var/tmp/google-agents no Linux e no diretório $env:LOCALAPPDATA/Temp no Windows, a menos que você tenha personalizado o diretório de saída ao executar o script.

Para ver informações detalhadas, examine o script diagnose-agents.sh no Linux ou o script diagnose-agents.ps1 no Windows.

Ferramenta de diagnóstico do agente para políticas de instalação automática

Se uma tentativa de instalar o Agente de operações usando uma política de SO dele falhar, use o script de diagnóstico descrito nesta seção para depuração. Por exemplo, você pode encontrar um dos seguintes casos:

• A instalação do Agente de operações falha quando você usa a caixa de seleção Instalar o Agente de operações para o Monitoring e Logging para instalá-lo durante a criação da VM.

• O status do agente no painel Instâncias de VM do Cloud Monitoring ou a guia Observabilidade em uma página de detalhes da VM do Compute Engine permanece no estado Pendente por mais de 10 minutos. Um status Pendente prolongado pode indicar uma das seguintes situações:

  • Um problema ao aplicar a política.
  • Um problema na instalação real do Agente de operações.
  • Um problema de conectividade entre a VM e o Cloud Monitoring.

  Para alguns desses problemas, o script de diagnóstico do agente e as verificações de integridade também podem ser úteis.

Para executar o script de diagnóstico da política, execute os seguintes comandos:

curl -sSO https://dl.google.com/cloudagents/diagnose-ui-policies.sh
bash diagnose-ui-policies.sh VM_NAME VM_ZONE

Observação: é necessário ter o papel roles/osconfig.osPolicyAssignmentViewer para executar este script.

Este script mostra informações sobre VMs afetadas e políticas de instalação automática relacionadas.

Ao registrar um caso de cliente para um agente em uma VM, execute as ferramentas de diagnóstico do agente e anexe as informações coletadas ao caso. Fornecer essas informações reduz o tempo necessário para resolver problemas no seu caso de suporte. Antes de anexar as informações ao caso de suporte, edite as informações confidenciais, como senhas.

Status do agente

É possível verificar o status dos processos do agente de operações na VM para determinar se o agente está em execução ou não.

Linux

Para verificar o status do agente de operações, use o seguinte comando:

sudo systemctl status google-cloud-ops-agent"*"

Verifique se os componentes "Agente do Metrics" e "Agente do Logging" estão listados como "ativos (em execução)", conforme mostrado no exemplo de saída a seguir. Algumas linhas foram removidas para simplificar:

● google-cloud-ops-agent.service - Google Cloud Ops Agent
     Loaded: loaded (/lib/systemd/system/google-cloud-ops-agent.service; enabled; vendor preset: enabled)
     Active: active (exited) since Wed 2023-05-03 21:22:28 UTC; 4 weeks 0 days ago
    Process: 3353828 ExecStartPre=/opt/google-cloud-ops-agent/libexec/google_cloud_ops_agent_engine -in /etc/go>
    Process: 3353837 ExecStart=/bin/true (code=exited, status=0/SUCCESS)
   Main PID: 3353837 (code=exited, status=0/SUCCESS)
        CPU: 195ms

[...]

● google-cloud-ops-agent-opentelemetry-collector.service - Google Cloud Ops Agent - Metrics Agent
     Loaded: loaded (/lib/systemd/system/google-cloud-ops-agent-opentelemetry-collector.service; static)
     Active: active (running) since Wed 2023-05-03 21:22:29 UTC; 4 weeks 0 days ago
    Process: 3353840 ExecStartPre=/opt/google-cloud-ops-agent/libexec/google_cloud_ops_agent_engine -service=ot>
   Main PID: 3353855 (otelopscol)
      Tasks: 9 (limit: 2355)
     Memory: 65.3M
        CPU: 40min 31.555s
     CGroup: /system.slice/google-cloud-ops-agent-opentelemetry-collector.service
             └─3353855 /opt/google-cloud-ops-agent/subagents/opentelemetry-collector/otelopscol --config=/run/g>

[...]

● google-cloud-ops-agent-fluent-bit.service - Google Cloud Ops Agent - Logging Agent
     Loaded: loaded (/lib/systemd/system/google-cloud-ops-agent-fluent-bit.service; static)
     Active: active (running) since Wed 2023-05-03 21:22:29 UTC; 4 weeks 0 days ago
    Process: 3353838 ExecStartPre=/opt/google-cloud-ops-agent/libexec/google_cloud_ops_agent_engine -service=fl>
   Main PID: 3353856 (google_cloud_op)
      Tasks: 31 (limit: 2355)
     Memory: 58.3M
        CPU: 29min 6.771s
     CGroup: /system.slice/google-cloud-ops-agent-fluent-bit.service
             ├─3353856 /opt/google-cloud-ops-agent/libexec/google_cloud_ops_agent_wrapper -config_path /etc/goo>
             └─3353872 /opt/google-cloud-ops-agent/subagents/fluent-bit/bin/fluent-bit --config /run/google-clo>

[...]

● google-cloud-ops-agent-diagnostics.service - Google Cloud Ops Agent - Diagnostics
     Loaded: loaded (/lib/systemd/system/google-cloud-ops-agent-diagnostics.service; disabled; vendor preset: e>
     Active: active (running) since Wed 2023-05-03 21:22:26 UTC; 4 weeks 0 days ago
   Main PID: 3353819 (google_cloud_op)
      Tasks: 8 (limit: 2355)
     Memory: 36.0M
        CPU: 3min 19.488s
     CGroup: /system.slice/google-cloud-ops-agent-diagnostics.service
             └─3353819 /opt/google-cloud-ops-agent/libexec/google_cloud_ops_agent_diagnostics -config /etc/goog>

[...]

Windows

Para verificar o status do agente de operações, use o seguinte comando:

Get-Service google-cloud-ops-agent*

Verifique se os componentes "Agente de métrica" e "Agente de Logging" estão listados como "Em execução", conforme mostrado no exemplo de saída a seguir:

Status   Name               DisplayName
------   ----               -----------
Running  google-cloud-op... Google Cloud Ops Agent
Running  google-cloud-op... Google Cloud Ops Agent - Logging Agent
Running  google-cloud-op... Google Cloud Ops Agent - Metrics Agent
Running  google-cloud-op... Google Cloud Ops Agent - Diagnostics

Registros automáticos do agente

Se o agente não ingerir registros no Cloud Logging, talvez seja necessário inspecionar os registros do agente localmente na VM para solucionar problemas. Também é possível usar a rotação de registros para gerenciar os próprios registros do agente.

Linux

Observação: tudo o que está na seção Linux foi automatizado como parte da ferramenta de diagnóstico. Para realizar a inspeção de registro manualmente, siga as etapas abaixo.

Para inspecionar registros próprios gravados em Journald, execute o comando a seguir:

journalctl -u google-cloud-ops-agent*

Para inspecionar os registros próprios gravados no disco pelo módulo de geração de registros, execute o comando a seguir:

vim -M /var/log/google-cloud-ops-agent/subagents/logging-module.log

Windows

Para inspecionar registros próprios gravados em Windows Event Logs, execute o comando a seguir:

Get-WinEvent -FilterHashtable @{ Logname='Application'; ProviderName='google-cloud-ops-agent*' } | Format-Table -AutoSize -Wrap

Para inspecionar os registros próprios gravados no disco pelo módulo de geração de registros, execute o comando a seguir:

notepad "C:\ProgramData\Google\Cloud Operations\Ops Agent\log\logging-module.log"

Para inspecionar os registros de Windows Service Control Manager dos serviços do Agente de operações, execute o comando a seguir:

Get-WinEvent -FilterHashtable @{ Logname='System'; ProviderName='Service Control Manager' } | Where-Object -Property Message -Match 'Google Cloud Ops Agent' | Format-Table -AutoSize -Wrap

Ver diagnósticos e uso de métricas no Cloud Monitoring

A página Gerenciamento de métricas do Cloud Monitoring fornece informações que podem ajudar a controlar o valor gasto em métricas sujeitas a cobrança, sem afetar a observabilidade. A página Gerenciamento de métricas mostra as seguintes informações:

• Volumes de ingestão para faturamento baseado em byte e amostra, em domínios de métricas e para métricas individuais.
• Dados sobre rótulos e cardinalidade de métricas.
• Uso de métricas em políticas de alertas e painéis personalizados.
• Taxa de erros de gravação de métrica.

Para visualizar a página Gerenciamento de métricas, faça o seguinte:

1. No painel de navegação do console do Google Cloud, selecione Monitoramento e  Gerenciamento de métricas:

   Acesse os Gerenciamento de métricas

2. Na barra de ferramentas, selecione a janela de tempo. Por padrão, a página Gerenciamento de métricas exibe informações sobre as métricas coletadas no dia anterior.

Para mais informações sobre a página Gerenciamento de métricas, consulte Ver e gerenciar o uso de métricas.