Trovare informazioni sulla risoluzione dei problemi di Ops Agent

Questo documento descrive le fonti di informazioni diagnostiche che puoi utilizzare per identificare i problemi durante l'installazione o l'esecuzione di Ops Agent.

Controlli di integrità dell'agente

La versione 2.25.1 ha introdotto i controlli di integrità all'ora di inizio per Ops Agent. All'avvio, Ops Agent esegue una serie di controlli alla ricerca di condizioni che impediscono l'esecuzione corretta dell'agente. Se l'agente rileva una delle condizioni, registra un messaggio che descrive il problema. Ops Agent verifica quanto segue:

  • Problemi di connettività
  • Disponibilità di porte utilizzate dall'agente per generare report sulle metriche relative a se stesso
  • Problemi di autorizzazione
  • Disponibilità delle API utilizzate dall'agente per scrivere log o metriche
  • Un problema della routine di controllo di integrità stessa.
Per informazioni sull'individuazione degli errori di data e ora di inizio, consulta Trovare gli errori di data e ora.

La versione 2.37.0 ha introdotto i controlli Heath di runtime per Ops Agent. Questi errori vengono segnalati a Cloud Logging ed Error Reporting. Per informazioni sull'individuazione degli errori di runtime, consulta Ricerca degli errori di runtime.

La versione 2.46.0 ha introdotto il codice informativo LogPingOpsAgent. Questo codice non rappresenta un errore. Per maggiori informazioni, vedi Verificare la riuscita raccolta di log.

La tabella seguente elenca ogni codice del controllo di integrità in ordine alfabetico e descrive il significato di ogni codice. I codici che terminano con la stringa Err indicano errori, mentre gli altri codici sono informativi.

