Scrivi voci di log ed esegui query con gcloud CLI

Questo documento offre l'introduzione ad alcune delle funzionalità di Cloud Logging e mostra come:

  • Scrivere voci di log utilizzando Google Cloud CLI.
  • Elencare le voci di log utilizzando gcloud CLI.
  • Elencare le voci di log utilizzando l'API Logging.
  • Visualizzare ed eseguire query sulle voci di log utilizzando Esplora log.

Prima di iniziare

Per completare questa guida rapida, devi avere un Google Cloud progetto con la fatturazione abilitata. Se non hai un Google Cloud progetto o se la fatturazione non è abilitata per il tuo Google Cloud progetto, procedi nel seguente modo:

  1. Accedi al tuo Google Cloud account. 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 senza costi per l'esecuzione, il test e il deployment dei workload.

  2. Installa Google Cloud CLI.

  3. Se utilizzi un provider di identità (IdP) esterno, devi prima accedere a gcloud CLI con la tua identità federata.

  4. Per inizializzare gcloud CLI, esegui questo comando: 

    gcloud init

  5. Crea o seleziona un Google Cloud progetto.

    Ruoli necessari per selezionare o creare un progetto

    • Seleziona un progetto: la selezione di un progetto non richiede un ruolo IAM specifico: puoi selezionare qualsiasi progetto su cui ti è stato concesso un ruolo.
    • Crea un progetto: per creare un progetto, devi disporre del ruolo Autore progetto (roles/resourcemanager.projectCreator), che contiene l' resourcemanager.projects.create autorizzazione. Scopri come concedere i ruoli.

    • Crea un Google Cloud progetto:

      gcloud projects create PROJECT_ID

      Sostituisci PROJECT_ID con un nome per il Google Cloud progetto che stai creando.

    • Seleziona il Google Cloud progetto che hai creato:

      gcloud config set project PROJECT_ID

      Sostituisci PROJECT_ID con il nome del Google Cloud progetto.

  6. Se utilizzi un progetto esistente per questa guida, verifica di disporre delle autorizzazioni necessarie per completare la guida. Se hai creato un nuovo progetto, disponi già delle autorizzazioni necessarie.

  7. Verifica che la fatturazione sia abilitata per il tuo Google Cloud progetto.

  8. Installa Google Cloud CLI.

  9. Se utilizzi un provider di identità (IdP) esterno, devi prima accedere a gcloud CLI con la tua identità federata.

  10. Per inizializzare gcloud CLI, esegui questo comando: 

    gcloud init

  11. Crea o seleziona un Google Cloud progetto.

    Ruoli necessari per selezionare o creare un progetto

    • Seleziona un progetto: la selezione di un progetto non richiede un ruolo IAM specifico: puoi selezionare qualsiasi progetto su cui ti è stato concesso un ruolo.
    • Crea un progetto: per creare un progetto, devi disporre del ruolo Autore progetto (roles/resourcemanager.projectCreator), che contiene l' resourcemanager.projects.create autorizzazione. Scopri come concedere i ruoli.

    • Crea un Google Cloud progetto:

      gcloud projects create PROJECT_ID

      Sostituisci PROJECT_ID con un nome per il Google Cloud progetto che stai creando.

    • Seleziona il Google Cloud progetto che hai creato:

      gcloud config set project PROJECT_ID

      Sostituisci PROJECT_ID con il nome del Google Cloud progetto.

  12. Se utilizzi un progetto esistente per questa guida, verifica di disporre delle autorizzazioni necessarie per completare la guida. Se hai creato un nuovo progetto, disponi già delle autorizzazioni necessarie.

  13. Verifica che la fatturazione sia abilitata per il tuo Google Cloud progetto.

Ruoli obbligatori

Per ottenere le autorizzazioni necessarie per creare, elencare ed eliminare le voci di log, chiedi all'amministratore di concederti il ruolo IAM Logging Admin (roles/logging.admin) nel progetto. Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

Potresti anche riuscire a ottenere le autorizzazioni richieste tramite i ruoli personalizzati o altri ruoli predefiniti.

I ruoli Logs Writer (roles/logging.logWriter) e Logs Viewer (roles/logging.viewer) contengono le autorizzazioni per creare ed elencare le voci di log. Per eliminare le voci di log, concedi il ruolo Logging Admin (roles/logging.admin), che contiene le autorizzazioni per creare, elencare ed eliminare le voci di log. Tieni presente che il ruolo Logging Admin (roles/logging.admin) concede anche le autorizzazioni per eseguire tutte le azioni in Logging.

Scrivere voci di log utilizzando gcloud CLI

Logging supporta le voci di log con dati strutturati e non strutturati. I dati strutturati sono costituiti da una struttura di dati JSON, ad esempio, {"weather": "partly cloudy"}. I dati non strutturati sono una stringa di caratteri, ad esempio "A simple entry".

Nei passaggi successivi utilizzerai gcloud CLI per scrivere una voce di log con dati non strutturati e una voce di log con dati strutturati. La gcloud CLI fornisce un'interfaccia a riga di comando per l'API Cloud Logging.

  1. Per scrivere una voce di log con dati non strutturati nel log my-test-log, esegui il gcloud logging write comando:

    gcloud logging write my-test-log "A simple entry."

    Al termine del comando, viene visualizzato il messaggio: Created log entry.

  2. Per scrivere una voce di log con dati strutturati nel log my-test-log:

    gcloud logging write --payload-type=json my-test-log '{ "message": "My second entry", "weather": "partly cloudy"}'

    Quando scrivi una voce di log con dati strutturati, devi includere --payload-type=json. Se ometti questo campo, Logging interpreta il payload come dati non strutturati.

Se il log my-test-log non esiste, Logging lo crea quando viene ricevuta la voce di log.

Elencare le voci di log utilizzando gcloud CLI

Puoi recuperare le voci di log da Logging e visualizzarle utilizzando gcloud CLI. Ad esempio, per recuperare e visualizzare le voci di log con un tipo di risorsa global, esegui questo comando:

gcloud logging read "resource.type=global"

Il comando restituisce un risultato simile al seguente:

---
insertId: jpj9zjf73t1mn
jsonPayload:
  message: My second entry
  weather: partly cloudy
logName: projects/myloggingproject/logs/my-test-log
receiveTimestamp: '2018-11-01T18:39:31.114507977Z'
resource:
  labels:
    project_id: myloggingproject
  type: global
timestamp: '2018-11-01T18:39:31.114507977Z'
---
insertId: vd4m1if7h7u1a
logName: projects/myloggingproject/logs/my-test-log
receiveTimestamp: '2018-11-01T18:39:19.718100792Z'
resource:
  labels:
    project_id: myloggingproject
  type: global
textPayload: A simple entry
timestamp: '2018-11-01T18:39:19.718100792Z'

Per informazioni sulla lettura dei log, consulta la gcloud logging read documentazione di riferimento.

Elencare le voci di log utilizzando Explorer API

Per eseguire i metodi dell'API Logging senza scrivere codice, consulta Utilizzo di Explorer API. Per leggere un elenco di voci di log da Logging:

  1. Vai alla pagina di riferimento dell'API per il metodo API entries.list:

    Vai alla pagina dell'API entries.list

  2. Configura ed esegui il comando API:

    1. Sostituisci PROJECT_ID nel testo seguente:

      "resourceNames": [
"projects/PROJECT_ID"
],
"filter": "resource.type=global",
"orderBy": "timestamp desc"

    2. Copia il testo aggiornato del passaggio precedente e incollalo nel campo Corpo della richiesta di Explorer API.

    3. Fai clic su Esegui.

    Il metodo restituisce una risposta simile alla seguente:

    {
  "entries": [
    {
      "textPayload": "A simple entry",
      "insertId": "vd4m1if7h7u1a",
      "resource": {
        "type": "global",
        "labels": {
          "project_id": "myloggingproject"
        }
      },
      "timestamp": "2018-11-01T18:39:19.718100792Z",
      "logName": "projects/myloggingproject/logs/my-test-log",
      "receiveTimestamp": "2018-11-01T18:39:19.718100792Z"
    },
    {
      "insertId": "jpj9zjf73t1mn",
      "jsonPayload": {
        "message": "My second entry",
        "weather": "partly cloudy"
      },
      "resource": {
        "type": "global",
        "labels": {
          "project_id": "myloggingproject"
        }
      },
      "timestamp": "2018-11-01T18:39:31.114507977Z",
      "logName": "projects/myloggingproject/logs/my-test-log",
      "receiveTimestamp": "2018-11-01T18:39:31.114507977Z"
    }
  ]
}

Visualizzare le voci di log in Esplora log

Per visualizzare le voci di log nella Google Cloud console, puoi utilizzare Esplora log. La maggior parte dei progetti archivia un numero elevato di log; puoi selezionare determinate voci di log scrivendo una query. Google Cloud

Per visualizzare le voci di log che hai scritto utilizzando Esplora log:

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

    Vai a Esplora log

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

    Assicurati che il tuo Google Cloud progetto sia selezionato nella Google Cloud barra di navigazione. Se necessario, utilizza l'elenco a discesa del Google Cloud progetto per selezionare il tuo Google Cloud progetto.

  2. Nel menu Risorsa, seleziona Globale.

    Se non vedi l'opzione di menu Globale o se non vedi le voci di log, attendi qualche minuto e aggiorna la pagina. Potrebbero essere necessari alcuni minuti prima che Logging riceva le voci di log.

  3. Per visualizzare i dettagli di una voce di log, fai clic sul relativo Menu.

    I dati della prima voce di log sono archiviati in textPayload. La seconda voce di log contiene dati strutturati archiviati in jsonPayload. Il payload strutturato contiene le chiavi message e weather.

Per informazioni sul formato dei dati delle voci di log, consulta il LogEntry tipo.

Eseguire query sulle voci di log in Esplora log

Puoi eseguire query sulle voci di log utilizzando l'editor di query e, con i log strutturati, per chiave e valore. Ad esempio, per visualizzare tutte le voci di log che contengono il testo simple:

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

    Vai a Esplora log

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

  2. Nel menu Risorsa, seleziona Globale.

  3. Nell'editor di query, inserisci la stringa simple tra virgolette. La visualizzazione dei log mostra solo la voce di log A simple entry..

  4. Dopo aver visualizzato il log, rimuovi la stringa di query che hai aggiunto e fai clic su Esegui query. Entrambe le voci di log vengono visualizzate di nuovo.

Per visualizzare tutte le voci di log con dati strutturati che hanno una chiave weather in cui il campo value contiene partly:

  1. L'editor di query contiene la riga resource.type="global". Inserisci questo comando:

    jsonPayload.weather:partly

  2. Fai clic su Esegui query. Il risultato è la singola voce di log My second entry.

Esplora log offre anche query salvate, suggerite e recenti. Per saperne di più sulle query, consulta Crea query in Esplora log.

Per query di esempio, consulta Query di esempio con Esplora log.

Risoluzione dei problemi

  • Gli errori di battitura e i nomi dei campi sconosciuti fanno sì che i comandi gcloud CLI vengano completati con invalid argument messaggi. Ad esempio, se dimentichi il punto in resource.type, viene generato il seguente errore:

     ERROR: (gcloud.logging.read) INVALID_ARGUMENT: Field not found: 'resourcetype'.

  • Quando a Cloud Logging non sono state concesse le autorizzazioni di accesso necessarie, i comandi gcloud CLI vengono completati con permission denied messaggi. Ad esempio, se un'istanza VM di Compute Engine è configurata con le impostazioni API predefinite, il comando list viene completato con un errore di autorizzazione negata:

     ERROR: (gcloud.logging.read) PERMISSION_DENIED: Request had insufficient authentication scopes.

    Per risolvere questo problema, modifica le autorizzazioni dell'istanza VM di Compute Engine per concedere l'autorizzazione di lettura a Cloud Logging:

    1. Vai alla pagina Dettagli istanza VM per l'istanza VM. Fai clic su Arresta. Il completamento di questa azione potrebbe richiedere uno o due minuti.
    2. Per modificare la configurazione, fai clic su Modifica.
    3. Cerca l'intestazione Ambiti di accesso all'API Cloud e fai clic Dettagli per visualizzare le impostazioni di ogni API. Modifica la voce da API Cloud Logging a Completo. Fai clic su Salva.
    4. Per riavviare l'istanza VM, fai clic su Avvia. Dopo qualche istante, la VM è pronta per l'uso.

  • Quando Explorer API non riesce a completare il comando o richiede un'autorizzazione aggiuntiva, visualizza un messaggio o un codice di errore:

    • Codice di risposta 200 e nessuna voce: se viene visualizzato il messaggio nextPageToken è visualizzato, significa che Explorer API non ha avuto il tempo di completare la ricerca. Aggiungi un pageToken alla richiesta, imposta il valore in modo che sia uguale a quello fornito con la chiave nextPageToken e riprova a eseguire il comando.
    • Codice di risposta 400: il valore della query non è valido. Ad esempio, se scrivi global come gloobal, il messaggio è Unsupported resource type: gloobal.
    • Codice di risposta 404: l'ID progetto non è valido. Controlla l'ortografia dell'identificatore del progetto.
    • Ti potrebbe essere chiesto di accedere al Google Cloud progetto e di consentire a Explorer API di accedere al tuo account.

Libera spazio

Per evitare che al tuo Google Cloud account vengano addebitati costi relativi alle risorse utilizzate in questa pagina, elimina il Google Cloud progetto con le risorse.

  1. (Facoltativo) Per eliminare le voci di log che hai creato, esegui questo comando gcloud:

    gcloud logging logs delete my-test-log

    Se non elimini le voci di log, queste scadono e vengono rimosse. Per informazioni sulla conservazione, consulta Quote e limiti.

Passaggi successivi

  • Per informazioni dettagliate sull'interfaccia a riga di comando di Logging, consulta le pagine di riferimento per il gcloud logging gruppo di comandi.
  • Per la documentazione sull'API Logging, consulta API Cloud Logging.
  • Per informazioni dettagliate su Esplora log, consulta Utilizzo di Esplora log.