La registrazione nei runtime di seconda generazione è diversa da quella nei runtime di prima generazione. Una delle modifiche più importanti durante l'upgrade a runtime più recenti è che la registrazione preintegrata con App Engine non è supportata nei runtime di seconda generazione e i log non vengono correlati automaticamente. Se esegui la migrazione alle piattaforme di 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 per archiviazione, ricerca, analisi e monitoraggio. Cloud Logging raccoglie automaticamente i log dalle risorse Google Cloud. Puoi anche raccogliere i log dalle tue applicazioni, dalle risorse on-premise e dalle risorse di altri provider cloud.
Differenze principali
La seguente tabella illustra le differenze nella registrazione tra i runtime di prima e 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 dell'app nel log delle richieste. Il logging nei runtime di prima generazione utilizza il campo protoPayload.line.logMessage del log delle richieste per incorporare i log delle app. |
App Engine non incorpora
i log delle app nel log delle richieste associato.
App Engine omette l'attributo protoPayload.line nel log della richiesta.
I log delle app vengono indirizzati in base al metodo di registrazione:
|
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 vedere i log dell'app nidificati al suo interno.
|
I runtime di seconda generazione includono log di più tipi, ad esempio log delle richieste in appengine.googleapis.com/request_log , stdout , stderr , logs/python e molti altri, a seconda di come 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 Logs Explorer. Per ulteriori informazioni, consulta Correlare i log delle richieste con i log delle app e Visualizzare i log correlati in Esplora log. |
Integrazione di Cloud Trace | Integrazione automatica con Cloud Trace per la raccolta dei dati sulla latenza. | Per raccogliere i dati sulla latenza da App Engine, devi integrare manualmente la tua app con Cloud Trace. Per ulteriori informazioni, consulta Strumento per Cloud Trace. |
Correlazione del 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 del logging con Error Reporting, consulta Eseguire il monitoraggio delle 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 gravità più alta di qualsiasi voce di log dell'app correlata alla voce di log della richiesta. Ad esempio, se una richiesta fa sì che la tua app emetta una voce di log di avviso, Esplora log mostrerà un'icona di avviso accanto alla voce di log della richiesta. Quando espandi la voce di richiesta, viene visualizzata la voce di log dell'avviso nidificata all'interno della voce di richiesta. | Per impostazione predefinita, tutti i log delle richieste hanno una gravità pari a DEFAULT o INFO .
Anche se i log delle richieste sono correlati ai log delle app e lo strumento 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 ulteriori informazioni, consulta l'elenco delle API disponibili. |
Prima di iniziare la migrazione
Abilita l'API Cloud Logging nel progetto che contiene la tua app.
Assicurati che l'app abbia l'autorizzazione a scrivere log.
Per impostazione predefinita, l'account di servizio predefinito della tua app ha l'autorizzazione per scrivere i 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.Acquisisci familiarità con i diversi tipi di log in App Engine.
Panoramica del processo di migrazione
Per eseguire la migrazione dell'app in modo che utilizzi Cloud Logging:
- Installa le librerie client di Cloud per Cloud Logging
- Scrivere log con Cloud Logging
- Correlare i log delle richieste con i log delle app
- Visualizza i log
- Testare l'app
Installazione delle librerie client 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
, ad esempio:
google-cloud-logging
Scrivere log con il modulo di logging standard di Python
In ogni file che scrive voci di log:
- Importa la libreria client Cloud Logging.
- Crea un'istanza del client Cloud Logging.
- Esegui il metodo
setup_logging()
del client Cloud Logging, che associa il suo ascoltatore predefinito come gestore di logging per il logger principale di Python.
Ad esempio:
Dopo aver collegato il gestore, tutti i log a livello INFO
o superiore
emessi nella tua applicazione verranno inviati a Logging per impostazione predefinita:
Metti in correlazione 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 registrazione nidificato simile a quello dei runtime di prima generazione in uno dei seguenti modi:
- Configura il client Cloud Logging nella tua applicazione e correla i log.
- Utilizzo di un identificatore
trace
constdout
estderr
.
Il comportamento di registrazione nei runtime di prima e seconda generazione è diverso nei seguenti modi:
Nei runtime di prima generazione, App Engine incorpora tutti i log dell'app emessi durante il trattamento di una richiesta nel campo
protoPayload.line.logMessage
del log della richiesta. Questi log sono visibili in Esplora log tramiteappengine.googleapis.com/request_log
.L'immagine seguente mostra i log delle richieste e delle app 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 singolarmente in base al nome in Esplora log.L'immagine seguente mostra log di richieste e app separati nei runtime di seconda generazione:
Le sezioni seguenti spiegano come utilizzare il client Cloud Logging o il logging strutturato con stdout
e stderr
per correlare i log.
Utilizzare il modulo di logging di Python
Per aggiungere la correlazione delle richieste ai log dell'app registrati dal modulo di logging di 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 logging
di Python, ad esempio logging.info()
e logging.error()
. Questi
log vengono instradati a logs/python
.
App Engine aggiunge questo campo trace
anche al log delle richieste associato,
in modo da poter 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 maggiori informazioni su questo approccio, consulta Scrivere log strutturati in stdout e stderr.
Questo approccio aggiunge l'identificatore della traccia della richiesta nei log delle applicazioni:
- Estrazione dell'identificatore della traccia dall'intestazione della richiesta
X-Cloud-Trace-Context
. - Scrivere l'ID in un campo denominato
logging.googleapis.com/trace
nella voce di log strutturato. Per ulteriori informazioni sull'intestazioneX-Cloud-Trace-Context
, consulta Forzare il monitoraggio di una richiesta.
Visualizza i log
Puoi visualizzare i log dell'app e i log delle richieste in diversi modi:
- Utilizza Esplora log da Cloud Logging nella console Google Cloud.
- Utilizza Google Cloud CLI per visualizzare i log utilizzando gcloud.
- Leggi i log in modo programmatico utilizzando vari metodi.
Utilizzare Esplora log
Puoi visualizzare i log dell'app e delle richieste utilizzando Esplora log:
Vai a Esplora log nella console Google Cloud:
Seleziona un progetto Google Cloud esistente nella parte superiore della pagina.
In Tipo di risorsa, seleziona GAE Application.
Puoi filtrare Logs Explorer in base al servizio App Engine, alla versione e ad altri criteri. Puoi anche cercare nei log voci specifiche. Per i dettagli, consulta Utilizzare Esplora log.
Se invii voci di testo semplici all'output standard, non puoi utilizzare Log Visualizzatore per filtrare le voci dell'app in base alla gravità né vedere quali log dell'app corrispondono a richieste specifiche. Puoi comunque utilizzare altri tipi di filtri in Esplora log, ad esempio testo e timestamp.
Visualizzare le voci di log correlate in Esplora log
In Esplora log, per visualizzare le voci di log secondarie correlate a una voce di log principale, espandi la voce di log.
Ad esempio, per visualizzare voce di log delle richieste di App Engine e le voci del log dell'applicazione:
Nel pannello di navigazione della console Google Cloud, seleziona Logging, quindi Esplora log:
In Tipo di risorsa, seleziona GAE Application.
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 in base a e seleziona request_log.
Nel riquadro Risultati delle query, per espandere una voce di log, fai clic su Espandi. Se viene espanso, 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 secondari. Esplora log ottiene questo risultato correlando 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
:
Utilizza 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 dei seguenti metodi:
- Utilizza un destinatario dei log in Pub/Sub e uno script per eseguire 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.
Testa la tua app
La migrazione è riuscita se riesci a eseguire il deployment dell'app senza errori. Per verificare che Cloud Logging funzioni, segui questi passaggi:
Vai a Esplora log ed espandi una voce di log delle richieste.
Assicurati che i log dell'app generati dall'app durante l'elaborazione di una richiesta siano nidificati all'interno del log delle richieste.
Se tutti gli endpoint dell'app funzionano come previsto, utilizza la suddivisione del traffico per aumentare lentamente il traffico per l'app aggiornata. Monitora attentamente l'app per rilevare eventuali problemi prima di indirizzare più traffico all'app aggiornata.