Codice per il controllo di integrità Categoria Significato Suggerimento
DLApiConnErr Connettività Richiesta al sottodominio dei download, dl.google.com, non riuscita. Controlla la connessione a internet e le regole del firewall. Per maggiori informazioni, consulta Problemi di connettività di rete.
FbMetricsPortErr Disponibilità porte La porta 20202, necessaria per le metriche personali di Ops Agent, non è disponibile. Verifica che la porta 20202 sia aperta. Per maggiori informazioni, consulta La porta richiesta non è disponibile.
HcFailureErr Generico Si è verificato un errore interno della routine di controllo di integrità di Ops Agent. Invia una richiesta di assistenza dalla console Google Cloud. Per maggiori informazioni, consulta Assistenza.
LogApiConnErr Connettività Richiesta all'API Logging non riuscita. Controlla la connessione a internet e le regole del firewall. Per maggiori informazioni, consulta Problemi di connettività di rete.
LogApiDisabledErr API L'API Logging è disabilitata nell'attuale progetto Google Cloud. Abilita l'API Logging.
LogApiPermissionErr Autorizzazione Nell'account di servizio manca il ruolo Writer log (roles/logging.logWriter). Concedi il ruolo Writer log all'account di servizio. Per maggiori informazioni, vedi L'agente non dispone delle autorizzazioni API.
LogApiScopeErr Autorizzazione Nella VM manca l'ambito di accesso https://www.googleapis.com/auth/logging.write. Aggiungi l'ambito https://www.googleapis.com/auth/logging.write alla VM. Per maggiori informazioni, consulta Verificare gli ambiti di accesso.
LogApiUnauthenticatedErr API La VM attuale non ha potuto eseguire l'autenticazione nell'API Logging. Verifica che i file delle credenziali, gli ambiti di accesso alle VM e le autorizzazioni siano configurati correttamente. Per maggiori informazioni, consulta Autorizzare Ops Agent.
LogPingOpsAgent   Un messaggio payload informativo scritto ogni 10 minuti nel log ops-agent-health. Puoi utilizzare le voci di log risultanti per verificare che l'agente stia inviando i log. Questo messaggio non è un errore. Questo messaggio dovrebbe essere visualizzato ogni 10 minuti. Se il messaggio non viene visualizzato per almeno 20 minuti, è possibile che l'agente abbia riscontrato un problema. Per informazioni sulla risoluzione dei problemi, consulta Risolvere i problemi di Ops Agent.
LogParseErr Runtime Ops Agent non è riuscito ad analizzare uno o più log. Controlla la configurazione di eventuali processori di logging che hai creato. Per ulteriori informazioni, consulta Errori di analisi dei log.
LogPipeLineErr Runtime La pipeline di logging di Ops Agent non è riuscita. Verifica che l'agente abbia accesso ai file di buffer; verifica che il disco sia pieno e che la configurazione di Ops Agent sia corretta. Per maggiori informazioni, consulta Errori della pipeline.
MetaApiConnErr Connettività Richiesta al server G C E Metadata di eseguire query sugli ambiti di accesso alle VM, sui token OAuth e sulle etichette delle risorse non è riuscita. Controlla la connessione a internet e le regole del firewall. Per maggiori informazioni, consulta Problemi di connettività di rete.
MonApiConnErr Connettività Richiesta all'API Monitoring non riuscita. Controlla la connessione a internet e le regole del firewall. Per maggiori informazioni, consulta Problemi di connettività di rete.
MonApiDisabledErr API L'API Monitoring è disabilitata nell'attuale progetto Google Cloud. Abilita l'API Monitoring.
MonApiPermissionErr Autorizzazione Nell'account di servizio manca il ruolo Writer metriche Monitoring (roles/monitoring.metricWriter). Concedi il ruolo Writer metriche Monitoring all'account di servizio. Per maggiori informazioni, vedi L'agente non dispone delle autorizzazioni API.
MonApiScopeErr Autorizzazione Nella VM manca l'ambito di accesso https://www.googleapis.com/auth/monitoring.write. Aggiungi l'ambito https://www.googleapis.com/auth/monitoring.write alla VM. Per maggiori informazioni, consulta Verificare gli ambiti di accesso.
MonApiUnauthenticatedErr API La VM attuale non è riuscita ad autenticarsi con l'API Monitoring. Verifica che i file delle credenziali, gli ambiti di accesso alle VM e le autorizzazioni siano configurati correttamente. Per maggiori informazioni, consulta Autorizzare Ops Agent.
OtelMetricsPortErr Disponibilità porte La porta 20201, necessaria per le metriche automatiche di Ops Agent, non è disponibile. Verifica che la porta 20201 sia aperta. Per maggiori informazioni, consulta Una porta obbligatoria non è disponibile.
PacApiConnErr Connettività Questo codice per il controllo di integrità non è affidabile. Questo codice è disabilitato in Ops Agent versione 2.46.1. Esegui l'aggiornamento alla versione Ops Agent 2.46.1 o successiva.

Individuare gli errori relativi all'ora di inizio

A partire dalla versione 2.35.0, le informazioni sul controllo di integrità vengono scritte nel log ops-agent-health dall'API Cloud Logging (le versioni 2.33.0 e 2.34.0 utilizzano ops-agent-health-checks). Le stesse informazioni vengono scritte anche in un file health-checks.log, come segue:

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

Puoi anche visualizzare qualsiasi messaggio di controllo di integrità eseguendo una query sullo stato del servizio Ops Agent come segue:

  • Su Linux, esegui questo comando: 
       sudo systemctl status google-cloud-ops-agent"*"

    Cerca messaggi come "[Ports Check] Risultato: PASS". Altri risultati sono "ERROR" e "FAIL".

  • Su Windows, utilizza il Visualizzatore eventi di Windows. Cerca i messaggi di tipo "Informazioni", "Errore" o "Errore" associati al servizio google-cloud-ops-agent.

Dopo aver risolto gli eventuali problemi, devi riavviare l'agente. I controlli di integrità vengono eseguiti all'avvio dell'agente, quindi per eseguirli nuovamente, devi riavviare l'agente.

Individuare gli errori di runtime

I controlli di integrità del runtime vengono segnalati sia in Cloud Logging sia in Error Reporting. Se l'agente non si è avviato, ma è riuscito a segnalare errori prima di non riuscire, potresti vedere anche errori all'ora di inizio segnalati.

