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, solo i dati che hanno origine in un progetto sono disponibili per gli strumenti di visualizzazione. 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 scope forniscono l'aggregazione in fase di lettura

Gli ambiti consentono agli strumenti di visualizzazione e analisi di eseguire l'aggregazione in fase di lettura dei dati archiviati in più località. 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 di metriche e tracce vengono sempre archiviati nel progetto Google Cloud da cui provengono. Per visualizzare i dati delle metriche archiviati in più progetti in un unico grafico, configura un ambito delle metriche in modo da elencare i progetti. Dopo aver configurato questo ambito, quando crei un grafico o una criterio di avviso, la query eseguita 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 Google Cloud da cui provengono. Tuttavia, puoi configurare Logging in modo che instradi i dati di log dalla risorsa in cui hanno 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 elencare le visualizzazioni di log anziché i progetti nell'ambito 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 il tipo di dati per determinare su quali risorse eseguire query 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. Una volta aperta 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 avviso.
  • Quando crei un grafico utilizzando la pagina Esplora metriche, specifichi una metrica da inserire nel grafico. Monitoring esegue query sui progetti elencati nell'ambito delle metriche per i dati delle metriche, quindi visualizza i risultati delle query.

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

Monitoring verifica il tuo ruolo IAM nel progetto da cui viene eseguita la query. Supponiamo che l'ambito delle metriche per un progetto denominato AllEnv elenchi i seguenti progetti: AllEnv, Prod e Staging. Inoltre, supponiamo che ti sia stato concesso il ruolo Visualizzatore Monitoring per il progetto AllEnv. I grafici che crei 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 su cui eseguire query all'apertura della pagina. Ad esempio, supponiamo che tu abbia un'applicazione che genera dati di traccia in tre progetti. Puoi configurare la pagina Esplora tracce in modo che esegua automaticamente query su questi tre progetti impostando l'ambito di traccia predefinito.

Se non configuri l'ambito di osservabilità, si verifica quanto segue:

  • La pagina Esplora log esegue query sul 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 quell'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 di 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 i 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 sul progetto per i dati di log.

Quando creare ambiti dei log personalizzati

Crea ambiti dei log personalizzati per le seguenti configurazioni:

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

Se crei un ambito dei log personalizzato, valuta la possibilità di aggiornare l'ambito dei log predefinito.

Best practice per la configurazione degli ambiti dei log

  • Includi solo le visualizzazioni log.
  • Non configurare un ambito che elenchi sia i progetti sia le 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 di log o progetti per ambito di log 100

Per saperne di più, consulta Crea e gestisci gli ambiti dei log.

Ambito delle metriche

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

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

Quando configurare gli ambiti delle metriche

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

  • Vuoi creare grafici dei dati archiviati in progetti diversi.
  • Vuoi che una criterio di avviso monitori i dati archiviati in progetti diversi.
  • Registra le applicazioni con App Hub. Per informazioni su questo scenario, consulta Applicazioni App Hub e ambiti delle metriche.

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 saperne di più, consulta Panoramica degli ambiti delle metriche.

Ambiti delle tracce

La pagina Esplora tracce utilizza gli ambiti di Trace. Quando si apre questa pagina, il sistema esegue automaticamente una query sulle visualizzazioni elencate nell'ambito di 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 una query sulla vista _AllSpans del progetto nel set di dati predefinito per i dati di traccia.

Un ambito della traccia elenca le visualizzazioni, non i progetti Google Cloud . Anche se selezioni i progetti quando configuri un ambito di traccia, il sistema aggiunge all'ambito la visualizzazione di traccia predefinita di questi progetti. La visualizzazione di Trace predefinita di un progetto corrisponde alla visualizzazione con il percorso _Trace/Spans/_AllSpans, dove i campi _Trace, Spans e _AllSpans fanno riferimento a un bucket, un set di dati e una visualizzazione di osservabilità. Il set di dati Spans archivia 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.

Best practice per la configurazione degli ambiti di traccia

Limiti associati agli ambiti di traccia

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

Per saperne di più, consulta Crea e gestisci gli ambiti di traccia.

Configura l'ambito di osservabilità

Questa sezione non si applica alle cartelle o alle organizzazioni.

Per i dati di log e tracce, i ruoli Identity and Access Management (IAM) nel progetto che stai visualizzando e in tutti i progetti e le visualizzazioni dei log cercati influiscono sui dati restituiti dalla query. Se esegui una query per visualizzare i dati di log che non hai l'autorizzazione di visualizzare, 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 suo 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

