Scrivere voci di log ed eseguirne query utilizzando uno script Python

Questa guida rapida offre l'introduzione ad alcune delle funzionalità di Cloud Logging e mostra come eseguire le seguenti operazioni:

  • Scrivi le voci di log utilizzando uno script Python.
  • Visualizza le voci di log utilizzando uno script Python.
  • Elimina le voci di log utilizzando uno script Python.
  • Invia i log a un bucket Cloud Storage.

La registrazione può indirizzare le voci di log alle seguenti destinazioni:

  • Bucket Cloud Storage
  • Set di dati di BigQuery
  • Pub/Sub
  • Bucket di Logging
  • Progetti Google Cloud

Prima di iniziare

Per completare questa guida introduttiva, devi disporre di un progetto Google Cloud con la fatturazione abilitata. Se non hai un progetto Google Cloud o se la fatturazione non è attivata per il tuo progetto Google Cloud, svolgi i seguenti passaggi:
  1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

  3. Make sure that billing is enabled for your Google Cloud project.

  4. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

  5. Make sure that billing is enabled for your Google Cloud project.

Questa guida rapida utilizza Cloud Logging e Cloud Storage. L'utilizzo di queste risorse può comportare un costo. Al termine di questa guida rapida, puoi evitare la fatturazione continua eliminando le risorse che hai creato. Per ulteriori dettagli, consulta la sezione Pulizia in questa pagina.

Per iniziare

Per completare questa guida rapida, puoi utilizzare l'ambiente Cloud Shell o un ambiente Linux generico. Python è preinstallato in Cloud Shell.

Cloud Shell

  1. Apri Cloud Shell e verifica la configurazione del progetto Google Cloud:

    1. Nella console Google Cloud, fai clic su Attiva Cloud Shell.

      Cloud Shell si apre in una finestra e mostra un messaggio di benvenuto.

    2. Il messaggio di benvenuto ripete l'ID progetto Google Cloud configurato. Se non si tratta del progetto Google Cloud che vuoi utilizzare, esegui il seguente comando dopo aver sostituito PROJECT_ID con l'ID del progetto:

      gcloud config set project PROJECT_ID

Linux

  1. Assicurati che Python sia installato e configurato. Per informazioni su come preparare il computer per lo sviluppo Python, consulta Configurare un ambiente di sviluppo Python.

  2. Installa la libreria client di Cloud Logging:

    pip install --upgrade google-cloud-logging

  3. Configura le autorizzazioni di Identity and Access Management per il tuo progetto Google Cloud. Nei passaggi seguenti, crei un account di servizio per il tuo progetto Google Cloud, poi generi e scarichi un file sulla tua workstation Linux.

    1. Nella console Google Cloud, vai alla pagina Account di servizio:

      Vai ad Account di servizio.

      Se utilizzi la barra di ricerca per trovare questa pagina, seleziona il risultato con il sottotitolo IAM e amministrazione.

    2. Seleziona il progetto Google Cloud della guida rapida e fai clic su Crea account di servizio:

      • Inserisci un nome per l'account.
      • Inserisci una descrizione dell'account.
      • Fai clic su Crea e continua.

    3. Fai clic sul campo Seleziona un ruolo e seleziona Logging Admin.

    4. Fai clic su Fine per completare la creazione dell'account di servizio.

    5. Crea un file della chiave e scaricalo sulla workstation:

      • Per il tuo account di servizio, fai clic su Altre opzioni e seleziona Gestisci chiavi.
      • Nel riquadro Chiavi, fai clic su Aggiungi chiave.
      • Fai clic su Crea nuova chiave.

      • In Tipo di chiave, seleziona JSON e fai clic su Crea. Dopo un istante, in una finestra viene visualizzato un messaggio simile al seguente:

        Chiave privata salvata sul computer.

  4. Sulla workstation Linux, fornisci le tue credenziali di autenticazione all'applicazione impostando la variabile di ambiente GOOGLE_APPLICATION_CREDENTIALS sul percorso del file della chiave. Ad esempio:

     export GOOGLE_APPLICATION_CREDENTIALS="/home/user/Downloads/FILE_NAME.json"

    Questa variabile di ambiente si applica solo alla sessione di shell corrente, quindi se apri una nuova sessione, imposta di nuovo la variabile.

Clona origine

Per configurare Cloud Shell per questa guida introduttiva, segui questi passaggi:

  1. Clona il progetto GitHub python-logging:

      git clone https://github.com/googleapis/python-logging

    La directory samples/snippets contiene i due script utilizzati in questa guida rapida:

    • snippets.py ti consente di gestire le voci in un log.
    • export.py ti consente di gestire le esportazioni dei log.

  2. Passa alla directory snippets:

      cd python-logging/samples/snippets

Scrivere voci di log

Lo script snippets.py utilizza le librerie client Python per scrivere voci di log in Logging. Quando l'opzione write è specificata nella riga di comando, lo script scrive le seguenti voci di log:

  • Una voce con dati non strutturati e nessun livello di gravità specificato.
  • Una voce con dati non strutturati e un livello di gravità pari a ERROR.
  • Una voce con dati strutturati JSON e nessun livello di gravità specificato.

Per scrivere nuove voci di log nel log my-log, esegui lo script snippets.py con l'opzione write:

python snippets.py my-log write

Visualizza voci di log

Per visualizzare le voci di log in Cloud Shell, esegui lo script snippets.py con l'opzione list:

python snippets.py my-log list

Il comando viene completato con il risultato:

    Listing entries for logger my-log:
    * 2018-11-15T16:05:35.548471+00:00: Hello, world!
    * 2018-11-15T16:05:35.647190+00:00: Goodbye, world!
    * 2018-11-15T16:05:35.726315+00:00: {u'favorite_color': u'Blue', u'quest': u'Find the Holy Grail', u'name': u'King Arthur'}

Se il risultato non mostra voci, riprova a eseguire il comando. Sono necessari alcuni istanti affinché la funzionalità di logging riceva ed elabori le voci di log.

Puoi anche visualizzare le voci di log utilizzando Esplora log. Per maggiori dettagli, consulta Visualizza i log utilizzando Esplora log.

Eliminare le voci di log

Per eliminare tutte le voci del log my-log, esegui lo script snippets.py con l'opzione delete:

python snippets.py my-log delete

Il comando viene completato con il risultato:

Deleted all logging entries for my-log.

Log delle route

In questa sezione:

  • Crea un bucket Cloud Storage come destinazione per i dati.
  • Crea un sink che copia le nuove voci di log nella destinazione.
  • Aggiorna le autorizzazioni del bucket Cloud Storage.
  • Scrivere voci di log in Logging.
  • Se vuoi, verifica i contenuti del bucket Cloud Storage.

Crea destinazione

La destinazione di esportazione per questa guida di avvio rapido è un bucket Cloud Storage. Per creare un bucket Cloud Storage, segui questi passaggi:

  1. Nella console Google Cloud, vai alla pagina Bucket:

    Vai a Bucket

    Se utilizzi la barra di ricerca per trovare questa pagina, seleziona il risultato con il sottotitolo Cloud Storage.

  2. Fai clic su Crea bucket.
  3. Inserisci un nome per il bucket.
  4. In Tipo di località, seleziona Regione, che seleziona una località del bucket con la latenza più bassa.
  5. Per Classe di archiviazione predefinita, seleziona Standard.
  6. In Controllo dell'accesso, seleziona Granulare.
  7. Per Strumenti di protezione, seleziona Nessuna e poi fai clic su Crea.

Questa guida rapida utilizza il nome del bucket Cloud Storage myloggingproject-1.

Crea un sink

Un sink è una regola che determina se Logging inoltra una voce di log appena arrivata a una destinazione. Un sink ha tre attributi:

  • Nome
  • Destinazione
  • Filtro

Per ulteriori informazioni sui sink, consulta Sinks.

Se una voce di log appena arrivata soddisfa le condizioni di query, viene inoltrata alla destinazione.

Lo script export.py utilizza le librerie client Python per creare, elencare, modificare ed eliminare i canali. Per creare l'emissario mysink che esporta tutte le voci di log con una gravità di almeno INFO nel bucket Cloud Storage myloggingproject-1, esegui il seguente comando:

python export.py create mysink myloggingproject-1 "severity>=INFO"

Per visualizzare i canali di destinazione, esegui lo script export.py con l'opzione list:

python export.py list

Lo script restituisce quanto segue:

    mysink: severity>=INFO -> storage.googleapis.com/myloggingproject-1

Aggiorna le autorizzazioni di destinazione

Le autorizzazioni della destinazione, in questo caso il bucket Cloud Storage, non vengono modificate quando crei un'area di destinazione utilizzando lo script export.py. Devi modificare le impostazioni di autorizzazione del bucket Cloud Storage per grante l'autorizzazione di scrittura al tuo sink. Per informazioni sugli account di servizio, gli ambiti di accesso e i ruoli di Identity and Access Management, consulta Account di servizio.

Per aggiornare le autorizzazioni del bucket Cloud Storage:

  1. Identifica l'identità autore della destinazione:

    1. Nella console Google Cloud, vai alla pagina Log Router:

      Vai a Router dei log

      Se utilizzi la barra di ricerca per trovare questa pagina, seleziona il risultato con il sottotitolo Logging.

      Viene visualizzata una tabella di riepilogo dei tuoi sink.

    2. Individua il tuo lavandino nella tabella, seleziona Menu e poi Visualizza i dettagli del lavandino.

    3. Copia l'identità dell'autore negli appunti.

  2. Nella console Google Cloud, vai alla pagina Bucket:

    Vai a Bucket

    Se utilizzi la barra di ricerca per trovare questa pagina, seleziona il risultato con il sottotitolo Cloud Storage.

  3. Per aprire la visualizzazione dettagliata, fai clic sul nome del bucket.

  4. Seleziona Autorizzazioni e fai clic su Concedi accesso.

  5. Incolla l'identità dello scrittore nella casella Nuove entità. Rimuovi il prefisso serviceAccount: dall'indirizzo dell'identità dell'autore.

  6. Imposta Ruolo su Storage Object Creator e poi fai clic su Salva.

Per ulteriori informazioni, vedi Impostare le autorizzazioni di destinazione.

Convalida il sink

Per verificare che l'obiettivo e la destinazione siano configurati correttamente:

  1. Scrivi nuove voci di log nel log my-log:

    python snippets.py my-log write

  2. Visualizza i contenuti del bucket Cloud Storage:

    1. Nella console Google Cloud, vai alla pagina Bucket:

      Vai a Bucket

      Se utilizzi la barra di ricerca per trovare questa pagina, seleziona il risultato con il sottotitolo Cloud Storage.

    2. Per aprire la visualizzazione dettagliata, fai clic sul nome del bucket. La visualizzazione dettagliata elenca le cartelle che contengono i dati. Se nel bucket non sono presenti dati, viene visualizzato il seguente messaggio:

      There are no live objects in this bucket.

      Come descritto in Voci dei log in ritardo, potrebbero essere necessarie 2 o 3 ore prima che le prime voci vengano visualizzate nella destinazione o prima che ti venga inviata una notifica di un errore di configurazione.

      Una volta che il bucket ha ricevuto i dati, la visualizzazione dettagliata mostra un risultato simile al seguente:

      Visualizzazione dettagliata dei contenuti del bucket.

    3. I dati in ogni cartella sono organizzati in una serie di cartelle etichettate con la cartella di primo livello costituita da un nome del log, quindi successivamente, l'anno, il mese e il giorno. Per visualizzare i dati esportati dall'eseguiamo, fai clic sul nome della cartella my-log, quindi continua a fare clic sulle sottocartelle dell'anno, del mese e del giorno finché non raggiungi un file che termina con json:

      Visualizzazione della sottocartella dei contenuti del bucket.

    4. Il file JSON contiene le voci di log esportate nel bucket Cloud Storage. Fai clic sul nome del file JSON per visualizzarne i contenuti. I contenuti sono simili a:

       {"insertId":"yf1cshfoivz48",
 "logName":"projects/loggingproject-222616/logs/my-log",
 "receiveTimestamp":"2018-11-15T23:06:14.738729911Z",
 "resource":{"labels":{"project_id":"loggingproject-222616"},"type":"global"},
 "severity":"ERROR",
 "textPayload":"Goodbye, world!",
 "timestamp":"2018-11-15T23:06:14.738729911Z"}

      Poiché il livello di gravità di ERROR è superiore al livello di gravità di INFO, la voce di log contenente la stringa "Addio, mondo!" viene esportata nella destinazione di destinazione. Le altre voci di log scritte non sono state esportate nella destinazione perché il loro livello di gravità è stato impostato sul valore predefinito, che è inferiore a INFO.

Risoluzione dei problemi

Esistono diversi motivi per cui un bucket Cloud Storage potrebbe essere vuoto:

  • Il bucket non ha ricevuto dati. Potrebbero essere necessarie 2 o 3 ore prima che le prime voci vengano visualizzate nella destinazione o prima che ti venga inviata una notifica di un errore di configurazione. Per ulteriori informazioni, consulta Voce del log in ritardo.

  • Si è verificato un errore di configurazione. In questo caso, riceverai un messaggio email simile alla seguente riga dell'oggetto:

     [ACTION REQUIRED] Logging export config error in myloggingproject.

    Il contenuto del corpo dell'email descrive il problema di configurazione. Ad esempio, se non aggiorni le autorizzazioni di destinazione, nell'email viene elencato il seguente codice di errore:

     bucket_permission_denied

    Per correggere questa condizione specifica, consulta Aggiornare le autorizzazioni di destinazione in questa pagina.

  • Non sono state registrate voci di log dopo la creazione dell'eseguibile sink. Il sink viene applicato solo alle nuove voci di log in arrivo. Per correggere questa situazione, scrivi nuove voci di log:

     python snippets.py my-log write

Esegui la pulizia

Per evitare che al tuo account Google Cloud vengano addebitati costi relativi alle risorse utilizzate in questa pagina, segui questi passaggi.

  1. (Facoltativo) Elimina le voci di log che hai creato. Se non elimini le voci del log, queste scadranno e verranno rimosse. Consulta la sezione Quote e limiti.

    Per eliminare tutte le voci di log nel log my-log, esegui il seguente comando:

     python snippets.py my-log delete

  2. Elimina il progetto Google Cloud o le risorse della guida rapida.

    • Per eliminare il progetto Google Cloud, fai clic su Vai alle impostazioni del progetto nel riquadro Informazioni sul progetto della console Google Cloud e poi su Spegni.

    • Per eliminare le risorse della guida rapida:

      1. Elimina il sink eseguendo il seguente comando:

        python export.py delete mysink

      2. Elimina il bucket Cloud Storage. Vai alla console Google Cloud e fai clic su Storage > Bucket. Seleziona la casella accanto al nome del bucket e fai clic su Elimina.

Passaggi successivi