Per visualizzare gli errori di runtime da Ops Agent in Logging, segui questi passaggi:

  1. Nella console Google Cloud, vai alla pagina Esplora log:

    Vai a Esplora log

    Se usi la barra di ricerca per trovare questa pagina, seleziona il risultato con il sottotitolo Logging.

  2. Inserisci la seguente query e fai clic su Esegui query:
    log_id("ops-agent-health")

Per visualizzare gli errori di runtime di Ops Agent in Error Reporting, segui questi passaggi:

  1. Nella console Google Cloud, vai alla pagina Error Reporting:

    Vai a Error Reporting.

    Puoi trovare questa pagina anche utilizzando la barra di ricerca.

  2. Per visualizzare gli errori di Ops Agent, filtra gli errori per Ops Agent.

Verifica la corretta raccolta dei log

La versione 2.46.0 di Ops Agent ha introdotto il controllo di integrità informativo di LogPingOpsAgent. Questo controllo scrive un messaggio informativo nel campo ops-agent-health ogni 10 minuti. Puoi utilizzare la presenza di questi messaggi per verificare che Ops Agent stia scrivendo i log in uno dei seguenti modi:

Se una di queste opzioni indica che i messaggi di log non vengono importati, puoi:

Per controllare lo stato di Ops Agent su una VM specifica, hai bisogno dell'ID istanza della VM. Per trovare l'ID istanza:

  • Nella console Google Cloud, vai alla pagina Istanze VM:

    Vai a Istanze VM

    Se usi la barra di ricerca per trovare questa pagina, seleziona il risultato con il sottotitolo Compute Engine.

  • Fai clic sul nome di un'istanza VM.
  • Nella scheda Dettagli, individua la sezione Informazioni di base. L'ID istanza viene visualizzato come stringa numerica. Utilizza questa stringa per il valore INSTANCE_ID nelle sezioni successive.

Strumento di diagnostica degli agenti per le VM

Lo strumento di diagnostica dell'agente raccoglie informazioni di debug locali critiche dalle tue VM per tutti i seguenti agenti: Ops Agent, agente Logging legacy e agente Monitoring legacy. Le informazioni di debug includono, ad esempio, informazioni sul progetto, informazioni sulla VM, configurazione dell'agente, log dell'agente, stato del servizio dell'agente e informazioni che in genere richiedono una raccolta manuale. Lo strumento controlla anche l'ambiente VM locale per verificare che soddisfi determinati requisiti per il corretto funzionamento degli agenti, ad esempio la connettività di rete e le autorizzazioni richieste.

Quando invii una richiesta di assistenza a un cliente per un agente su una VM, esegui lo strumento di diagnostica dell'agente e allega alla richiesta le informazioni raccolte. Queste informazioni consentono di ridurre il tempo necessario per la risoluzione dei problemi relativi alla tua richiesta di assistenza. Prima di allegare le informazioni alla richiesta di assistenza, oscura tutte le informazioni sensibili come le password.

Lo strumento di diagnostica dell'agente deve essere eseguito dall'interno della VM, quindi in genere è necessario prima accedere alla VM tramite SSH. Il seguente comando recupera lo strumento di diagnostica dell'agente e lo esegue:

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"

Segui l'output dell'esecuzione dello script per individuare i file che includono le informazioni raccolte. In genere puoi trovarli nella directory /var/tmp/google-agents su Linux e nella directory $env:LOCALAPPDATA/Temp su Windows, a meno che tu non abbia personalizzato la directory di output durante l'esecuzione dello script.

Per informazioni dettagliate, esamina lo script diagnose-agents.sh su Linux o lo script diagnose-agents.ps1 su Windows.

Strumento di diagnostica dell'agente per i criteri di installazione automatica

