Configurare gli ambiti di osservabilità per le query su più progetti

Questo documento descrive come creare grafici o visualizzare i dati di log quando questi sono archiviati in più progetti. Per impostazione predefinita, gli strumenti di visualizzazione possono accedere solo ai dati che hanno origine in un progetto. Tuttavia, se configuri un ambito, gli strumenti di visualizzazione e analisi possono eseguire query sui dati archiviati in più progetti.

Se vuoi solo monitorare o visualizzare i dati archiviati in un progettoGoogle Cloud , non devi eseguire alcuna configurazione.

Gli ambiti forniscono l'aggregazione in tempo reale

Gli ambiti consentono agli strumenti di visualizzazione e analisi di eseguire l'aggregazione in fase di lettura dei dati archiviati in più posizioni. Gli ambiti non controllano dove vengono archiviati i dati. I motori di query si basano invece sugli ambiti per determinare dove cercare i dati.

I dati delle metriche e delle tracce vengono sempre archiviati nel progetto Google Cloud in cui hanno origine. Per visualizzare i dati delle metriche archiviati in più progetti in un unico grafico, configura un ambito delle metriche per elencare questi progetti. Dopo aver configurato questo ambito, quando crei un grafico o una criterio di avviso, la query emessa da questi servizi restituisce automaticamente i dati delle metriche dei progetti elencati. Il comportamento è simile per i dati di traccia.

Per impostazione predefinita, i dati di log vengono archiviati nel progetto, nell'account di fatturazione, nella cartella o nell'organizzazione da cui provengono i dati. Google Cloud Tuttavia, puoi configurare Logging per indirizzare i dati di log dalla risorsa di origine a un'altra posizione, ad esempio un altro progetto o un bucket di log centralizzato. In tutti i casi, configura un ambito dei log personalizzato. Ti consigliamo di utilizzare le visualizzazioni di log anziché i progetti negli elenchi degli ambiti dei log. Una visualizzazione di log fornisce l'accesso in lettura a un sottoinsieme di voci di log in un bucket di log. Ad esempio, se hai dati di log archiviati in tre progetti, puoi configurare la visualizzazione log in modo da includere la visualizzazione _Default/_AllLogs per ciascuno di questi progetti.

Come vengono utilizzati gli ambiti da Google Cloud Observability

Gli strumenti di analisi e visualizzazione di Google Cloud Observability si basano su ambiti specifici per tipo di dati per determinare le risorse da interrogare per i dati che lo strumento deve visualizzare o analizzare.

Esempi:

  • Quando si apre la pagina Esplora log, il sistema esegue query sulle risorse elencate nell'ambito di log predefinito per i dati di log. Dopo aver aperto questa pagina, puoi utilizzare un'opzione della barra degli strumenti per eseguire query sulle risorse in un ambito diverso.
  • Quando si apre la pagina Esplora tracce, il sistema esegue query sui progetti elencati nell'ambito della traccia predefinito per i dati di traccia. Dopo aver aperto questa pagina, puoi utilizzare un'opzione della barra degli strumenti per eseguire query sulle risorse in un ambito diverso.
  • Quando crei una criterio di avviso, Monitoring esegue query sui progetti elencati nell'ambito delle metriche per i dati delle metriche. Quindi analizza la risposta alla query e determina se creare un incidente.
  • Quando crei un grafico utilizzando la pagina Esplora metriche, devi specificare una metrica da rappresentare nel grafico. Monitoring esegue query sui progetti elencati nell'ambito delle metriche per i dati delle metriche, quindi visualizza i risultati della query.

Logging e Trace verificano i tuoi ruoli IAM (Identity and Access Management) su una risorsa prima che una query restituisca i dati. Ad esempio, se un ambito dei log specifica un progetto per il quale non ti sono state concesse le autorizzazioni per leggere i dati di log, una query a quel progetto non restituisce dati.

