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 origine in un progetto, una cartella o un'organizzazione, questo documento non fa al caso tuo. Tuttavia, se utilizzi i sink di log per indirizzare i log ad altri progetti o a bucket di log definiti dall'utente oppure se utilizzi le visualizzazioni log, le informazioni contenute 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, vedi Visualizza 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 log. Ad esempio, puoi definire un ambito di log che elenca i progetti che contengono risorse utilizzate per la produzione oppure uno che elenca le visualizzazioni log che includono voci di log per un tipo di risorsa specifico.

Quando crei una risorsa progetto, cartella o organizzazione Trusted Cloud , Logging crea un ambito log denominato _Default. Questo ambito include il progetto, la cartella o l'organizzazione che è stata creata. Quando una risorsa cercata è un progetto, una cartella o un'organizzazione Trusted Cloud , i risultati includono le voci di log che hanno origine nella risorsa e vengono poi archiviate in un bucket di log. Il bucket di log può trovarsi in qualsiasi progetto. Quando viene eseguita la ricerca in un progetto, i risultati includono anche le voci di log instradate al progetto da un sink in un altro progetto e poi archiviate in un bucket di log.

Puoi creare ambiti dei 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 di log. Quando apri questa pagina e selezioni un ambito dei log, la pagina esegue la ricerca nelle risorse elencate in quell'ambito e poi aggiorna la visualizzazione.

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

Differenza tra gli ambiti dei log e l'archiviazione centralizzata dei log

Sia l'archiviazione centralizzata dei log sia gli ambiti dei log ti consentono di visualizzare i dati di log provenienti da progetti diversi.

Quando centralizzi l'archiviazione dei log, configuri i sink in un'organizzazione o una cartella per indirizzare le voci di log a un'unica posizione di archiviazione. L'archiviazione centralizzata fornisce un'unica posizione per eseguire query sui dati dei log, il che semplifica le query quando cerchi tendenze o indaghi su problemi. Dal punto di vista della sicurezza, hai anche una posizione di archiviazione, che semplifica le attività degli analisti della sicurezza.

Quando viene eseguita una query sulle risorse elencate in un ambito dei log, i singoli risultati della query vengono combinati. Un ambito dei log facilita l'aggregazione in fase di lettura dei dati di log che potrebbero essere archiviati in posizioni diverse. Tuttavia, un ambito del log può essere utilizzato anche per fornire l'accesso in lettura a una o più visualizzazioni dei log in un bucket di log centralizzato.

Quando si apre la pagina Esplora log, vengono eseguite query sulle risorse elencate nell'ambito di log predefinito. Pertanto, configura l'ambito predefinito in modo che la pagina mostri i dati che di solito vuoi visualizzare. Ad esempio, puoi impostare l'ambito dei log predefinito per elencare una visualizzazione dei log che, quando viene eseguita una query, restituisce i dati dei log per un'applicazione App Hub.

Best practice

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

Ad esempio, supponi di risolvere un problema e di voler 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. Determini 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 dei log perché prevedi di dover svolgere una risoluzione dei problemi simile in futuro.

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

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

  5. Una volta risolto il problema, condividi la causa dell'errore con i tuoi colleghi. Inoltre, prevedi di riscontrare errori simili in futuro, quindi hai creato un ambito dei log che consentirà a te o a chiunque stia esaminando l'errore di trovare rapidamente le voci di log pertinenti.

Applicazioni App Hub e ambiti dei log

Le tue applicazioni App Hub potrebbero scrivere dati di log in più progetti. I dati di log potrebbero essere archiviati nel progetto in cui hanno origine oppure un amministratore dell'organizzazione potrebbe aver configurato l'archiviazione centralizzata. Per visualizzare i dati di log della tua applicazione, crea un ambito log, configuralo in modo che elenchi i progetti o le visualizzazioni log che archiviano i dati di log della tua applicazione e poi configuralo come ambito log predefinito. Una volta completati questi passaggi, la pagina Esplora log mostra automaticamente i dati scritti dalla tua applicazione, anche se questi dati sono archiviati in progetti diversi o in un bucket di log centralizzato.

Crea l'ambito dei log personalizzato nel progetto da cui visualizzerai i dati dei log. Questo progetto è il progetto host di App Hub o il progetto di gestione della cartella abilitata per le app. Ad esempio, se il nome visualizzato della cartella è My Folder, il nome visualizzato del progetto di gestione è My Folder-mp.

Limitazioni

  • Non puoi eliminare o modificare l'ambito dei log denominato _Default.
  • Solo i progetti Trusted 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 località global.

