Scrivi voci di log ed esegui query con gcloud CLI

Questo documento illustra alcune delle funzionalità di Cloud Logging e mostra come svolgere le seguenti operazioni:

  • Scrivi voci di log utilizzando Google Cloud CLI.
  • Elenca le voci di log utilizzando gcloud CLI.
  • Elenca le voci di log utilizzando l'API Logging.
  • Visualizza ed esegui query sulle voci di log utilizzando Esplora log.

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, segui questi 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. Install the Google Cloud CLI.

  3. To initialize the gcloud CLI, run the following command: 

    gcloud init

  4. Create or select a Google Cloud project.

    • Create a Google Cloud project:

      gcloud projects create PROJECT_ID

      Replace PROJECT_ID with a name for the Google Cloud project you are creating.

    • Select the Google Cloud project that you created:

      gcloud config set project PROJECT_ID

      Replace PROJECT_ID with your Google Cloud project name.

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

  6. Install the Google Cloud CLI.

  7. To initialize the gcloud CLI, run the following command: 

    gcloud init

  8. Create or select a Google Cloud project.

    • Create a Google Cloud project:

      gcloud projects create PROJECT_ID

      Replace PROJECT_ID with a name for the Google Cloud project you are creating.

    • Select the Google Cloud project that you created:

      gcloud config set project PROJECT_ID

      Replace PROJECT_ID with your Google Cloud project name.

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

Scrivere voci di log utilizzando gcloud CLI

Il 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. 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 comando gcloud logging write:

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

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

  2. Scrivi 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, la funzionalità di 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.

Elenca 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 il seguente 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 documentazione di riferimento di gcloud logging read.

Elenca le voci di log utilizzando Explorer API

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

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

    Vai alla pagina dell'API entries.list

  2. Configura ed esegui il comando API:

    1. Sostituisci PROJECT_ID nel seguente testo:

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

    2. Copia il testo aggiornato dal passaggio precedente e incollalo nel campo Request body (Corpo della richiesta) di Explorer API.

    3. Fai clic su Execute (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 console Google Cloud, puoi utilizzare Esplora log. La maggior parte dei progetti Google Cloud archivia un numero elevato di log. Puoi selezionare determinate voci di log scrivendo una query.

Per visualizzare le voci di log che hai scritto utilizzando Esplora log, segui questi passaggi:

  1. Nella console Google Cloud, 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 progetto Google Cloud sia selezionato nella barra di navigazione di Google Cloud. Se necessario, utilizza l'elenco a discesa del progetto Google Cloud per selezionare il tuo progetto Google Cloud.

  2. Nel menu Risorsa, seleziona Globale.

    Se non vedi l'opzione di menu Globale o se non vedi le voci del log, attendi qualche minuto e aggiorna la pagina. Potrebbero essere necessari alcuni minuti prima che la registrazione 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 del 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 tipo LogEntry.

Esegui 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, in base alla chiave e al valore. Ad esempio, per visualizzare tutte le voci di log che contengono il testo simple:

  1. Nella console Google Cloud, 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 ulteriori informazioni sulle query, consulta Creare query in Esplora log.

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

Risoluzione dei problemi

  • Errori ortografici e nomi di campi sconosciuti fanno sì che i comandi gcloud CLI vengano completati con messaggi di argomento non valido. Ad esempio, se dimentichi il punto in resource.type, si verifica l'errore:

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

  • Se a Cloud Logging non sono state concesse le autorizzazioni di accesso necessarie, i comandi gcloud CLI vengono completati con messaggi di autorizzazione negata. Ad esempio, se un'istanza VM 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 correggere questa condizione, modifica le autorizzazioni dell'istanza VM di Compute Engine per concedere l'autorizzazione di lettura a Cloud Logging come segue:

    1. Vai alla pagina Dettagli istanza VM della tua istanza VM. Fai clic su Interrompi. Il completamento dell'azione potrebbe richiedere un paio di minuti.
    2. Per modificare la configurazione, fai clic su Modifica.
    3. Cerca l'intestazione Ambiti di accesso API Cloud e fai clic su Dettagli per visualizzare le impostazioni per ogni API. Modifica la voce da API Cloud Logging a Completa. Fai clic su Salva.
    4. Per riavviare l'istanza VM, fai clic su Avvia. Dopo alcuni istanti, la VM è pronta per essere utilizzata.

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

    • Codice di risposta 200 e nessuna voce: se viene visualizzato il messaggio nextPageToken, significa che Explorer API non ha avuto il tempo di completare la ricerca. Aggiungi un pageToken alla richiesta, imposta il valore su 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 sbagli a scrivere 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 tuo progetto Google Cloud e di consentire ad API Explorer di accedere al tuo account.

Esegui la pulizia

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

  1. (Facoltativo) Per eliminare le voci di log che hai creato, esegui il seguente 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, leggi le pagine di riferimento per il gruppo di comandi gcloud logging.
  • Per la documentazione sull'API Logging, consulta API Cloud Logging.
  • Per informazioni dettagliate su Esplora log, consulta Utilizzo di Esplora log.