Monitoring verifica il tuo ruolo IAM sul progetto da cui viene emessa la query. Supponiamo che l'ambito delle metriche per un progetto denominato AllEnv elenchi i seguenti progetti: AllEnv, Prod e Staging. Inoltre, supponi di aver ricevuto il ruolo Visualizzatore Monitoring nel progetto AllEnv. I grafici creati con la pagina Esplora metriche quando utilizzi il progetto AllEnv mostrano automaticamente i dati delle metriche per i tre progetti.

Ambiti di Google Cloud Observability

Questa sezione descrive gli ambiti utilizzati da Google Cloud Observability.

Ambito di osservabilità

L'ambito di osservabilità specifica l'ambito dei log predefinito e l'ambito della traccia predefinito. Pagine come Esplora log ed Esplora tracce utilizzano gli ambiti predefiniti per determinare le risorse da sottoporre a query all'apertura della pagina. Ad esempio, supponiamo di avere un'applicazione che genera dati di traccia in tre progetti. Puoi configurare la pagina Esplora tracce per eseguire automaticamente query su questi tre progetti impostando l'ambito della traccia predefinito.

Se non configuri l'ambito di osservabilità, si verificano le seguenti situazioni:

  • La pagina Esplora log esegue query nel progetto per i dati di log.
  • La pagina Esplora tracce esegue query sul progetto per i dati di traccia.

L'ambito di osservabilità non si applica ai dati delle metriche.

Quando configurare l'ambito di osservabilità

Configura l'ambito di osservabilità nei seguenti scenari:

  • Crei un ambito di log personalizzato e vuoi che le risorse elencate in questo ambito vengano interrogate per impostazione predefinita.

  • Crei un ambito di traccia personalizzato e vuoi che i progetti elencati in questo ambito vengano interrogati per impostazione predefinita.

Limiti associati agli ambiti di osservabilità

Descrizione Valore massimo
Numero di ambiti di osservabilità per progetto 1

Ambiti dei log

Gli ambiti dei log vengono utilizzati dalla pagina Esplora log e dalle dashboard che mostrano i dati dei log:

  • Quando si apre la pagina Esplora log, il sistema esegue automaticamente query sulle risorse elencate nell'ambito di log predefinito per i dati di log. Questa pagina fornisce anche controlli che ti consentono di passare da un ambito all'altro.

  • Per le dashboard, l'implementazione determina se il sistema esegue query sul progetto o sulle risorse elencate nell'ambito di log predefinito.

Un ambito di log può elencare visualizzazioni di log, progetti, cartelle e organizzazioni.

Se non configuri un ambito dei log personalizzato, la pagina Esplora log esegue query nel tuo progetto per i dati di log.

Quando creare ambiti dei log personalizzati

Crea ambiti di log personalizzati per le seguenti configurazioni:

In tutti i casi, configura gli ambiti dei log personalizzati in modo da elencare una o più visualizzazioni dei log. Queste visualizzazioni dei log potrebbero trovarsi in un bucket di log centralizzato oppure in bucket di log diversi. Se utilizzi un bucket di log centralizzato, puoi creare più ambiti dei log personalizzati, ognuno con il proprio set di visualizzazioni dei log.

Se crei ambiti di log personalizzati, valuta la possibilità di aggiornare l'ambito di log predefinito.

Best practice per la configurazione degli ambiti dei log

  • Includi solo le visualizzazioni log.
  • Non configurare un ambito che elenca sia progetti che visualizzazioni di log.

Limiti associati agli ambiti dei log

Descrizione Valore massimo
Numero di ambiti dei log per progetto 100
Numero di progetti per ambito dei log 5
Numero di visualizzazioni log o progetti per ambito di log 100

Per saperne di più, consulta la pagina Creare e gestire gli ambiti dei log.

Ambito delle metriche

L'ambito delle metriche viene utilizzato da tutte le query emesse da Cloud Monitoring. Ad esempio, le query relative a policy di avviso e strumenti di creazione di grafici come Metrics Explorer vengono inviate ai progetti elencati nell'ambito delle metriche.

Se non configuri l'ambito delle metriche, i servizi Monitoring eseguono query sul tuo progetto per i dati delle metriche.

Quando configurare gli ambiti delle metriche

Configura l'ambito delle metriche quando si verifica una delle seguenti condizioni:

Limiti associati agli ambiti delle metriche

Descrizione Valore massimo
Numero di ambiti delle metriche per progetto 1
Numero di progetti per ambito delle metriche 375

Per ulteriori informazioni, consulta la panoramica degli ambiti delle metriche.

Ambiti delle tracce

Gli ambiti Trace vengono utilizzati dalla pagina Esplora tracce. Quando si apre questa pagina, il sistema esegue automaticamente query sui progetti elencati nell'ambito della traccia predefinito per i dati di traccia. Questa pagina fornisce anche controlli che ti consentono di passare da un ambito all'altro.

Se non configuri un ambito di traccia personalizzato, la pagina Esplora tracce esegue query nel tuo progetto per i dati di traccia.

Quando creare ambiti di traccia personalizzati

Crea ambiti di traccia personalizzati quando hai applicazioni che si basano su risorse in progetti Google Cloud diversi.

Limiti associati agli ambiti delle tracce

Descrizione Valore massimo
Numero di ambiti della traccia per progetto 100
Numero di progetti per ambito della traccia 20

Per saperne di più, consulta la pagina Creare e gestire gli ambiti di traccia.

Configurare l'ambito dell'osservabilità

Questa sezione non si applica a cartelle o organizzazioni.

Per i dati di log e traccia, i tuoi ruoli Identity and Access Management (IAM) nel progetto che stai visualizzando e in tutti i progetti e le visualizzazioni log in cui hai eseguito ricerche influiscono sui dati restituiti dalla query. Se esegui una query per visualizzare i dati di log per cui non disponi dell'autorizzazione, la query non restituisce alcun dato di log.

Per i dati delle metriche, quando viene configurato l'ambito delle metriche di un progetto, al progetto viene concesso l'accesso in lettura ai dati delle metriche archiviati dai progetti elencati nel relativo ambito delle metriche. Quando a un utente viene concesso un ruolo Identity and Access Management che gli consente di visualizzare i dati delle metriche in un progetto, può visualizzare i dati delle metriche disponibili per il progetto.

Per configurare l'ambito di osservabilità, imposta l'ambito dei log predefinito e l'ambito della traccia predefinito. Il resto di questa sezione descrive come completare queste azioni.

