Migrazione a Cloud Logging

Il logging nei runtime di seconda generazione è diverso da quello della prima generazione. Uno dei principali cambiamenti dell'upgrade a runtime più recenti è che il logging preintegrato con App Engine non è supportato nei runtime di seconda generazione e i log non sono correlati automaticamente. Se stai eseguendo la migrazione ai runtime di seconda generazione, devi utilizzare la libreria client di Cloud Logging.

Questa guida descrive come aggiornare l'app per utilizzare Cloud Logging e ottenere quasi le stesse funzionalità di filtro e correlazione dei log disponibili con l'integrazione di logging in App Engine.

Cloud Logging è un sistema di gestione dei log in tempo reale con supporto di archiviazione, ricerca, analisi e monitoraggio. Cloud Logging raccoglie automaticamente i log dalle risorse Google Cloud. Puoi anche raccogliere log da applicazioni, risorse on-premise e risorse di altri cloud provider.

Differenze principali

La seguente tabella illustra le differenze nel logging tra runtime di prima e di seconda generazione:

	Runtime di prima generazione	Runtime di seconda generazione
Log delle richieste e delle app (chiamati anche log delle applicazioni)	App Engine incorpora tutti i log delle app nel log delle richieste. L'accesso nei runtime di prima generazione utilizza il campo protoPayload.line.logMessage del log delle richieste per incorporare i log dell'app.	App Engine non incorpora i log delle app nel log delle richieste associato. App Engine omette l'attributo protoPayload.line nel log delle richieste. I log delle app vengono instradati in base al metodo di logging: stdout e stderr: instrada i log come print() a logs/stdout o logs/stderr. Modulo di logging di Python dopo la configurazione del client di Cloud Logging: instrada tutti i log scritti dal modulo di logging radice di Python, come logging.info() e logging.error(), a logs/python. Se la libreria client di Cloud Logging per Python non è configurata per la correlazione, il modulo di logging radice di Python viene instradato a logs/stderr per impostazione predefinita.
Visualizzazione dei log in Esplora log	I runtime di prima generazione contengono un solo tipo di log, appengine.googleapis.com/request_log. Quando espandi un log delle richieste, puoi visualizzare i log dell'app nidificati al di sotto.	I runtime di seconda generazione includono i log di più tipi di log, ad esempio i log delle richieste in appengine.googleapis.com/request_log, stdout, stderr, logs/python e molti altri, a seconda del modo in cui la tua app emette i log. I log interni di Google sono disponibili anche in /var/log/google_init.log. Poiché i log delle app non sono correlati automaticamente ai log delle richieste, sono necessari passaggi aggiuntivi per visualizzare la visualizzazione nidificata dei log delle richieste e delle app in Esplora log. Per maggiori informazioni, consulta Correlare i log delle richieste con i log delle app e Visualizzare i log correlati in Esplora log.
Integrazione con Cloud Trace	Integrazione automatica con Cloud Trace per la raccolta dei dati di latenza.	Devi integrare manualmente l'app con Cloud Trace per raccogliere i dati relativi alla latenza da App Engine. Per maggiori informazioni, consulta Strumento per Cloud Trace.
Correlazione livello di errore	Registra l'errore generato nei log delle richieste di App Engine con un livello di gravità ERROR. Error Reporting correla automaticamente questi dettagli nella dashboard di Error Reporting.	Per impostazione predefinita, App Engine non integra Error Reporting nei runtime di seconda generazione. Per configurare l'integrazione di logging con Error Reporting, consulta Aggiungere strumenti alle app utilizzando le librerie client .
Livello di gravità	Esplora log assegna un livello di gravità ai log delle richieste e il livello di gravità riflette la massima gravità di qualsiasi voce di log dell'app correlata alla voce di log della richiesta. Ad esempio, se una richiesta comporta l'emissione di una voce di log di avviso da parte della tua app, Esplora log mostrerà un'icona di avviso accanto alla voce di log delle richieste. Quando espandi la voce della richiesta, vedi la voce di log di avviso nidificata all'interno della voce della richiesta.	Per impostazione predefinita, tutti i log delle richieste hanno una gravità DEFAULT o INFO. Anche se i log delle richieste sono correlati ai log delle app e Esplora log è configurato per visualizzare i log correlati, i log delle richieste non riflettono la gravità dei log delle app associati.
API Logservice	L'API Logservice fa parte dell'SDK dei servizi in bundle.	L'API Logservice è stata rimossa dall'SDK dei servizi in bundle. Per saperne di più, consulta l'elenco delle API disponibili.

Prima di avviare la migrazione

1. Abilita l'API Cloud Logging nel progetto che contiene la tua app.

   Abilitare l'API

2. Assicurati che la tua app abbia l'autorizzazione per scrivere log.

   Per impostazione predefinita, l'account di servizio predefinito della tua app è autorizzato a scrivere log.

   Se la tua app utilizza un account di servizio diverso o se hai modificato le autorizzazioni per l'account di servizio predefinito, assicurati che l'account che utilizzi disponga dell'autorizzazione logging.logEntries.create per scrivere i log.

3. Acquisisci familiarità con i diversi tipi di log in App Engine.

Panoramica del processo di migrazione

Per eseguire la migrazione dell'app per utilizzare Cloud Logging:

1. Installa le librerie client di Cloud per Cloud Logging
2. Scrivi log con Cloud Logging
3. Mettere in correlazione i log delle richieste con i log delle app
4. Visualizza i log
5. Testare l'app

Installazione delle librerie client di Cloud per Cloud Logging

Per installare e aggiornare i file di configurazione, aggiungi le librerie client di Cloud per Cloud Logging all'elenco delle dipendenze nel file requirements.txt, come segue:

google-cloud-logging

Scrivi log con il modulo di logging Python standard

In ogni file che scrive le voci di log:

1. Importare la libreria client di Cloud Logging.
2. Crea l'istanza del client Cloud Logging.
3. Esegui il metodo setup_logging() del client Cloud Logging, che collega il listener predefinito come gestore di logging per il logger radice Python.

Ad esempio:

# Imports the Cloud Logging client library
import google.cloud.logging

# Instantiates a client
client = google.cloud.logging.Client()

# Retrieves a Cloud Logging handler based on the environment
# you're running in and integrates the handler with the
# Python logging module. By default this captures all logs
# at INFO level and higher
client.setup_logging()

Una volta collegato il gestore, tutti i log a livello INFO o superiore emessi nell'applicazione verranno inviati a Logging per impostazione predefinita:

# Imports Python standard library logging
import logging

# The data to log
text = "Hello, world!"

# Emits the data using the standard logging module
logging.warning(text)

Correlare i log delle richieste con i log delle app

Alcune funzionalità disponibili nei runtime di prima generazione, come la correlazione automatica dei log delle richieste con i log delle app, non sono disponibili nei runtime di seconda generazione.

Le app che utilizzano runtime di seconda generazione possono ottenere un comportamento di logging nidificato simile a quello dei runtime di prima generazione in due modi:

• Configurazione del client Cloud Logging nell'applicazione e correlazione dei log.
• Utilizzo di un identificatore trace con stdout e stderr.

Il comportamento di logging nei runtime di prima e di seconda generazione varia nei seguenti aspetti:

• Nei runtime di prima generazione, App Engine incorpora tutti i log delle app emessi durante la gestione di una richiesta nel campo protoPayload.line.logMessage del log delle richieste. Questi log sono visibili in Esplora log fino al giorno appengine.googleapis.com/request_log.

  L'immagine seguente mostra i log dell'app e delle richieste correlati nei runtime di prima generazione:

  

• Nei runtime di seconda generazione, App Engine omette l'attributo protoPayload.line nel log delle richieste. I contenuti dei log dell'app non sono presenti nei log delle richieste JSON in Esplora log. Ogni log dell'app verrà visualizzato separatamente in base al relativo nome in Esplora log.

  L'immagine seguente mostra log delle app e delle richieste separati nei runtime di seconda generazione:

  

Le seguenti sezioni descrivono come utilizzare il client Cloud Logging o il logging strutturato con stdout e stderr per la correlazione dei log.

Utilizza il modulo di logging Python

Per aggiungere la correlazione delle richieste ai log dell'app registrati dal modulo di logging Python, configura la libreria client di Cloud Logging.

Quando esegui il metodo client.setup_logging() all'avvio dell'applicazione, questo metodo aggiunge il campo trace e i dettagli della richiesta HTTP ai log dell'app scritti dal modulo Python logging, come logging.info() e logging.error(). Questi log vengono instradati a logs/python.

App Engine aggiunge anche questo campo trace al log delle richieste associato, il che consente di visualizzare le voci di log correlate in Esplora log.

Utilizza stdout e stderr

Se utilizzi stdout e stderr per scrivere voci di log, queste vengono visualizzate in Esplora log. Tuttavia, per abilitare il filtro e la correlazione con i log delle richieste, devi formattare le voci come oggetto JSON e fornire metadati specifici. Per ulteriori informazioni su questo approccio, consulta la sezione Logging strutturato. Per i log dell'app strutturati, la correlazione delle voci nel log dell'app con il log delle richieste richiede l'identificatore di traccia della richiesta. Segui le istruzioni per correlare i messaggi di log:

1. Estrai l'identificatore 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 maggiori informazioni sull'intestazione X-Cloud-Trace-Context, consulta Forzare il tracciamento di una richiesta.

Visualizza i log

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

• Utilizza Esplora log di Cloud Logging nella console Google Cloud.
• Utilizza Google Cloud CLI per visualizzare i log mediante gcloud.
• Leggi i log in modo programmatico utilizzando vari metodi.

Usa Esplora log

Puoi visualizzare i log delle tue 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 App Engine, alla versione e ad altri criteri. Puoi anche cercare voci specifiche nei log. Per maggiori dettagli, consulta Utilizzo di Esplora log.

Se invii voci di testo semplici all'output standard, non puoi utilizzare il visualizzatore log per filtrare le voci delle app in base alla gravità, né vedere quali log delle app corrispondono a richieste specifiche. Puoi comunque utilizzare altri tipi di filtri in Esplora log, ad esempio 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 voce di log delle richieste di App Engine e le voci dei log dell'applicazione, 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 eseguire la correlazione in base ai log delle richieste, fai clic su Correla per e seleziona request_log.

   

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

Dopo aver creato un filtro per i log, ogni log delle richieste mostra i log dell'app corrispondenti come log figlio. Esplora log riesce a raggiungere questo obiettivo mettendo in correlazione il campo trace nei log dell'app con un determinato log delle richieste, supponendo che l'applicazione utilizzi la libreria google-cloud-logging.

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

Utilizzare Google Cloud CLI

Per visualizzare i log di App Engine dalla riga di comando, utilizza il seguente 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:

• Utilizza un sink di log in Pub/Sub e uno script per il pull da Pub/Sub.
• Chiama l'API Cloud Logging tramite la libreria client per il tuo linguaggio di programmazione.
• Chiama direttamente gli endpoint REST dell'API Cloud Logging.

Testare l'applicazione

La migrazione ha esito positivo se sei in grado di eseguire il deployment dell'app senza errori. Per verificare che Cloud Logging funzioni, segui questi passaggi:

1. Vai a Esplora log ed espandi una voce di log delle richieste.

   Vai a Esplora log

2. Assicurati che i log dell'app generati dall'app durante l'elaborazione di una richiesta siano nidificati all'interno del log delle richieste.

3. Se tutti gli endpoint delle app funzionano come previsto, utilizza la suddivisione del traffico per accelerare lentamente il traffico dell'app aggiornata. Monitora attentamente l'app per rilevare eventuali problemi prima di indirizzare più traffico all'app aggiornata.