Risolvere i problemi dell'agente Logging

Questa pagina fornisce istruzioni per la risoluzione dei problemi comuni riscontrati con l'installazione o l'interazione con l'agente Logging.

Elenco di controllo

Se hai difficoltà a installare o utilizzare l'agente Logging, Ecco alcuni aspetti da verificare:

• Se i comandi di installazione di Linux generano errori, assicurati di anteporre sudo ai comandi di installazione.

• Verifica che il servizio dell'agente sia in esecuzione sull'istanza VM:

  • Per una VM Windows, utilizza il seguente comando PowerShell:

    Get-Service -Name StackdriverLogging
    

    Cerca un servizio denominato Stackdriver Logging. Se l'agente non è in esecuzione, potrebbe essere necessario riavviarlo.

  • Per una VM Linux, utilizza il seguente comando:

    sudo service google-fluentd status
    

    Se l'agente non è in esecuzione, potrebbe essere necessario riavviarlo utilizzando il seguente comando:

    sudo service google-fluentd restart
    

    Se il riavvio non va a buon fine e l'output del log mostra "Disattivato tramite metadati", è probabile che tu stia eseguendo un'immagine da Google Cloud Marketplace, dove l'agente Logging è disattivato per impostazione predefinita. La chiave dei metadati dell'istanza google-logging-enable controlla lo stato di attivazione dell'agente Logging, dove un valore 0 disattiva l'agente. Per riattivare l'agente, rimuovi la chiave google-logging-enable o imposta il suo valore su 1. Per ulteriori informazioni, consulta Creare un'istanza con l'agente di logging disattivato.

    Se l'agente non è disattivato tramite i metadati, reinstallalo. Consulta la sezione seguente, Reinstallare l'agente Logging.

• Controlla se l'agente ha scritto messaggi di errore nei log.

  • Su Windows, a partire dalla versione v1-9, l'agente Logging salva i suoi log in C:\Program Files (x86)\Stackdriver\LoggingAgent\fluentd.log.

    Non è possibile recuperare i log delle versioni precedenti dell'agente.

  • Su Linux, l'agente Logging è un pacchetto fluentd e registra i messaggi in /var/log/google-fluentd/google-fluentd.log:

    • Se visualizzi errori HTTP 429, potresti aver superato le quote dell'API Logging. Puoi visualizzare la quota disponibile selezionando API e servizi > Dashboard nella console Google Cloud. Scegli l'API Logging.

    • Se riscontri problemi di accesso o autorizzazione all'API, vai a Verificare le credenziali di Compute Engine.

• Se l'agente sembra funzionare normalmente, ma non ricevi dati, devi verificare che l'agente li invii al progetto corretto. Consulta la sezione seguente, Verifica delle credenziali di Compute Engine.

• Se l'agente non riesce ad autorizzarsi, verifica se le credenziali per la chiave privata sono mancanti o non valide.

Verifica l'installazione dell'agente

Per verificare che l'installazione sia andata a buon fine, cerca la voce del log di test dell'agente in Esplora log.

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

   Vai a Esplora log

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

2. Nella parte superiore della pagina, scegli il progetto contenente l'istanza VM:

   • Per le istanze VM Compute Engine, scegli il progetto Google Cloud che contiene l'istanza VM.
   • Per le istanze VM Amazon EC2, scegli il progetto Google Cloud a cui stai inviando i log.

3. Nelle schede delle finestre, scegli la risorsa per l'istanza VM:

   • Per Compute Engine, scegli Istanza VM GCE.
   • Per Amazon EC2, scegli Istanza AWS EC2.
   • Seleziona syslog (Linux), fluent.info (Windows) o Tutti i log.

Se viene visualizzata la voce di log "gRPC inviato correttamente all'API Logging", l'installazione dell'agente è completata. Questo messaggio viene generato una volta quando l'agente viene installato e anche ogni volta che viene riavviato.

Per ulteriori informazioni su Esplora log, consulta Utilizzare Esplora log.

Testa l'agente

Se sospetti che l'agente non funzioni, verifica che sia in esecuzione e prova a inviare un messaggio di prova a Logging:

Trovare il messaggio di prova

Dopo aver inviato un messaggio di prova, cercalo in Esplora log:

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

   Vai a Esplora log

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

2. Nella parte superiore della pagina, scegli il progetto contenente l'istanza VM:

   • Per le istanze VM Compute Engine, scegli il progetto Google Cloud che contiene l'istanza VM.
   • Per le istanze VM Amazon EC2, scegli il progetto Google Cloud a cui stai inviando i log.

3. Nelle schede delle finestre, scegli la risorsa per l'istanza VM:

   • Per Compute Engine, scegli Istanza VM GCE.
   • Per Amazon EC2, scegli Istanza AWS EC2.
   • Seleziona syslog (Linux), fluent.info (Windows) o Tutti i log.

4. Dovresti vedere una voce di log con il messaggio di test. In questo caso, l'agente di logging funziona correttamente.

Verifica le credenziali di Compute Engine

Affinché un'istanza VM Compute Engine esegua l'agente senza credenziali con chiave privata, l'istanza deve avere ambiti di accesso appropriati e l'identità dell'account di servizio utilizzata dall'istanza deve avere autorizzazioni IAM appropriate.

Quando crei un'istanza VM, le impostazioni predefinite dell'ambito e dell'account di servizio sono sufficienti per eseguire gli agenti. Le istanze molto vecchie o quelle per le quali hai modificato le impostazioni predefinite potrebbero non avere credenziali idonee.

Impossibile caricare le credenziali predefinite

Se sono presenti Could not load the default credentials errori nel file di log di registrazione, significa che l'agente potrebbe non riuscire a connettersi al server di metadati di Compute Engine.

Il log degli errori è il seguente:

