Scrivere ed eseguire query sulle voci di log utilizzando uno script Python
Questa guida rapida illustra alcune delle funzionalità di Cloud Logging e mostra come:
- Scrivere le voci di log utilizzando uno script Python.
- Visualizzare le voci di log utilizzando uno script Python.
- Eliminare le voci di log utilizzando uno script Python.
- Esegui il routing dei log su un bucket Cloud Storage.
Logging può instradare 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 rapida, devi avere un progetto Google Cloud con fatturazione abilitata. Se non hai un progetto Google Cloud o se non hai abilitato la fatturazione per il tuo progetto Google Cloud, segui questi passaggi:- Accedi al tuo account Google Cloud. Se non conosci Google Cloud, crea un account per valutare le prestazioni dei nostri prodotti in scenari reali. I nuovi clienti ricevono anche 300 $di crediti gratuiti per l'esecuzione, il test e il deployment dei carichi di lavoro.
-
Nella pagina del selettore di progetti della console Google Cloud, seleziona o crea un progetto Google Cloud.
-
Assicurati che la fatturazione sia attivata per il tuo progetto Google Cloud.
-
Nella pagina del selettore di progetti della console Google Cloud, seleziona o crea un progetto Google Cloud.
-
Assicurati che la fatturazione sia attivata per il tuo progetto Google Cloud.
Questa guida rapida utilizza Cloud Logging e Cloud Storage. L'utilizzo di queste risorse può comportare un costo. Al termine della guida rapida, puoi evitare di continuare la fatturazione eliminando le risorse che hai creato. Per ulteriori dettagli, consulta Eseguire la pulizia in questa pagina.
Per iniziare
Puoi utilizzare l'ambiente Cloud Shell o un ambiente Linux generico per completare questa guida rapida. Python è preinstallato in Cloud Shell.
Cloud Shell
Apri Cloud Shell e verifica la configurazione del tuo progetto Google Cloud:
Nella console Google Cloud, fai clic su Attiva Cloud Shell:
Cloud Shell si apre in una finestra e mostra un messaggio di benvenuto:
Il messaggio di benvenuto mostra l'eco dell'ID progetto Google Cloud configurato. Se questo non è il progetto Google Cloud che vuoi utilizzare, esegui il comando seguente dopo aver sostituito PROJECT_ID con l'ID del progetto:
gcloud config set project PROJECT_ID
Linux
Assicurati che Python sia installato e configurato. Per informazioni sulla preparazione della macchina per lo sviluppo Python, consulta Configurazione di un ambiente di sviluppo Python.
Installa la libreria client di Cloud Logging:
pip install --upgrade google-cloud-logging
Configura le autorizzazioni di Identity and Access Management per il tuo progetto Google Cloud. Nei passaggi seguenti, creerai un account di servizio per il tuo progetto Google Cloud, quindi generi e scarichi un file sulla tua workstation Linux.
-
Nella console Google Cloud, vai alla pagina Account di servizio:
Se utilizzi la barra di ricerca per trovare questa pagina, seleziona il risultato il cui sottotitolo è IAM e amministrazione.
Seleziona il progetto Google Cloud della guida rapida, quindi fai clic su Crea account di servizio:
- Inserisci un nome per l'account.
- Inserisci una descrizione per l'account.
- Fai clic su Crea e continua.
Fai clic sul campo Seleziona un ruolo e seleziona Amministratore Logging.
Fai clic su Fine per completare la creazione dell'account di servizio.
Crea un file di chiave e scaricalo sulla workstation:
- Per il tuo account di servizio, fai clic su more_vert 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 qualche istante, viene visualizzata una finestra popup con un messaggio simile a quello mostrato di seguito:
-
Sulla workstation Linux, fornisci le 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; pertanto, se apri una nuova sessione, imposta di nuovo la variabile.
Clona origine
Per configurare Cloud Shell per questa guida rapida:
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
consente di gestire le voci in un log.export.py
consente di gestire le esportazioni dei log.
Passa alla directory
snippets
:cd python-logging/samples/snippets
Scrivi voci di log
Lo script snippets.py
utilizza le librerie client Python per scrivere le 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à
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 termina 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 alcuna voce, riprova a eseguire il comando. Logging impiega alcuni momenti per ricevere ed elaborare le voci di log.
Puoi anche visualizzare le voci di log utilizzando Esplora log. Per ulteriori dettagli, consulta Visualizzare 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 termina con il risultato:
Deleted all logging entries for my-log
.
Log di routing
In questa sezione:
- Crea un bucket Cloud Storage come destinazione per i tuoi dati.
- Crea un sink che copi le nuove voci di log nella destinazione.
- Aggiorna le autorizzazioni del bucket Cloud Storage.
- Scrivi le voci di log in Logging.
- Se vuoi, 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:
-
Nella console Google Cloud, vai alla pagina Bucket:
Se utilizzi la barra di ricerca per trovare questa pagina, seleziona il risultato il cui sottotitolo è Cloud Storage.
- Fai clic su Crea bucket.
- Inserisci un nome per il bucket.
- Per Tipo di località, seleziona Regione, che seleziona una località del bucket con la latenza più bassa.
- In Classe di archiviazione predefinita, seleziona Standard.
- In Controllo dell'accesso, seleziona Granulare.
- Per Strumenti di protezione, seleziona Nessuno e fai clic su Crea.
Questa guida rapida utilizza il nome di un bucket Cloud Storage myloggingproject-1
.
Crea un sink
Un sink è una regola che determina se Logging instrada una voce di log appena ricevuta a una destinazione. Un sink ha tre attributi:
- Nome
- Destinazione
- Filtro
Per ulteriori informazioni sui sink, consulta la sezione Sink.
Se una voce di log appena raggiunta soddisfa le condizioni della query, la voce di log viene instradata verso la 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à minima di INFO
nel bucket Cloud Storage
myloggingproject-1
, esegui questo comando:
python export.py create mysink myloggingproject-1 "severity>=INFO"
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 della 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 l'autorizzazione di scrittura al sink. Per informazioni su account di servizio, ambiti di accesso e ruoli di Identity and Access Management, consulta Account di servizio.
Per aggiornare le autorizzazioni per il bucket Cloud Storage:
Identifica l'identità autore del sink:
-
Nella console Google Cloud, vai alla pagina Router dei log:
Se utilizzi la barra di ricerca per trovare questa pagina, seleziona il risultato il cui sottotitolo è Logging.
Viene visualizzata una tabella di riepilogo dei tuoi sink.
Individua il sink nella tabella, seleziona more_vert Menu, quindi Visualizza dettagli sink.
Copia l'identità dell'autore negli appunti.
-
-
Nella console Google Cloud, vai alla pagina Bucket:
Se utilizzi la barra di ricerca per trovare questa pagina, seleziona il risultato il cui sottotitolo è Cloud Storage.
Per aprire la visualizzazione dettagliata, fai clic sul nome del bucket.
Seleziona Autorizzazioni e fai clic su Concedi l'accesso.
Incolla l'identità dell'autore nella casella Nuove entità. Rimuovi il prefisso
serviceAccount:
dall'indirizzo dell'identità dell'autore.Imposta il Ruolo su
Storage Object Creator
, quindi fai clic su Salva.
Per ulteriori informazioni, vedi Impostare le autorizzazioni della destinazione.
Convalida sink
Per verificare che il sink e la destinazione siano configurati correttamente:
Scrivi nuove voci di log nel log
my-log
:python snippets.py my-log write
Visualizza i contenuti del bucket Cloud Storage:
-
Nella console Google Cloud, vai alla pagina Bucket:
Se utilizzi la barra di ricerca per trovare questa pagina, seleziona il risultato il cui sottotitolo è Cloud Storage.
Per aprire la visualizzazione dettagliata, fai clic sul nome del bucket. Nella visualizzazione dettagliata sono elencate le cartelle che contengono dati. Se il tuo bucket non contiene dati, 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 venga notificato un errore di configurazione.
Dopo che il bucket ha ricevuto i dati, la visualizzazione dettagliata mostra un risultato simile a:
I dati di ogni cartella sono organizzati in una serie di cartelle etichettate in base alla cartella di primo livello composta da un nome log e successivamente l'anno, il mese e il 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 conjson
:Il file JSON contiene le voci di log esportate nel bucket Cloud Storage. Fai clic sul nome del file JSON per visualizzarne il contenuto. 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à
ERROR
è superiore al livello di gravitàINFO
, la voce di log contenente la stringa ""Goodbye, world!"" viene esportata nella destinazione del sink. Le altre voci di log che sono state scritte non sono state esportate nella destinazione perché il livello di gravità era impostato sul valore predefinito e il livello di gravità predefinito è inferiore aINFO
.
-
Risoluzione dei problemi
I motivi per cui un bucket Cloud Storage potrebbe essere vuoto sono diversi:
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 venga visualizzato un errore di configurazione. Per ulteriori informazioni, consulta la sezione Voci di log in arrivo in ritardo.
Si è verificato un errore di configurazione. In questo caso, riceverai un messaggio e-mail simile al seguente 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 della destinazione, nell'email viene visualizzato il seguente codice di errore:
bucket_permission_denied
Per correggere questa condizione specifica, consulta la sezione Aggiornare le autorizzazioni della destinazione in questa pagina.
Nessuna voce di log è stata scritta dopo la creazione del sink. Il sink viene applicato solo alle voci di log appena arrivano. 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:
(Facoltativo) Elimina le voci di log create. Se non elimini le voci dei log, scadranno e verranno rimosse. Consulta Quote e limiti.
Per eliminare tutte le voci di log nel log
my-log
, esegui questo comando:python snippets.py my-log delete
Elimina il tuo progetto Google Cloud o le risorse della guida rapida.
Per eliminare il progetto Google Cloud, nel riquadro Informazioni sul progetto della console Google Cloud, fai clic su Vai alle impostazioni del progetto, quindi fai clic su Arresta.
Per eliminare le risorse della guida rapida:
Elimina il sink eseguendo questo comando:
python export.py delete mysink
Eliminare il bucket Cloud Storage. Vai alla console Google Cloud e fai clic su Archiviazione > Bucket. Seleziona la casella accanto al nome del bucket e fai clic su Elimina.
Passaggi successivi
- Per scoprire come leggere, scrivere e configurare i log dalle tue applicazioni, consulta API Cloud Logging.
- Per informazioni su Esplora log, consulta Visualizzare i log utilizzando Esplora log.
- Per scoprire come instradare i dati dei log alle destinazioni supportate, vedi Panoramica del routing e dell'archiviazione.
- Per scoprire come raccogliere le voci di log dalle istanze VM, consulta Panoramica di Ops Agent.
- Per informazioni su audit e conformità, consulta la panoramica di Cloud Audit Logs.