Prima di iniziare

  1. In the Trusted Cloud console, on the project selector page, select or create a Trusted Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  2. Verify that billing is enabled for your Trusted Cloud project.

  3. Per ottenere le autorizzazioni necessarie per creare e visualizzare gli ambiti dei log, chiedi all'amministratore di concederti i seguenti ruoli IAM nel progetto:

    Per ulteriori informazioni sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

    Questi ruoli predefiniti contengono le autorizzazioni necessarie per creare e visualizzare gli ambiti dei log. Per vedere quali sono esattamente le autorizzazioni richieste, espandi la sezione Autorizzazioni obbligatorie:

    Autorizzazioni obbligatorie

    Per creare e visualizzare gli ambiti dei log sono necessarie le seguenti autorizzazioni:

    • Per impostare l'ambito dei log predefinito: observability.scopes.{get, update}
    • Per creare e gestire gli ambiti dei log: logging.logScopes.{create, delete, get, list, update}

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

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

    gcloud

    Installa Google Cloud CLI, quindi accedi a gcloud CLI con la tua identità federata. Dopo aver eseguito l'accesso, inizializza Google Cloud CLI eseguendo il seguente comando: 

    gcloud init

    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 e con le tue credenziali utente.

    1. Install the Google Cloud CLI.

    2. Configura gcloud CLI per utilizzare la tua identità federata.

      Per ulteriori informazioni, vedi Accedi a gcloud CLI con la tua identità federata.

    3. Create local authentication credentials for your user account: 

      gcloud auth application-default login

      If an authentication error is returned, and you are using an external identity provider (IdP), confirm that you have signed in to the gcloud CLI with your federated identity.

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

    REST

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

      Installa Google Cloud CLI, quindi accedi a gcloud CLI con la tua identità federata.

    Per saperne di più, consulta Autenticarsi per l'utilizzo di REST nella documentazione sull'autenticazione di Trusted Cloud .

    Elenca gli ambiti dei log

    gcloud

    Per elencare gli ambiti dei 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 le configurazioni di App Hub, seleziona il progetto host di App Hub o il progetto di gestione della cartella app.

    Per ottenere i dettagli di un ambito dei log in un progetto, utilizza il comando gcloud logging scopes describe:

     gcloud logging scopes describe LOG_SCOPE_ID --project=PROJECT_ID

    Prima di eseguire il comando, aggiorna i seguenti campi:

    • PROJECT_ID: l'identificatore del progetto.
    • LOG_SCOPE_ID: l'ID dell'ambito dei log. Ad esempio, my-scope.

    Terraform

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

    REST

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

    Per i progetti Trusted Cloud , utilizza i seguenti comandi:

    Nei comandi precedenti, il campo parent ha la seguente sintassi:

    projects/PROJECT_ID/locations/LOCATION_ID

    I campi nell'espressione precedente hanno il seguente significato:

    • PROJECT_ID: l'identificatore del progetto. Per le configurazioni di App Hub, seleziona il progetto host di App Hub o il progetto di gestione della cartella app.
    • LOCATION_ID deve essere impostato su global.

    Crea un ambito di log

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

    gcloud

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

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

    Prima di eseguire il comando, aggiorna i seguenti campi:

    • PROJECT_ID: l'identificatore del progetto. Per le configurazioni di App Hub, seleziona il progetto host di App Hub o il progetto di gestione della cartella app.
    • LOG_SCOPE_ID: l'ID 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 log. Ad esempio, per includere my-project nell'ambito dei log, specifica projects/my-project.

    Terraform

    Per scoprire come applicare o rimuovere una configurazione Terraform, consulta Comandi Terraform di base. Per saperne di più, consulta la documentazione di riferimento del fornitore Terraform.

    Per creare un ambito dei log in un progetto, una cartella o 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 tuo progetto Trusted Cloud . Per le configurazioni di App Hub, seleziona il progetto host di App Hub o il progetto di gestione della cartella app.
    • locations: impostato su "global".

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

      "projects/PROJECT_ID/locations/global/logScopes/LOG_SCOPE_ID"

      Nell'espressione precedente, LOG_SCOPE_ID è il nome di un ambito log, ad esempio "production".

    • 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, "Scope for production resources".

    REST

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

    Per i progetti Trusted Cloud , utilizza il seguente comando:

    Nei comandi precedenti, il campo parent ha la seguente sintassi:

    projects/PROJECT_ID/locations/LOCATION_ID

    I campi nell'espressione precedente hanno il seguente significato:

    • PROJECT_ID: l'identificatore del progetto. Per le configurazioni di App Hub, seleziona il progetto host di App Hub o il progetto di gestione della cartella app.
    • LOCATION_ID deve essere impostato su global.

    Modificare o eliminare un ambito log

    gcloud

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

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

    Prima di eseguire il comando, aggiorna i seguenti campi:

    • PROJECT_ID: l'identificatore del progetto. Per le configurazioni di App Hub, seleziona il progetto host di App Hub o il progetto di gestione della cartella app.
    • LOG_SCOPE_ID: l'ID dell'ambito dei log. Ad esempio, my-scope.

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

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

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

     gcloud logging scopes delete LOG_SCOPE_ID --project=PROJECT_ID

    Prima di eseguire il comando, aggiorna i seguenti campi:

    • PROJECT_ID: l'identificatore del progetto. Per le configurazioni di App Hub, seleziona il progetto host di App Hub o il progetto di gestione della cartella app.
    • LOG_SCOPE_ID: l'ID dell'ambito dei log. Ad esempio, my-scope.

    Terraform

    Per scoprire come applicare o rimuovere una configurazione Terraform, consulta Comandi Terraform di base. Per saperne di più, consulta la documentazione di riferimento del fornitore Terraform.

    Per modificare un 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 dei log. Per un elenco completo dei comandi, consulta la documentazione di riferimento dell'API.

    Per i progetti Trusted Cloud , utilizza i seguenti comandi:

    Nei comandi precedenti, il campo parent ha la seguente sintassi:

    projects/PROJECT_ID/locations/LOCATION_ID/logScopes/LOG_SCOPE_ID

    I campi nell'espressione precedente hanno il seguente significato:

    • PROJECT_ID: l'identificatore del progetto. Per le configurazioni di App Hub, seleziona il progetto host di App Hub o il progetto di gestione della cartella app.
    • LOCATION_ID deve essere impostato su global.
    • LOG_SCOPE_ID: l'ID dell'ambito dei log. Ad esempio, my-scope.

    Passaggi successivi