Configura il progetto, i ruoli IAM e seleziona l'interfaccia che prevedi di utilizzare.

Configura il progetto e i ruoli

  1. 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 role (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 Google Cloud project.

  3. Enable the Observability API, if it is not already enabled.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the API

  4. Per ottenere le autorizzazioni necessarie per creare e visualizzare gli scope, 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: Logs Configuration Writer (roles/logging.configWriter) sul progetto
    • Per modificare un ambito delle metriche: Monitoring Admin (roles/monitoring.admin) sul tuo progetto e su ogni progetto che vuoi aggiungere all'ambito 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 saperne di più 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 scope. Per vedere quali sono esattamente le autorizzazioni richieste, espandi la sezione Autorizzazioni obbligatorie:

    Autorizzazioni obbligatorie

    Per creare e visualizzare gli scope sono necessarie le seguenti autorizzazioni:

    • logging.logScopes.{create, delete, get, list, update}
    • monitoring.metricsscopes.{link, get, list}
    • observability.traceScopes.{create, delete, get, list, update}
    • observability.scopes.{get, update}

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

Seleziona l'interfaccia che intendi utilizzare

Console

Quando utilizzi la console Google Cloud per accedere ai servizi e alle API Google Cloud , non devi configurare l'autenticazione.

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 comando seguente: 

gcloud init

REST

Per utilizzare gli esempi di API REST in questa pagina in un ambiente di sviluppo locale, utilizzi 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 Autenticati per usare REST nella documentazione sull'autenticazione di Google Cloud .

Visualizza e imposta l'ambito predefinito

Console

Per configurare l'ambito di osservabilità, devi configurare i suoi 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 alle 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 o il progetto di gestione di App Hub.

  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 di log, fai clic su Crea ambito di log e completa la finestra di dialogo. Per saperne di più, consulta Crea e gestisci gli ambiti dei log.

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

  4. Configura l'ambito delle metriche:

    1. Seleziona la scheda Ambito delle metriche.
    2. Nel riquadro Progetti Google Cloud, fai clic su Aggiungi progetti cloud, quindi completa la finestra di dialogo. Per saperne di più, consulta Configura gli ambiti delle metriche.

  5. Configura l'ambito di traccia predefinito:

    1. Seleziona la scheda Ambiti di traccia e segui questi passaggi:

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

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

gcloud

Per visualizzare e aggiornare l'ambito di osservabilità, segui questi passaggi:

  1. Per visualizzare le impostazioni per l'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, il flag --trace-scope o entrambi i flag.

    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: il nome completo della risorsa 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 dei log. Ad esempio, my-scope.

    • TRACE_SCOPE_FQN_ID: il nome completo della risorsa dell'ambito di traccia. Questo campo ha il seguente formato: 
      projects/PROJECT_ID/locations/LOCATION/traceScopes/TRACE_SCOPE_NAME

      Nell'espressione precedente, TRACE_SCOPE_NAME è il nome dell'ambito di traccia. Ad esempio, my-trace-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\
   --trace-scope=TRACE_SCOPE_FQN_ID\
   --location=LOCATION\
   --project=PROJECT_ID

    Windows (PowerShell)

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

    Windows (cmd.exe)

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

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

    Updated scope [_Default].
logScope: logging.googleapis.com/projects/my-project/locations/global/logScopes/my-log-scope
traceScope: projects/my-project/locations/global/traceScopes/my-trace-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 di log predefinito e l'ambito di traccia predefinito.
  • Per aggiornare l'ambito di osservabilità predefinito di 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 di percorso per entrambi gli endpoint ha il seguente formato:

projects/PROJECT_ID/locations/LOCATION/scopes/OBSERVABILITY_SCOPE_ID

I campi dell'espressione precedente hanno il seguente significato:

  • PROJECT_ID: l'identificatore del progetto. Per le configurazioni di App Hub, seleziona il progetto host o il progetto di gestione di App Hub.
  • 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 le informazioni sull'ambito dei log predefinito e sullo scope delle tracce 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 name: 
        projects/PROJECT_ID/locations/global/scopes/_Default

    Prima di copiare il campo precedente, sostituisci PROJECT_ID con il nome del 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 ulteriori informazioni sugli ambiti, consulta i seguenti documenti: