Scrittura e visualizzazione dei log

In questa pagina vengono descritti i log disponibili per le app App Engine e come scrivere, correlare e visualizzare le voci di log.

App Engine raccoglie due tipi di log:

  • Log delle richieste: log delle richieste inviate alla tua app. Per impostazione predefinita, App Engine emette automaticamente una voce di log per ogni richiesta HTTP ricevuta da un'app.

  • Log dell'app: voci di log emesse da un'app di App Engine in base alle voci di log scritte in un framework o file supportato.

App Engine invia automaticamente sia i log delle richieste sia i log delle app all'agente Cloud Logging.

Scrittura dei log delle app

App Engine emette automaticamente i log per le richieste inviate alla tua app, quindi non è necessario scrivere i log delle richieste. Questa sezione illustra come scrivere i log dell'app.

Quando scrivi i log dell'app dall'app App Engine, questi vengono raccolti automaticamente da Cloud Logging, purché vengano scritti utilizzando i seguenti metodi:

Integra con Cloud Logging

Puoi integrare la tua app App Engine con Cloud Logging. Questo approccio consente di utilizzare tutte le funzionalità offerte da Cloud Logging e richiede solo poche righe di codice specifico di Google.

Scrivi log strutturati in stdout e stderr

Per impostazione predefinita, App Engine utilizza la libreria client di Cloud Logging per inviare i log. Tuttavia, questo metodo non supporta il logging strutturato. Puoi scrivere log strutturati solo utilizzando stdout/stderr. Inoltre, puoi inviare stringhe di testo a stdout e stderr. Per impostazione predefinita, il payload di log è una stringa di testo archiviata nel campo textPayload della voce di log. Le stringhe vengono visualizzate come messaggi in Esplora log, nella riga di comando e nell'API Cloud Logging e sono associate al servizio App Engine e alla versione da cui sono state emesse.

Per ottenere più valore dai log, puoi filtrare queste stringhe in Esplora log in base al livello di gravità. Per filtrare queste stringhe, devi formattarle come dati strutturati. Per farlo, scrivi i log sotto forma di una singola riga di JSON serializzato. App Engine rileva e analizza questa riga JSON serializzata e la inserisce nel campo jsonPayload della voce di log anziché in textPayload.

I log stdout e stderr dell'ambiente flessibile vengono inviati a Cloud Logging utilizzando l'agente Logging legacy in esecuzione nelle istanze di macchine virtuali. L'agente Logging viene eseguito con risorse limitate e i log scritti vengono ruotati dopo aver superato il limite di 10 MB. Se la frequenza con cui i log vengono scritti in stdout e stderr è superiore alla frequenza con cui i log vengono letti dall'agente Logging, i log possono essere ruotati prima che vengano inviati a Cloud Logging. Se non vuoi perdere i log, usa Cloud Logging.

Campi JSON speciali nei messaggi

Quando fornisci un log strutturato come dizionario JSON, alcuni campi speciali vengono eliminati da jsonPayload e scritti nel campo corrispondente nel LogEntry generato, come descritto nella documentazione relativa ai campi speciali.

Ad esempio, se il file JSON include una proprietà severity, viene rimosso da jsonPayload e viene visualizzato come severity della voce di log. La proprietà message viene utilizzata come testo visualizzato principale della voce di log, se presente.

Correla i log delle richieste con i log delle app

Dopo aver formattato le voci come oggetto JSON e fornito metadati specifici, puoi abilitare i filtri e la correlazione con i log delle richieste. Per correlare le voci di log delle richieste con quelle dell'app, devi disporre dell'identificatore di traccia della richiesta. Segui le istruzioni per correlare i messaggi di log:

  1. Estrai l'identificatore della traccia dall'intestazione della richiesta X-Cloud-Trace-Context.
  2. Nella voce di log strutturato, scrivi l'ID in un campo denominato logging.googleapis.com/trace. Per ulteriori informazioni sull'intestazione X-Cloud-Trace-Context, consulta Forzare il tracciamento di una richiesta.

Per visualizzare i log correlati, consulta Visualizzare le voci di log correlate in Esplora log.

visualizza i log

Puoi visualizzare i log delle app e delle richieste in diversi modi:

Utilizza Esplora log

Puoi visualizzare i log delle app e delle richieste utilizzando Esplora log:

  1. Vai a Esplora log nella console Google Cloud:

    Vai a Esplora log

  2. Seleziona un progetto Google Cloud esistente nella parte superiore della pagina.

  3. In Tipo di risorsa, seleziona Applicazione GAE.

Puoi filtrare Esplora log in base al servizio, alla versione e ad altri criteri di App Engine. Puoi anche cercare voci specifiche nei log. Per maggiori dettagli, consulta Utilizzo di Esplora log.

Se invii semplici voci di testo all'output standard, non puoi utilizzare il visualizzatore log per filtrare le voci dell'app in base alla gravità, né visualizzare quali log dell'app corrispondono a richieste specifiche. Puoi continuare a utilizzare altri tipi di filtri in Esplora log, come testo e timestamp.

Visualizza le voci di log correlate in Esplora log

In Esplora log, per visualizzare le voci di log figlio correlate a una voce di log padre, espandi la voce di log.

Ad esempio, per visualizzare le voci del log delle richieste di App Engine e delle applicazioni, segui questi passaggi:

  1. Nel pannello di navigazione della console Google Cloud, seleziona Logging, quindi Esplora log:

    Vai a Esplora log

  2. In Tipo di risorsa, seleziona Applicazione GAE.

  3. Per visualizzare e correlare i log delle richieste, in Nome log seleziona request_log. In alternativa, per creare la correlazione in base ai log delle richieste, fai clic su Correla per e seleziona request_log.

    Correlazione dei log

  4. Nel riquadro Risultati delle query, fai clic su Espandi per espandere una voce di log. All'espansione, ogni log delle richieste mostrerà i log delle app associati.

Dopo aver creato un filtro per i log, ogni log delle richieste mostra i log delle app corrispondenti come log figlio. Esplora log lo raggiunge mettendo in relazione il campo trace nei log dell'app e un determinato log delle richieste, supponendo che l'applicazione utilizzi la libreria google-cloud-logging.

L'immagine seguente mostra i log delle app raggruppati in base al campo trace:

Le voci di log dell'app sono nidificate nella voce di log delle richieste.

Utilizza Google Cloud CLI

Per visualizzare i log di App Engine dalla riga di comando, utilizza questo comando:

gcloud app logs tail

Per ulteriori informazioni, consulta gcloud app logs tail.

Lettura dei log in modo programmatico

Se vuoi leggere i log in modo programmatico, puoi utilizzare uno di questi metodi:

Prezzi, quote e criterio di conservazione dei log

Per informazioni sui prezzi applicabili sia ai log delle richieste sia delle app, consulta Prezzi per Cloud Logging.

Per il criterio di conservazione dei log e la dimensione massima delle voci di log, consulta Quote e limiti. Se vuoi archiviare i log per un periodo più lungo, puoi esportarli in Cloud Storage. Puoi anche esportare i log in BigQuery e Pub/Sub per ulteriori elaborazioni.

Gestione dell'utilizzo delle risorse di log

Puoi controllare la quantità di attività di logging nei log dell'app scrivendo un numero maggiore o minore di voci nel codice dell'app. I log delle richieste vengono creati automaticamente. Per gestire il numero di voci di log delle richieste associate alla tua app, utilizza la funzionalità di esclusione dei log di Cloud Logging.

Problemi noti

Di seguito sono riportati alcuni problemi di logging nei runtime di seconda generazione:

  • A volte le voci di log dell'app non sono correlate al log delle richieste. Questo si verifica la prima volta che l'app riceve una richiesta e ogni altra volta che App Engine scrive messaggi di stato nel log dell'app. Per ulteriori informazioni, visita la pagina https://issuetracker.google.com/issues/138365527.

  • Quando esegui il routing dei log dal sink di log a Cloud Storage, la destinazione Cloud Storage contiene solo i log delle richieste. App Engine scrive i log delle app in cartelle diverse.

  • BigQuery non riesce a importare i log a causa del campo @type nei log delle richieste. Questo interrompe il rilevamento automatico dello schema, poiché BigQuery non consente l'uso di @type nei nomi dei campi. Per risolvere il problema, devi definire manualmente lo schema e rimuovere il campo @type dai log delle richieste.

  • Se utilizzi le API REST di logging, un thread in background scrive i log in Cloud Logging. Se il thread principale non è attivo, l'istanza non ottiene il tempo di CPU, il che causa l'arresto del thread in background. Il tempo di elaborazione del log è in ritardo. A un certo punto, l'istanza viene rimossa e tutti i log non inviati andranno persi. Per evitare di perdere i log, utilizza una delle seguenti opzioni:

    • Configura l'SDK di Cloud Logging per l'utilizzo di gRPC. Con gRPC, i log vengono inviati immediatamente a Cloud Logging. Tuttavia, questo può aumentare i limiti di CPU richiesti.
    • Invia messaggi di log a Cloud Logging utilizzando stdout/stderr. Questa pipeline si trova all'esterno dell'istanza di App Engine e non viene limitata.

Passaggi successivi

  • Consulta Monitorare la latenza degli avvisi per scoprire come utilizzare Cloud Logging per visualizzare i log per gli errori di debug e come utilizzare Cloud Trace per comprendere la latenza delle app.