Scrittura e visualizzazione dei log

Questa pagina descrive 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:i log delle richieste inviate all'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 App Engine in base alle voci di log che scrivi in un framework o file supportato.

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

Scrivere log delle app

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

Quando scrivi i log dell'app dalla tua app App Engine, questi vengono rilevati automaticamente da Cloud Logging, a condizione che vengano scritti utilizzando i seguenti metodi:

Integra con Cloud Logging

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

Puoi scrivere log in Cloud Logging dalle applicazioni Python utilizzando il gestore di log Python standard o direttamente la libreria client dell'API Cloud Logging per Python. Quando utilizzi il gestore di log Python standard, devi collegare un gestore Cloud Logging al gestore principale di Python. Per ulteriori informazioni, consulta Configurare Cloud Logging per Python.

Scrivere log strutturati in stdout e stderr

Per impostazione predefinita, App Engine utilizza la libreria client Cloud Logging per inviare i log. Tuttavia, questo metodo non supporta la registrazione strutturata. Puoi scrivere log strutturati solo utilizzando stdout/stderr. Inoltre, puoi inviare stringhe di testo anche a stdout e stderr. Per impostazione predefinita, il payload del log è una stringa di testo memorizzata 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 che le ha emesse.

Per ottenere un valore maggiore 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 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.

Gli snippet riportati di seguito mostrano come scrivere questi log strutturati.

# Uncomment and populate this variable in your code:
# PROJECT = 'The project ID of your Cloud Run service';

# Build structured log messages as an object.
global_log_fields = {}

# Add log correlation to nest all log messages.
# This is only relevant in HTTP-based contexts, and is ignored elsewhere.
# (In particular, non-HTTP-based Cloud Functions.)
request_is_defined = "request" in globals() or "request" in locals()
if request_is_defined and request:
    trace_header = request.headers.get("X-Cloud-Trace-Context")

    if trace_header and PROJECT:
        trace = trace_header.split("/")
        global_log_fields[
            "logging.googleapis.com/trace"
        ] = f"projects/{PROJECT}/traces/{trace[0]}"

# Complete a structured log entry.
entry = dict(
    severity="NOTICE",
    message="This is the default display field.",
    # Log viewer accesses 'component' as jsonPayload.component'.
    component="arbitrary-property",
    **global_log_fields,
)

print(json.dumps(entry))

Nell'ambiente standard di App Engine, la scrittura di log strutturati in stdout e stderr non viene conteggiata ai fini della quota di richieste di importazione dei log al minuto nell'API Cloud Logging.

Campi JSON speciali nei messaggi

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

Ad esempio, se il tuo JSON include una proprietà severity, viene rimossa dal jsonPayload e viene visualizzata come severity della voce di log. La proprietà message viene utilizzata come testo di visualizzazione principale della voce di log, se presente.

Metti in correlazione i log delle richieste con i log delle app

Per impostazione predefinita, i log non sono correlati nei runtime di seconda generazione. Questi ambienti di runtime richiedono l'utilizzo delle librerie client di Cloud. Queste librerie non supportano il nidificazione e richiedono la correlazione dei 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

Dopo aver formattato le voci come oggetto JSON e fornito metadati specifici, puoi attivare il filtro e la correlazione con i log delle richieste. Per correlare le voci di log delle richieste con le voci di log dell'app, devi disporre dell'identificatore della 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 monitoraggio 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 dell'app e i log delle richieste in diversi modi:

Utilizzare Esplora log

Puoi visualizzare i log dell'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 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:

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

    Vai a Esplora log

  2. In Tipo di risorsa, seleziona GAE Application.

  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 in base a e seleziona request_log.

    Correlare i log

  4. 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:

Le voci del 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 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:

Prezzi, quote e criterio di conservazione dei log

Per informazioni sui prezzi applicabili sia ai log delle richieste che a quelli delle app, consulta Prezzi di Cloud Logging.

Per le norme di conservazione dei log e le dimensioni massime 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 un'ulteriore elaborazione.

Gestione dell'utilizzo delle risorse dei log

Puoi controllare la quantità di attività di registrazione nei log dell'app scrivendo più o meno voci dal codice dell'app. I log delle richieste vengono creati automaticamente, quindi per gestire il numero di voci dei 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 registrazione nei runtime di seconda generazione:

  • A volte le voci del log dell'app non sono correlate al log delle richieste. Questo accade la prima volta che l'app riceve una richiesta e ogni 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 inoltri i log dallsink di log a Cloud Storage, la destinazione Cloud Storage contiene solo i log delle richieste. App Engine scrive i log delle app in diverse cartelle.

  • BigQuery non riesce a importare i log a causa del campo @type nei log delle richieste. Ciò interrompe il rilevamento automatico dello schema, poiché BigQuery non consente @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 riceve tempo della CPU, il che causa l'interruzione del thread in background. Il tempo di elaborazione dei log è in ritardo. A un certo punto, l'istanza viene rimossa e gli eventuali log non inviati andranno persi. Per evitare di perdere i log, utilizza una delle seguenti opzioni:

    • Configura l'SDK Cloud Logging in modo che utilizzi gRPC. Con gRPC, i log vengono inviati immediatamente a Cloud Logging. Tuttavia, questo può aumentare i limiti della CPU richiesti.
    • Invia messaggi di log a Cloud Logging utilizzando stdout/stderr. Questa pipeline è al di fuori dell'istanza App Engine e non viene limitata.

Passaggi successivi

  • Consulta Monitora e avvisa sulla latenza per scoprire come utilizzare Cloud Logging per visualizzare i log relativi agli errori di debug e come utilizzare Cloud Trace per comprendere la latenza dell'app.