Prima di iniziare

  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. In the Google Cloud console, on the project selector page, select or create a Google 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

  3. Verify that billing is enabled for your Google Cloud project.

  4. Enable the Observability API.

    Roles required to enable APIs

    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

    Enable the API

  5. In the Google Cloud console, on the project selector page, select or create a Google 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

  6. Verify that billing is enabled for your Google Cloud project.

  7. Enable the Observability API.

    Roles required to enable APIs

    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

    Enable the API

    8.

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

    • Per creare e visualizzare gli ambiti dei log e per ottenere l'ambito dei log predefinito: Writer configurazione log (roles/logging.configWriter) sul tuo progetto
    • Per modificare un ambito delle metriche: Monitoring Admin (roles/monitoring.admin) sul tuo progetto e su ogni progetto che vuoi aggiungere agli ambiti delle metriche
    • Per creare e visualizzare gli ambiti di traccia e per ottenere e impostare gli ambiti predefiniti: Observability Scopes Editor (roles/observability.scopesEditor) sul tuo progetto

    Per ulteriori informazioni 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.

    Il ruolo Editor ambiti di osservabilità include autorizzazioni private che ti consentono di creare e visualizzare gli ambiti di traccia. Queste autorizzazioni non sono disponibili per l'inclusione nei ruoli IAM personalizzati.

  9. 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.

    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. Dopo l'installazione, inizializza Google Cloud CLI eseguendo il seguente comando: 

      gcloud init

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

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

    Visualizzare e impostare l'ambito predefinito

    Console

    Per configurare l'ambito di osservabilità, devi configurare i relativi componenti, ovvero l'ambito dei log predefinito, l'ambito delle metriche e l'ambito delle tracce 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. Nella barra degli strumenti della console Google Cloud , seleziona il tuo progetto Google Cloud . Per le configurazioni di App Hub, seleziona il progetto host di App Hub o il progetto di gestione della cartella app.

    3. Configura l'ambito dei log predefinito:

      1. Seleziona la scheda Ambiti dei log.

        Vengono elencati gli ambiti dei log esistenti. La voce con l'icona "Predefinito", , è l'ambito dei log predefinito. Se vuoi creare un ambito log, fai clic su Crea ambito log e poi completa la finestra di dialogo. Per saperne di più, vedi Creare e gestire gli ambiti dei log.

      2. Trova la voce che vuoi impostare come predefinita, fai clic su  Altro, quindi seleziona Imposta come predefinito.

    4. Configura l'ambito delle metriche:

      1. Seleziona la scheda Ambito delle metriche.
      2. Nel riquadro Progetti Google Cloud, fai clic su Aggiungi progetti e poi completa la finestra di dialogo. Per maggiori informazioni, consulta la pagina Configurare gli ambiti delle metriche.

    5. Configura l'ambito della traccia predefinito:

      1. Seleziona la scheda Ambiti di traccia e poi procedi nel seguente modo:

        Vengono elencati gli ambiti di traccia esistenti. La voce con l'icona "Predefinito", , è l'ambito di traccia predefinito. Se vuoi creare un ambito di traccia, fai clic su Crea ambito log e poi completa la finestra di dialogo. Per saperne di più, consulta la pagina Creare e gestire gli ambiti di traccia.

      2. Trova la voce che vuoi impostare come predefinita, fai clic su  Altro, quindi seleziona Imposta come predefinito.

    gcloud

    Per visualizzare e impostare l'ambito di osservabilità:

    1. Per visualizzare le impostazioni dell'ambito di osservabilità, esegui il comando gcloud observability scopes describe.

      Prima di utilizzare i dati dei comandi riportati di seguito, effettua le seguenti sostituzioni:

      • OBSERVABILITY_SCOPE_ID: il nome di un oggetto Scope. Questo valore deve essere impostato su _Default.
      • LOCATION: il campo della località deve essere impostato su global.
      • PROJECT_ID: l'identificatore del progetto.

      Esegui il comando gcloud observability scopes describe:

      Linux, macOS o Cloud Shell

      gcloud observability scopes describe OBSERVABILITY_SCOPE_ID \
   --location=LOCATION\
   --project=PROJECT_ID

      Windows (PowerShell)

      gcloud observability scopes describe OBSERVABILITY_SCOPE_ID `
   --location=LOCATION`
   --project=PROJECT_ID

      Windows (cmd.exe)

      gcloud observability scopes describe OBSERVABILITY_SCOPE_ID ^
   --location=LOCATION^
   --project=PROJECT_ID

      La risposta al comando è simile alla seguente: 

      logScope: logging.googleapis.com/projects/my-project/locations/global/logScopes/_Default
