Creare e gestire gli ambiti dei log

Questo documento descrive come creare e gestire gli ambiti dei log, che puoi utilizzare per trovare in modo efficiente le voci di log che vuoi visualizzare o analizzare. Se vuoi solo visualizzare e analizzare le voci di log che hanno avuto origine in un progetto, una cartella o un'organizzazione, questo documento non fa per te. Tuttavia, se utilizzi sink di log per instradare i log a altri progetti o a bucket di log definiti dall'utente, o se utilizzi le visualizzazioni dei log, le informazioni in questo documento potrebbero aiutarti a trovare in modo efficiente voci di log specifiche.

Questo documento non descrive come visualizzare i log. Per informazioni su questo argomento, consulta Visualizzare i log utilizzando Esplora log.

Informazioni sugli ambiti dei log

Gli ambiti dei log sono risorse permanenti a livello di progetto che elencano un insieme di risorse. Queste risorse possono essere progetti, cartelle, organizzazioni e visualizzazioni dei log. Ad esempio, puoi definire un ambito di log che elenca i progetti che contengono le risorse utilizzate per la produzione o uno che elenca le visualizzazioni log che includono le voci di log per un tipo di risorsa specifico.

Quando crei un progetto, una cartella o una risorsa organizzazione Google Cloud, logging crea un ambito di log denominato _Default. Questo ambito include il progetto, la cartella o l'organizzazione creati. Quando la risorsa cercata è un progetto, una cartella o un'organizzazione Google Cloud, i risultati includono le voci di log che hanno origine nella risorsa e vengono archiviate in un bucket di log. Quando viene eseguito una ricerca in un progetto, i risultati includono anche le voci di log che vengono instradate al progetto da un'area di destinazione in un altro progetto e poi archiviate in un bucket di log.

Puoi creare ambiti di log. Puoi anche modificare ed eliminare gli ambiti dei log che crei. Tuttavia, non puoi modificare o eliminare l'ambito del log denominato _Default.

Utilizzi un ambito di log per controllare le risorse in cui la pagina Esplora log cerca i dati dei log. Quando apri la pagina e selezioni un ambito di log, la pagina cerca le risorse elencate in quell'ambito e aggiorna la visualizzazione.

Puoi anche utilizzare un ambito dei log per controllare le risorse in cui un riquadro dei log cerca i dati dei log. Un riquadro dei log è un widget della dashboard personalizzata che visualizza i dati dei log. Ogni riquadro dei log ha la propria configurazione, che ti consente di creare una dashboard contenente più riquadri dei log in cui ogni riquadro mostra dati dei log diversi. Per ulteriori informazioni, consulta Visualizzare log ed errori in una dashboard personalizzata.

Per i progetti, l'ambito di log predefinito determina l'insieme di risorse che la pagina Esplora log cerca quando viene aperta. Tuttavia, i ruoli IAM (Identity and Access Management) nelle risorse cercate e l'impostazione dell'intervallo di tempo determinano le voci di log che vengono recuperate dallo spazio di archiviazione. Quando vengono creati i progetti, l'ambito dei log denominato _Default viene designato come ambito dei log predefinito. Puoi impostare l'ambito dei log predefinito.

Best practice

Poiché gli ambiti di log ti consentono di definire e salvare una configurazione per uso futuro, ti consigliamo di creare ambiti di log per configurazioni di ricerca complesse.

Ad esempio, supponiamo che tu stia risolvendo un problema e voglia visualizzare le voci di log per tutte le istanze di macchine virtuali (VM) di proprietà del tuo team. Per svolgere questa attività, puoi procedere nel seguente modo:

  1. Stabilisci che le voci di log che vuoi visualizzare sono archiviate in più bucket di log e in più progetti. Per la maggior parte dei bucket di log, esiste una visualizzazione di log che include le voci di log che vuoi analizzare. Se non esiste una visualizzazione dei log, puoi crearne una.

  2. Decidi di creare un ambito di log perché prevedi di dover svolgere un'attività di risoluzione dei problemi simile in futuro.

  3. Apri la pagina Esplora log nella console Google Cloud e utilizza il menu Perfeziona ambito per selezionare il nuovo ambito dei log.

  4. Esamina le voci dei log e trova le informazioni necessarie per risolvere il problema che stavi esaminando.

  5. Una volta risolto il problema, condividi la causa dell'errore con i colleghi. Inoltre, hai comunicato di prevedere errori simili in futuro, pertanto hai creato un ambito di log che ti consentirà, o a chi sta esaminando l'errore, di trovare rapidamente le voci di log pertinenti.

Limitazioni

  • Non puoi eliminare o modificare l'ambito dei log denominato _Default.
  • Solo i progetti Google Cloud supportano un ambito dei log predefinito.
  • Non puoi aggiungere cartelle o organizzazioni a un ambito dei log definito dall'utente.
  • Gli ambiti di log vengono creati nella posizione global.

Prima di iniziare

  • Per ottenere le autorizzazioni necessarie per creare e visualizzare gli ambiti dei log e per impostare l'ambito dei log predefinito, chiedi all'amministratore di concederti i seguenti ruoli IAM:

    • Per creare e visualizzare gli ambiti dei log o per ottenere l'ambito dei log predefinito: Autore della configurazione dei log (roles/logging.configWriter) nel progetto, nella cartella o nell'organizzazione
    • Per impostare l'ambito dei log predefinito: Editor di osservabilità (roles/observability.editor) nel progetto, nella cartella o nell'organizzazione

    Per saperne di più sulla concessione dei ruoli, consulta Gestire l'accesso a progetti, cartelle e organizzazioni.

    Questi ruoli predefiniti contengono le autorizzazioni necessarie per creare e visualizzare gli ambiti dei log e per impostare l'ambito dei log predefinito. Per visualizzare le autorizzazioni esatte richieste, espandi la sezione Autorizzazioni richieste:

    Autorizzazioni obbligatorie

    Per creare e visualizzare gli ambiti dei log e impostare l'ambito dei log predefinito, sono necessarie le seguenti autorizzazioni:

    • Per ottenere e impostare l'ambito dei log predefinito: observability.scopes.{get, update}

    Potresti anche ottenere queste autorizzazioni con ruoli personalizzati o altri ruoli predefiniti.

  • Select the tab for how you plan to use the samples on this page:

    Console

    When you use the Google Cloud console to access Google Cloud services and APIs, you don't need to set up authentication.

    gcloud

    In the Google Cloud console, activate Cloud Shell.

    Activate Cloud Shell

    At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

    Terraform

    Per utilizzare gli esempi di Terraform in questa pagina in un ambiente di sviluppo locale, installa e inizializza gcloud CLI, quindi configura le Credenziali predefinite dell'applicazione con le tue credenziali utente.

    1. Install the Google Cloud CLI.

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

      gcloud init

    3. If you're using a local shell, then create local authentication credentials for your user account: 

      gcloud auth application-default login

      You don't need to do this if you're using Cloud Shell.

    Per saperne di più, consulta Configurare l'ADC per un ambiente di sviluppo locale nella documentazione sull'autenticazione di Google Cloud.

    REST

    Per utilizzare gli esempi dell'API REST in questa pagina in un ambiente di sviluppo locale, utilizza le credenziali fornite a gcloud CLI.

      Install the Google Cloud CLI, then initialize it by running the following command: 

      gcloud init

    Per ulteriori informazioni, consulta Eseguire l'autenticazione per l'utilizzo di REST nella documentazione sull'autenticazione di Google Cloud.

Elenco degli ambiti dei log

Console

Per elencare gli ambiti dei log:

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

    Vai a Impostazioni

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

  2. Seleziona la scheda Ampi dello log.

    La tabella elenca gli ambiti dei log. Dopo aver selezionato un progetto Google Cloud, una voce della tabella viene visualizzata con un'icona "Predefinito", a indicare che questo ambito di log elenca le risorse cercate da Esplora log quando viene aperta la pagina.

gcloud

Per elencare gli ambiti di log in un progetto, utilizza il comando gcloud logging scopes list:

 gcloud logging scopes list --project=PROJECT_ID

Prima di eseguire il comando, aggiorna i seguenti campi:

  • PROJECT_ID: l'identificatore del progetto.

Per visualizzare i dettagli dell'ambito di un log in un progetto, utilizza il comando gcloud logging scopes describe:

 gcloud logging scopes describe LOG_SCOPE --project=PROJECT_ID

Prima di eseguire il comando, aggiorna i seguenti campi:

  • PROJECT_ID: l'identificatore del progetto.
  • LOG_SCOPE: il nome dell'ambito dei log. Ad esempio, my-scope.

Terraform

Puoi utilizzare Terraform per creare e modificare l'ambito di un log. Tuttavia, non puoi utilizzare Terraform per elencare gli ambiti dei log.

REST

L'API Cloud Logging contiene comandi che elencano gli ambiti di log in una risorsa o che riportano i dettagli di un ambito di log specifico. Per un elenco completo dei comandi, consulta la documentazione di riferimento dell'API.

Per i progetti Google Cloud, utilizza i seguenti comandi:

Nel comando API, imposta il campo locations su global.

Impostare l'ambito dei log predefinito

L'ambito di log predefinito elenca le risorse cercate dalla pagina Esplora log quando viene aperta. Se un ambito dei log predefinito non esiste o non è accessibile, in questa pagina vengono cercate automaticamente le voci di log provenienti dal progetto, dalla cartella o dall'organizzazione selezionata. Le voci di log visualizzate dalla pagina Esplora log dipendono dalle risorse cercate, dall'impostazione dell'intervallo di tempo e dai tuoi ruoli IAM nelle risorse cercate.

Quando vengono creati i progetti, viene creato l'ambito dei log denominato _Default e viene designato come ambito dei log predefinito. Tuttavia, puoi creare il tuo ambito dei log e designarlo come ambito predefinito.

Console

Per impostare l'ambito dei log predefinito:

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

    Vai a Impostazioni

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

  2. Seleziona la scheda Ampi dello log.

  3. Individua l'ambito del log che vuoi designare come ambito predefinito, fai clic su  Altro e poi seleziona Imposta come predefinito.

    L'ambito del log selezionato è mostrato con un'icona "Predefinito",.

gcloud

Non supportati.

Terraform

Puoi utilizzare Terraform per creare e modificare l'ambito di un log. Tuttavia, non puoi utilizzare Terraform per impostare l'ambito dei log predefinito.

REST

Non supportati.

Creare un ambito di log

Puoi creare 100 ambiti di log per progetto. Un ambito di log può includere un totale di 100 visualizzazioni di log e progetti; tuttavia, può includere solo 5 progetti. Non puoi aggiungere cartelle o organizzazioni a un ambito dei log.

Console

Per creare un ambito di log:

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

    Vai a Impostazioni

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

  2. Seleziona la scheda Ampi dello log e fai clic su Crea ambito dello log.

  3. Per aggiungere uno o più progetti, fai clic su Aggiungi progetti e completa la finestra di dialogo.

    Dopo aver aggiunto un progetto, i tuoi ruoli IAM in quel progetto determinano quali voci di log puoi visualizzare. Ad esempio, il tuo ruolo IAM potrebbe consentirti di visualizzare solo le voci di log accessibili da una visualizzazione di log specifica in un bucket di log. Per ulteriori informazioni sui ruoli, consulta Ruoli di logging.

  4. Per aggiungere una o più visualizzazioni dei log, fai clic su Aggiungi visualizzazioni dei log e completa la finestra di dialogo.

    La finestra di dialogo elenca tutte le viste di log con voci di log provenienti dal progetto corrente o instradate al progetto corrente da un'area di destinazione in un altro progetto. Ad esempio, se non hai configurato alcun canale, in questa finestra di dialogo vengono elencate le visualizzazioni dei log nel progetto corrente.

    Per elencare le visualizzazioni dei log archiviate in un altro progetto Google Cloud, fai clic su  Importa progetto e poi seleziona il progetto Google Cloud.

    Dopo aver aggiunto una visualizzazione dei log, i tuoi ruoli IAM nella visualizzazione dei log o nel progetto che la memorizza determinano le voci di log a cui puoi accedere. Per ulteriori informazioni, consulta Controllare l'accesso a una visualizzazione dei log.

  5. Nella sezione Nome ambito log, inserisci il nome e la descrizione che vuoi visualizzare nella scheda Ambiti log.

    Il nome di un ambito dei log non può essere modificato e deve essere univoco all'interno del progetto.

  6. Fai clic su Crea ambito log.

gcloud

Per creare un ambito di log in un progetto, utilizza il comando gcloud logging scopes create:

 gcloud logging scopes create LOG_SCOPE --project=PROJECT_ID \
   --description=DESCRIPTION \
   --resource-names=RESOURCE_NAMES

Prima di eseguire il comando, aggiorna i seguenti campi:

  • PROJECT_ID: l'identificatore del progetto.

  • LOG_SCOPE: il nome dell'ambito dei log. Ad esempio, my-scope.

  • DESCRIPTION: facoltativo. La descrizione dell'ambito dei log. Formatta la descrizione come stringa.

  • RESOURCE_NAMES: un elenco separato da virgole dei nomi completi di progetti o visualizzazioni dei log. Ad esempio, per includere my-project nell'ambito del log, specifica projects/my-project.

Terraform

Per scoprire come applicare o rimuovere una configurazione Terraform, consulta Comandi Terraform di base. Per ulteriori informazioni, consulta la Terraform documentazione di riferimento del provider.

Per creare un ambito dei log in un progetto, in una cartella o in un'organizzazione utilizzando Terraform, utilizza la risorsa Terraform google_logging_log_scope.

Nel comando, imposta i seguenti campi:

  • parent: il nome completo del progetto, della cartella o dell'organizzazione. Ad esempio, puoi impostare questo campo su "projects/PROJECT_ID", dove PROJECT_ID è l'ID del progetto Google Cloud.
  • locations: impostato su "global".

  • name: impostato sul nome completo dell'ambito del log. Per i progetti, il formato di questo campo è:

    "projects/PROJECT_ID/locations/global/logScopes/LOG_SCOPE"

    Nell'espressione precedente, LOG_SCOPE è il nome di un ambito del log, ad esempio "produzione".

  • resource_names: un array di progetti e visualizzazioni log, in cui ogni progetto e visualizzazione log è specificato utilizzando il nome completo.

  • description: una breve descrizione. Ad esempio, "Ambito per le risorse di produzione".

REST

L'API Cloud Logging supporta anche la creazione di ambiti di log in una cartella o un'organizzazione. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API.

Per i progetti Google Cloud, utilizza il seguente comando:

Nel comando API, imposta il campo locations su global.

Modificare o eliminare l'ambito di un log

Console

Per modificare o eliminare l'ambito di un log creato da te o da un collega:

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

    Vai a Impostazioni

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

  2. Seleziona la scheda Ampi dello log.

  3. Individua gli ambiti di log che vuoi modificare o eliminare, fai clic su  Altro e poi esegui una delle seguenti operazioni:

    • Per modificarlo, seleziona Modifica ambito e poi completa la finestra di dialogo.
    • Per eliminare, seleziona Elimina ambito e completa la finestra di dialogo.

gcloud

Per modificare la descrizione dell'elenco di risorse in un ambito del log in un progetto, utilizza il comando gcloud logging scopes update:

 gcloud logging scopes update LOG_SCOPE --project=PROJECT_ID \
   --description=DESCRIPTION \
   --resource-names=RESOURCE_NAMES

Prima di eseguire il comando, aggiorna i seguenti campi:

  • PROJECT_ID: l'identificatore del progetto.

  • LOG_SCOPE: il nome dell'ambito dei log. Ad esempio, my-scope.

  • DESCRIPTION: la descrizione dell'ambito dei log. Formatta la descrizione come stringa. Ometti questo campo se non vuoi modificare la descrizione dell'ambito del log.

  • RESOURCE_NAMES: un elenco separato da virgole dei nomi completi di progetti o visualizzazioni dei log. Ometti questo campo se non vuoi modificare l'elenco delle risorse.

Per eliminare l'ambito di un log in un progetto, utilizza il comando gcloud logging scopes delete:

 gcloud logging scopes delete LOG_SCOPE --project=PROJECT_ID

Prima di eseguire il comando, aggiorna i seguenti campi:

  • PROJECT_ID: l'identificatore del progetto.
  • LOG_SCOPE: il nome dell'ambito dei log. Ad esempio, my-scope.

Terraform

Per scoprire come applicare o rimuovere una configurazione Terraform, consulta Comandi Terraform di base. Per ulteriori informazioni, consulta la Terraform documentazione di riferimento del provider.

Per modificare l'ambito dei log in un progetto, una cartella o un'organizzazione utilizzando Terraform, utilizza la risorsa Terraform google_logging_log_scope.

REST

L'API Cloud Logging contiene comandi che possono modificare o eliminare un ambito log. Per un elenco completo dei comandi, consulta la documentazione di riferimento dell'API.

Per i progetti Google Cloud, utilizza i seguenti comandi:

Nel comando API, imposta il campo locations su global.

Passaggi successivi