Scrivi voci di log ed esegui query utilizzando uno script Python

Per iniziare

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

Clona origine

Per configurare Cloud Shell per questa guida rapida:

1. Clona il progetto GitHub python-logging:

   git clone https://github.com/GoogleCloudPlatform/python-docs-samples
   

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

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

2. Passa alla directory snippets:

   cd logging/samples/snippets
   

Scrivi voci di log

Lo script snippets.py utilizza le librerie client Python per scrivere voci di log in Logging. Quando l'opzione write viene 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à 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:
* 2025-11-13T16:05:35.548471+00:00: Hello, world!
* 2025-11-13T16:05:35.647190+00:00: Goodbye, world!
* 2025-11-13T16: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 alcuna voce, riprova a eseguire il comando. Logging impiega alcuni istanti per ricevere ed elaborare le voci di log.

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

Elimina voci di log

Per eliminare tutte le voci di log nel 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.

Instrada i log

In questa sezione, eseguirai questi passaggi:

• Crea un bucket Cloud Storage come destinazione per i tuoi 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.
• Facoltativamente, verifica i contenuti del bucket Cloud Storage.

Crea destinazione

La destinazione di esportazione per questa guida rapida è 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. Questa guida rapida utilizza il nome myloggingproject-1.
4. In Tipo di località, seleziona Regione, che seleziona una località del bucket con la latenza più bassa.
5. In Imposta una classe predefinita, seleziona Standard.
6. In Controllo dell'accesso, seleziona Granulare.
7. In Strumenti di protezione, seleziona Nessuno, quindi fai clic su Crea.

Crea un sink

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

• Nome
• Destinazione
• Filtro

Per saperne di più sui sink, consulta Informazioni sui sink di log.

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

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

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

Lo script restituisce quanto segue:

Created sink mysink

Per visualizzare i sink, 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 sink utilizzando lo script export.py. Devi modificare le impostazioni delle autorizzazioni del bucket Cloud Storage per concedere le autorizzazioni di scrittura nel sink. Per informazioni sui service account, sugli ambiti di accesso e sui ruoli di Identity and Access Management, consulta Service account.

Per aggiornare le autorizzazioni sul bucket Cloud Storage:

1. Identifica l'identità writer del sink:

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

      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 sink.

   2. Trova il sink nella tabella, seleziona more_vert Menu, quindi seleziona Visualizza dettagli sink.

   3. Copia l'identità del writer 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 l'accesso.

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

6. Imposta Ruolo su Storage Admin, quindi fai clic su Salva.

Per saperne di più, consulta Imposta le autorizzazioni della destinazione.

Convalida sink

Per verificare che il sink e la destinazione siano configurati correttamente, segui questi passaggi:

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 dati. Se non sono presenti dati nel bucket, viene visualizzato il seguente messaggio:

      There are no live objects in this bucket.

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

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

      

   3. I dati di ogni cartella sono organizzati in una serie di cartelle etichettate con la cartella di primo livello costituita da un nome di log e, successivamente, da anno, mese e giorno. Per visualizzare i dati esportati dal sink, fai clic sul nome della cartella my-log, quindi continua a fare clic sulle sottocartelle di anno, mese e giorno fino a raggiungere un file che termina con json:

      

   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 ai seguenti:

       {"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 "Goodbye, world!" viene esportata nella destinazione del sink. 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 notificato un errore di configurazione. Per saperne di più, consulta Voci di log con arrivo in ritardo.

• Si è verificato un errore di configurazione. In questo caso, riceverai un'email con un oggetto simile al seguente:

   [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, l'email elenca il seguente codice di errore:

   bucket_permission_denied

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

• Non sono state scritte voci di log dopo la creazione del sink. Il sink viene applicato solo alle voci di log appena arrivate. Per correggere questa situazione, scrivi nuove voci di log:

   python snippets.py my-log write