Scrivi e visualizza i log

Vai Java Node.js PHP Python Ruby

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: 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 delle 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 i 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 spiega come scrivere i log delle app.

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

• Integra con Cloud Logging
• Scrivi log strutturati con stdout e stderr

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 poche righe di codice specifico di Google.

Puoi integrare l'appender Logback o java.util.logging con Cloud Logging. Utilizzando l'appender Logback, puoi utilizzare Cloud Logging con la facciata di logging SLF4J.

Per saperne di più sull'utilizzo di Cloud Logging dalle applicazioni Java con l' appender Logback o il java.util.logging gestore, o per integrare direttamente la libreria Cloud Logging per Java, consulta Configurare Cloud Logging per Java.

Importante: Esplora log non visualizza una voce di log delle app che supera i 16 kilobyte.

Scrivere 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 anche inviare stringhe di testo a stdout e stderr. Per impostazione predefinita, il payload del 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 e alla versione di App Engine 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 una singola riga con serializzazione JSON. App Engine raccoglie 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 log strutturati.

Nota: questi snippet sono stati originariamente scritti per Cloud Run. Sono ugualmente applicabili ad App Engine.

Abilita la registrazione JSON con Logback e SLF4J abilitando Logstash JSON Encoder nella configurazione di logback.xml.

// Add log correlation to nest all log messages beneath request log in Log Viewer.
// TODO(developer): delete this code if you're creating a Cloud
//                  Function and it is *NOT* triggered by HTTP.
String traceHeader = req.headers("x-cloud-trace-context");
if (traceHeader != null && project != null) {
  String trace = traceHeader.split("/")[0];
  MDC.put(
      "logging.googleapis.com/trace",
      String.format("projects/%s/traces/%s", project, trace));
}
// -- End log correlation code --

// Create a structured log entry using MDC (Mapped Diagnostic Context) keys.
// For instantiating the "logger" variable, see
// https://cloud.google.com/run/docs/logging#run_manual_logging-java
MDC.put("component", "arbitrary-property");

logger.info("This is the default display field.");

// Clear MDC at the end of the request to avoid resource leaks
MDC.clear();

Personalizza i nomi dei campi standard per escludere i contenuti indesiderati dall'importazione nel payload dei log. Per un elenco dei nomi dei campi e dei formati di dati previsti, consulta Utilizzare l'agente di logging.

<configuration>
  <appender name="CLOUD" class="com.google.cloud.logging.logback.LoggingAppender">
    <!-- Optional : filter logs at or above a level -->
    <filter class="ch.qos.logback.classic.filter.ThresholdFilter">
      <level>INFO</level>
    </filter>
    <log>application.log</log> <!-- Optional : default java.log -->
    <resourceType>gae_app</resourceType> <!-- Optional : default: auto-detected, fallback: global -->
    <enhancer>com.example.logging.logback.enhancers.ExampleEnhancer</enhancer> <!-- Optional -->
    <flushLevel>WARN</flushLevel> <!-- Optional : default ERROR -->
    <!-- Redirect logs to stdout in JSON format for Cloud Run to capture -->
    <redirectToStdout>true</redirectToStdout>
  </appender>
  <root level="INFO">
    <appender-ref ref="CLOUD"/>
  </root>
</configuration>

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 di 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 della LogEntry generata, come descritto nella documentazione relativa ai campi speciali.

Ad esempio, se il JSON include una proprietà severity, questa viene rimossa da 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.

Correlare i log delle richieste con i log delle app

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

1. Estrai l'identificatore di traccia dall'intestazione della richiesta X-Cloud-Trace-Context.
2. Nella voce di log strutturata, scrivi l'ID in un campo denominato logging.googleapis.com/trace. Per saperne di più sull'intestazione X-Cloud-Trace-Context, consulta Forzare la tracciabilità di una richiesta.

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

Visualizzare i log

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

• Utilizza Esplora log da Cloud Logging nella Google Cloud console.
• 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 delle app e delle richieste utilizzando lo strumento Esplora log:

1. Vai a Esplora log nella Google Cloud console:

   Vai a Esplora log

2. Seleziona un progetto esistente Google Cloud 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 Utilizzare Esplora log.

Se invii semplici voci di testo all'output standard, non puoi utilizzare il Visualizzatore log per filtrare le voci delle app in base alla gravità, né puoi vedere quali log delle app corrispondono a richieste specifiche. Puoi comunque utilizzare altri tipi di filtri in Esplora log, come 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 la voce di log delle richieste di App Engine e le voci di log delle applicazioni:

1. Nel pannello di navigazione della Google Cloud console, seleziona Logging, quindi seleziona 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 correlare in base ai log delle richieste, fai clic su Correlare per e seleziona request_log.

   

4. Nel riquadro Risultati delle query , fai clic su Espandi per espandere una voce di log. Quando espandi, ogni log delle richieste mostra 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 lo fa correlando il campo trace nei log delle app e un determinato log delle richieste, presupponendo che l'applicazione utilizzi la libreria google-cloud-logging.

L'immagine seguente mostra i log delle app raggruppati per il 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 saperne di più, consulta gcloud app logs tail.

Leggere i 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 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.

Prezzi, quote e criteri di conservazione dei log

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

Per i criteri 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 esportare i log in Cloud Storage. Puoi anche esportare i log in BigQuery e Pub/Sub per un'ulteriore elaborazione.

Gestire l'utilizzo delle risorse dei log

Puoi controllare la quantità di attività di logging dai log delle app scrivendo più o meno voci dal codice dell'app. I log delle richieste vengono creati automaticamente, quindi per gestire il numero di voci di log delle richieste associate a 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 delle app non sono correlate al log delle richieste. Ciò 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 saperne di più, consulta https://issuetracker.google.com/issues/138365527.

• Quando indirizzi i 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. 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 CPU, il che fa sì che il thread in background si arresti. Il tempo di elaborazione dei log è ritardato. A un certo punto, l'istanza viene rimossa e tutti i log non inviati vengono persi. Per evitare di perdere i log, utilizza una delle seguenti opzioni:

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

Passaggi successivi

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