Se il tentativo di installare Ops Agent tramite un criterio del sistema operativo Ops Agent non va a buon fine, puoi utilizzare lo script di diagnostica descritto in questa sezione per il debug. Ad esempio, potresti notare uno dei seguenti casi:

  • L'installazione di Ops Agent non riesce quando hai utilizzato la casella di controllo Installa Ops Agent per il monitoraggio e il logging per installare Ops Agent durante la creazione della VM.

  • Lo stato dell'agente nella dashboard delle istanze VM di Cloud Monitoring o nella scheda Osservabilità in una pagina dei dettagli della VM di Compute Engine rimane nello stato In attesa per più di 10 minuti. Lo stato In attesa prolungato potrebbe indicare uno dei seguenti motivi:

    • Problema nell'applicazione del criterio.
    • Un problema con l'installazione effettiva di Ops Agent.
    • Un problema di connettività tra la VM e Cloud Monitoring.

    Per alcuni di questi problemi, potrebbero essere utili anche lo script generico di diagnostica dell'agente e i controlli di integrità.

Per eseguire lo script di diagnostica dei criteri, esegui questi comandi:

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

Questo script mostra informazioni sulle VM interessate e sui relativi criteri di installazione automatica.

Quando invii una richiesta di assistenza a un cliente per un agente su una VM, esegui gli strumenti di diagnostica dell'agente e allega alla richiesta le informazioni raccolte. Queste informazioni consentono di ridurre il tempo necessario per la risoluzione dei problemi relativi alla tua richiesta di assistenza. Prima di allegare le informazioni alla richiesta di assistenza, oscura tutte le informazioni sensibili come le password.

Stato agente

Puoi controllare lo stato dei processi di Ops Agent sulla VM per determinare se l'agente è in esecuzione o meno.

Linux

Per verificare lo stato di Ops Agent, utilizza il seguente comando:

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

Verifica che i componenti "Metrics Agent" e "Logging Agent" siano elencati come "attivo (in esecuzione)", come mostrato nel seguente output di esempio (alcune righe sono state rimosse per brevità):

● 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

Per verificare lo stato di Ops Agent, utilizza il seguente comando:

Get-Service google-cloud-ops-agent*

Verifica che i componenti "Metrics Agent" e "Logging Agent" siano elencati come "In esecuzione", come mostrato nell'output di esempio seguente:

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

Autolog degli agenti

Se l'agente non riesce a importare i log in Cloud Logging, potresti dover ispezionare i log dell'agente localmente sulla VM per risolvere i problemi. Puoi anche utilizzare la rotazione dei log per gestire i self log dell'agente.

Linux

Per esaminare gli autolog scritti in Journald, esegui questo comando:

journalctl -u google-cloud-ops-agent*

Per esaminare i self log scritti sul disco dal modulo di logging, esegui questo comando:

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

Windows

Per ispezionare i self log scritti in Windows Event Logs, esegui questo comando:

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

Per esaminare i self log scritti sul disco dal modulo di logging, esegui questo comando:

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

Per ispezionare i log di Windows Service Control Manager per i servizi Ops Agent, esegui questo comando:

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

Visualizza l'utilizzo e la diagnostica delle metriche in Cloud Monitoring

La pagina Gestione delle metriche di Cloud Monitoring fornisce informazioni che possono aiutarti a controllare l'importo speso per le metriche addebitabili senza influire sull'osservabilità. La pagina Gestione delle metriche riporta le seguenti informazioni:

  • Volumi di importazione per la fatturazione basata sia su byte che su campioni, nei domini delle metriche e per singole metriche.
  • Dati su etichette e cardinalità delle metriche.
  • Utilizzo di metriche nei criteri di avviso e nelle dashboard personalizzate.
  • Percentuale di errori di scrittura delle metriche.

Per visualizzare la pagina Gestione delle metriche, segui questi passaggi:

  1. Nella console Google Cloud, vai alla pagina  Gestione delle metriche:

    Vai a Gestione delle metriche

    Se utilizzi la barra di ricerca per trovare questa pagina, seleziona il risultato con il sottotitolo Monitoring.

  2. Nella barra degli strumenti, seleziona la finestra temporale. Per impostazione predefinita, la pagina Gestione delle metriche mostra informazioni sulle metriche raccolte il giorno precedente.

Per saperne di più sulla pagina Gestione delle metriche, consulta Visualizzare e gestire l'utilizzo delle metriche.