Starting google-fluentd 1.8.4: /opt/google-fluentd/embedded/lib/ruby/gems/2.6.0/gems/googleauth-0.9.0/lib/googleauth/application_default.rb:74:in `get_application_default': Could not load the default credentials. Browse to (RuntimeError) https://developers.google.com/accounts/docs/application-default-credentials for more information.

Una potenziale causa di questo problema è la configurazione di un proxy personalizzato nella VM. Per risolvere il problema, consulta le istruzioni di configurazione del proxy per escludere il server di metadati di Compute Engine (metadata.google.internal o 169.254.169.254) dal passaggio attraverso il proxy. Se l'errore persiste, rimuovi l'account di servizio Compute Engine predefinito dalla VM e aggiungilo di nuovo.

Verifica gli ambiti di accesso

Per verificare gli ambiti di accesso:

1. Nella console Google Cloud, vai alla pagina Istanze VM:

   Vai a Istanze VM

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

2. Fai clic sul nome dell'istanza VM. Viene visualizzata la pagina dei dettagli dell'istanza.

3. Nella sezione Ambiti di accesso API Cloud, fai clic su Dettagli per visualizzare l'elenco delle API. Cerca le seguenti voci:

   1. Se vedi "Questa istanza ha accesso API completo a tutti i servizi Google Cloud", significa che i tuoi ambiti di accesso sono adeguati.
   2. Se accanto a API Stackdriver Logging, un nome precedente per l'API Cloud Logging, visualizzi che disponi dell'autorizzazione Sola scrittura o Completa, significa che gli ambiti di accesso della tua istanza sono adeguati per l'agente Cloud Logging.
   3. Se accanto a API Stackdriver Monitoring, un nome precedente per l'API Cloud Monitoring, visualizzi che disponi dell'autorizzazione Sola scrittura o Completa, significa che gli ambiti di accesso della tua istanza sono adeguati per l'agente Cloud Monitoring.

Correggere il problema

Se non disponi di ambiti di accesso adatti nell'istanza Compute Engine, aggiungi gli ambiti di accesso necessari all'istanza.

La tabella seguente mostra gli ambiti pertinenti per gli agenti di logging e monitoraggio:

Verificare l'autorizzazione dell'account di servizio predefinito

Anche se gli ambiti di accesso dell'istanza VM Compute Engine sono adeguati, l'account di servizio predefinito dell'istanza potrebbe non fornire le autorizzazioni IAM corrette per l'agente.

Per verificare l'autorizzazione dell'account di servizio predefinito, inizia individuando l'account di servizio predefinito:

1. Nella console Google Cloud, vai alla pagina Istanze VM:

   Vai a Istanze VM

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

2. Fai clic sul nome dell'istanza VM. Viene visualizzata la pagina dei dettagli dell'istanza.

3. Cerca la voce Account di servizio nella pagina. È elencato il account di servizio predefinito per l'istanza. Potrebbe avere un aspetto simile al seguente:

   [ID]-compute@developer.gserviceaccount.com
   

4. Nella console Google Cloud, vai alla pagina IAM:

   Vai a IAM

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

5. Seleziona Visualizza per: entità. Dovresti vedere un elenco di persone, gruppi e account di servizio. Nella colonna Ruolo sono riportati i ruoli di ciascun principale nel progetto.

6. Nella riga relativa all'account di servizio predefinito dell'istanza, dovresti vedere uno o più ruoli:

   • Se vedi Editor, questo ruolo è adeguato per tutti gli agenti. Il ruolo Editor potrebbe essere concesso automaticamente all'account di servizio predefinito, a seconda della configurazione dei criteri dell'organizzazione.
   • Se vedi Logs Writer (Autore log), questo ruolo è sufficiente per l'agente di logging. Per altri ruoli di Logging che includono l'autorizzazione di scrittura, consulta Controllo dell'accesso per Cloud Logging.
   • Se vedi Scrittore di metriche di monitoraggio, questo ruolo è sufficiente per l'agente Monitoring. Per altri ruoli di monitoraggio che includono l'autorizzazione di scrittura, consulta Controllo dell'accesso per Cloud Monitoring.

Correggere il problema

Se il tuo account di servizio predefinito non dispone di ruoli adeguati, prova a modificarli nella pagina IAM e amministrazione > IAM. Aggiungi i ruoli Logging o Monitoring appropriati per autorizzare gli agenti: Logging > Autore log o Monitoraggio > Autore metriche di monitoraggio.

Verifica le credenziali della chiave privata

Nelle istanze VM Compute Engine, puoi configurare l'agente in modo che utilizzi un account di servizio non predefinito con l'autorizzazione corretta. Nelle istanze VM AWS EC2, devi configurare l'agente in modo che utilizzi un account di servizio di questo tipo.

Per configurare l'agente in questo modo, devi creare credenziali con chiave privata per l'account di servizio designato e fornirle all'agente.

1. L'agente cerca una variabile di ambiente,GOOGLE_APPLICATION_CREDENTIALS, che contiene il nome di un file che contiene le credenziali della chiave privata.

2. Se la variabile di ambiente non è presente, l'agente cercherà le credenziali in una posizione predefinita:

   Linux

   /etc/google/auth/application_default_credentials.json
   

   Windows

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

3. Se la posizione predefinita non contiene le credenziali, l'agente utilizza le credenziali predefinite dell'applicazione dal server dei metadati.

Le seguenti informazioni ti aiutano a diagnosticare i problemi relativi alle credenziali con chiave privata:

1. La chiave privata è presente?
2. La chiave privata è ancora valida per l'account di servizio?
3. L'account di servizio dispone dei ruoli necessari per l'agente?

Per verificare che le credenziali con chiave privata valide siano installate nell'istanza VM, innanzitutto verifica che il file delle credenziali esista nella posizione prevista e poi verifica che le informazioni nel file delle credenziali siano valide.

Le credenziali sono presenti?

Per verificare se le credenziali dell'account di servizio chiavi privata sono presenti nell'istanza, esegui i seguenti comandi Linux sull'istanza:

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

Se uno dei comandi mostra un file come quello mostrato di seguito, la tua istanza potrebbe avere credenziali della chiave privata valide. Se entrambi i comandi mostrano un file, viene utilizzato il file indicato da 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}"
}

Le discrepanze tra le configurazioni delle credenziali possono causare l'utilizzo da parte dell'agente di credenziali diverse da quelle richieste dal servizio. Ad esempio, se imposti una posizione delle credenziali personalizzata in GOOGLE_APPLICATION_CREDENTIALS nella shell di accesso, ma non imposti la variabile nella configurazione del servizio dell'agente, il servizio cercherà nella posizione predefinita anziché nella posizione personalizzata.

Per controllare o modificare la variabile di ambiente delle credenziali, accedi o imposta GOOGLE_APPLICATION_CREDENTIALS in /etc/default/google-fluentd.

Se non sono presenti file delle credenziali, consulta Aggiunta delle credenziali.

Le credenziali sono valide?

Nel file delle credenziali, project_id è il tuo progetto Google Cloud, client_email identifica l'account di servizio nel progetto e private_key_id identifica la chiave privata nell'account di servizio. Confronta queste informazioni con quelle riportate nella sezione IAM e amministrazione > Account di servizio della console Google Cloud.

Il file delle credenziali non è valido se si verifica una delle seguenti condizioni:

• Stai controllando un'istanza Compute Engine, ma il progetto Google Cloud nel file delle credenziali non è quello che contiene l'istanza.
• Stai controllando un'istanza Amazon EC2, ma il progetto Google Cloud nel file delle credenziali non è il progetto Google Cloud a cui stai inviando i log.
• L'account di servizio elencato non esiste. Potrebbe essere stato eliminato.
• Nell'account di servizio elencato non sono abilitati i ruoli corretti: Scrittore di log per l'agente Cloud Logging e Scrittore di metriche di monitoraggio per l'agente Cloud Monitoring.
• La chiave privata non esiste. Potrebbe essere stata revocata.

Le credenziali possono essere revocate utilizzando la sezione IAM e amministrazione > Account di servizio della console Google Cloud. Se non sono presenti credenziali valide, consulta Aggiunta di credenziali per sostituire quelle esistenti o aggiungerne di nuove.

Se l'account di servizio è corretto, ma la chiave privata è stata revocata, puoi creare una nuova chiave privata e copiarla nella tua istanza. Consulta Creare le chiavi degli account di servizio.

In caso contrario, devi creare un nuovo account di servizio come descritto nella sezione Aggiunta delle credenziali.

Verifica le query di esclusione dei log

Visualizza le query di esclusione correnti per assicurarti che i log che stai cercando non vengano esclusi per errore.

Verifica il firewall

Per verificare se la tua istanza ha accesso a logging.googleapis.com, esegui il seguente comando Linux sull'istanza:

curl -sSL 'https://logging.googleapis.com/$discovery/rest?version=v2' | head

Il completamento del comando può richiedere un po' di tempo se il firewall blocca il traffico in uscita. Output di esempio che indica un problema del firewall:

curl: (7) Failed to connect to 2607:f8b0:4001:c03::5f: Network is unreachable

Consulta la sezione Regole firewall per informazioni su come configurare le regole per il traffico in uscita.

Reinstalla l'agente

L'installazione della versione più recente dell'agente può risolvere molti problemi:

• Se hai la certezza che il problema non riguarda le credenziali, puoi saltare вперед la sezione Installazione su Linux e Windows.

• Per un'installazione completa dell'agente e di eventuali credenziali necessarie, consulta Installazione dell'agente Logging.

Altri problemi comuni

Nella tabella seguente sono elencati alcuni problemi comuni che potresti riscontrare con l'agente Cloud Logging e viene spiegato come risolverli.

Su Linux, l'agente Logging registra gli errori in /var/log/google-fluentd/google-fluentd.log. Su Windows, l'agente Logging registra gli errori in C:\Program Files (x86)\Stackdriver\LoggingAgent\fluentd.log (a partire dalla versione v1-9). La classe di errore Google::APIClient::ClientError indica che esiste un problema con le autorizzazioni o l'accesso all'API.

Potresti iniziare a visualizzare errori dopo l'esecuzione dell'agente. Ad esempio, qualcuno potrebbe aver revocato le autorizzazioni richieste dal progetto o dall'istanza VM.

Limitazione della velocità in bit dei log

La velocità in MB dei log massima che l'agente Logging può elaborare è limitata dalla CPU. L'utilizzo della CPU tende ad aumentare con l'aumento della velocità in bit dei log. Tuttavia, con la configurazione predefinita, l'agente può utilizzare fino a un solo core della CPU. Pertanto, quando la throughput dei log aumenta, l'agente potrebbe raggiungere un limite di utilizzo della CPU. Se questi picchi sono solo temporanei, l'agente Logging memorizza i log in un buffer e successivamente li elabora. Se la produttività dei log rimane costantemente alta, i log potrebbero sforare il buffer e andare persi.

In genere, quando ogni voce di log è costituita da testo non elaborato di 1000 byte e non contiene ulteriore elaborazione del formato, l'agente Logging raggiunge il limite di un core della CPU con circa 5500 voci di log al secondo. Se le voci di log richiedono un'elaborazione avanzata, ad esempio l'analisi JSON o Regex, il numero massimo di voci di log al secondo potrebbe essere inferiore.

Se hai bisogno di una maggiore velocità in termini di log, ti consigliamo di utilizzare Ops Agent. Su Linux, per le voci di log che sono costituite da testo non elaborato di 1000 byte e non richiedono ulteriore elaborazione, Ops Agent può elaborare circa 160.000 voci di log al secondo.

Dimensione massima dei log superata

Se una o più voci di log hanno superato il limite di dimensioni massime, potresti trovare voci nei log di fluentd simili alle seguenti:

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

o

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

Per risolvere questo errore, taglia le voci di log in modo che non superino il limite di dimensione massimo. Ad esempio, il seguente codice campione taglia i log con il tag mytag, con i dati nel 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>

I log sono duplicati

LogEntry.insertID viene aggiunto nella pipeline di elaborazione all'interno dell'agente. Se insertID è diverso tra i log duplicati, significa che i log vengono estratti dai file di log più volte. Questo può accadere in presenza di rotazione dei log o quando il file pos è mancante o danneggiato. Per ridurre le probabilità di questo problema, assicurati che i file di posizione per qualsiasi input in_tail non siano configurati per essere nella cartella /var/log o in altre cartelle in cui potrebbe essere attivata la rotazione dei log.

La pipeline di logging si basa anche sul campo LogEntry.timestamp per deduplicare i log. Assicurati che il timestamp effettivo della voce di log sia analizzato correttamente. Se Fluentd non è configurato per analizzare il timestamp originale dalla voce di log, utilizza l'ora in cui elabora la voce di log. Pertanto, se l'input viene letto più volte, anche se il timestamp nella riga di log è lo stesso, Fluentd potrebbe trattarli come voci di log diverse con timestamp diversi.

Errori ripetuti nei log di controllo: Data points cannot be written more than 24h in the past

Esiste un problema noto che interessa le versioni da 1.8.5 a 1.9.3 (inclusive) che provoca la visualizzazione ripetuta di log come il seguente nei log di controllo dell'accesso ai dati quando l'agente è in esecuzione da più di 24 ore:

Field timeSeries[0].points[0].interval.end_time had an invalid value of "2021-10-20T20:16:34.010866-07:00": Data points cannot be written more than 24h in the past.

La soluzione è eseguire l'upgrade dell'agente alla versione 1.9.4 o successive.

I caratteri Unicode nei log vengono sostituiti da spazi o "�"

Per impostazione predefinita, l'input in_tail prevede che i file di input siano codificati in ASCII, quindi sostituisce qualsiasi carattere non ASCII con uno spazio. Per importare effettivamente i file codificati in UTF-8, devi fornire due opzioni nella configurazione in_tail:

<source>
  @type tail
  …

  encoding UTF-8
  from_encoding UTF-8
</source>

Sono necessarie entrambe le opzioni. Se viene fornita solo l'opzione encoding, i caratteri non ASCII nei log importati verranno sostituiti da "�".

Agente rimosso segnalato dalla console Google Cloud come installato

Dopo aver disinstallato l'agente, la console Google Cloud potrebbe impiegare fino a un'ora per segnalare questa modifica.

L'agente Logging non viene visualizzato nell'elenco Disinstalla un programma di Windows

Per disinstallare l'agente Logging se non è presente nell'elenco Disinstalla un programma del Pannello di controllo di Windows, esegui uninstall.exe dalla directory in cui l'hai installato.