traceScope: projects/my-project/locations/global/traceScopes/_Default
name: projects/my-project/locations/global/scopes/_Default

    2. Per aggiornare l'ambito di osservabilità, esegui il comando gcloud observability scopes update. Nel comando update, puoi includere il flag --log-scope per aggiornare l'ambito dei log predefinito.

      Prima di utilizzare i dati dei comandi riportati di seguito, effettua le seguenti sostituzioni:

      • OBSERVABILITY_SCOPE_ID: il nome di un oggetto Scope. Questo valore deve essere impostato su _Default.
      • LOG_SCOPE_FQN_ID: l'ID completo dell'ambito dei log. Questo campo ha il seguente formato: 
        logging.googleapis.com/projects/PROJECT_ID/locations/LOCATION/logScopes/LOG_SCOPE_ID

        Nell'espressione precedente, LOG_SCOPE_ID è l'ID dell'ambito del log. Ad esempio, my-scope.

      • LOCATION: il campo della località deve essere impostato su global.
      • PROJECT_ID: l'identificatore del progetto.

      Esegui il comando gcloud observability scopes update:

      Linux, macOS o Cloud Shell

      gcloud observability scopes update OBSERVABILITY_SCOPE_ID \
   --log-scope=LOG_SCOPE_FQN_ID\
   --location=LOCATION\
   --project=PROJECT_ID

      Windows (PowerShell)

      gcloud observability scopes update OBSERVABILITY_SCOPE_ID `
   --log-scope=LOG_SCOPE_FQN_ID`
   --location=LOCATION`
   --project=PROJECT_ID

      Windows (cmd.exe)

      gcloud observability scopes update OBSERVABILITY_SCOPE_ID ^
   --log-scope=LOG_SCOPE_FQN_ID^
   --location=LOCATION^
   --project=PROJECT_ID

      Ad esempio, se il valore di LOG_SCOPE_ID è my-scope, la risposta è simile alla seguente: 

      Updated scope [_Default].
logScope: logging.googleapis.com/projects/my-project/locations/global/logScopes/my-scope
name: projects/my-project/locations/global/scopes/_Default

    REST

    Per ottenere e impostare l'ambito dei log predefinito o l'ambito delle tracce predefinito utilizzando una chiamata API, configura l'ambito di osservabilità. L'ambito di osservabilità elenca l'ambito dei log predefinito e l'ambito della traccia predefinito:

    • Per ottenere l'ambito di osservabilità predefinito per un progetto, invia una richiesta all'endpoint projects.locations.scopes.get. Devi specificare un parametro di percorso. La risposta è un oggetto Scope, che elenca l'ambito dei log predefinito e l'ambito delle tracce predefinito.

    • Per aggiornare l'ambito di osservabilità predefinito per un progetto, invia una richiesta all'endpoint projects.locations.scopes.patch. Devi specificare un parametro di percorso, parametri di ricerca e fornire un oggetto Scope. I parametri di ricerca identificano i campi modificati. La risposta è un oggetto Scope.

    Il parametro percorso per entrambi gli endpoint ha il seguente formato:

    projects/PROJECT_ID/locations/LOCATION/scopes/OBSERVABILITY_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: il campo della località deve essere impostato su global.
    • OBSERVABILITY_SCOPE_ID: il nome di un oggetto Scope. Questo campo deve essere impostato su _Default. L'oggetto Scope con il nome _Default, creato automaticamente, memorizza informazioni sull'ambito dei log predefinito e sull'ambito di traccia predefinito.

    Per inviare un comando a un endpoint API, puoi utilizzare Explorer API, che ti consente di inviare un comando da una pagina di riferimento. Ad esempio, per ottenere l'ambito predefinito corrente, puoi procedere nel seguente modo:

    1. Fai clic su projects.locations.scopes.get.

    2. Nel widget Prova questo metodo, inserisci quanto segue nel campo Nome:

      projects/PROJECT_ID/locations/global/scopes/_Default

      Prima di copiare il campo precedente, sostituisci PROJECT_ID con il nome del tuo progetto.

    3. Seleziona Esegui.

    4. Nella finestra di dialogo di autorizzazione, completa i passaggi richiesti.

      La risposta è simile alla seguente:

      {
"name": "projects/my-project/locations/global/scopes/_Default",
"logScope": "logging.googleapis.com/projects/my-project/locations/global/logScopes/_Default"
"traceScope": "projects/my-project/locations/global/traceScopes/_Default"
}

    Ulteriori informazioni sugli ambiti

    Per saperne di più sugli ambiti, consulta i seguenti documenti: