Creare e gestire ambiti delle tracce

Questo documento descrive come creare e gestire un ambito di traccia, che consente alla pagina Esplora tracce di trovare gli intervalli di traccia che vuoi visualizzare o analizzare. Se vuoi solo visualizzare e analizzare gli span che hanno origine nel tuo progetto Google Cloud , non devi configurare alcun ambito di traccia. Tuttavia, se i dati di traccia sono archiviati in più progetti, come potrebbe accadere quando utilizzi un'architettura di microservizi, devi eseguire alcune attività di configurazione per visualizzare tutti gli span di un singolo progetto Google Cloud .

Questo documento non descrive come visualizzare le tracce e gli span. Per informazioni su questo argomento, vedi Trovare ed esplorare le tracce.

Questa funzionalità è supportata solo per i Google Cloud progetti. Per le configurazioni di App Hub, seleziona il progetto host di App Hub o il progetto di gestione.

Informazioni sugli ambiti delle tracce

Gli ambiti Trace sono risorse persistenti a livello di progetto che elencano le visualizzazioni, che forniscono l'accesso ai dati di traccia. Puoi configurare la pagina Esplora tracce per eseguire ricerche per ambito della traccia, il che significa che la pagina cerca le viste elencate nell'ambito selezionato. I ruoli Identity and Access Management (IAM) nella visualizzazione cercata e l'impostazione dell'intervallo di tempo determinano quali dati vengono recuperati dal sistema dallo spazio di archiviazione e poi visualizzati.

Puoi creare ambiti di traccia, nonché modificare ed eliminare quelli che crei. Vuoi creare un ambito della traccia quando hai un servizio che scrive dati di intervallo in più progetti Google Cloud .

Un ambito della traccia elenca le visualizzazioni, non i progetti. Google Cloud Sebbene tu selezioni i progetti quando configuri un ambito di traccia, il sistema aggiunge all'ambito la visualizzazione di traccia predefinita di questi progetti. La visualizzazione predefinita delle tracce di un progetto corrisponde alla visualizzazione con il percorso _Trace/Spans/_AllSpans, dove i campi _Trace, Spans e _AllSpans si riferiscono a un bucket, un set di dati e una visualizzazione di osservabilità. Il set di dati Spans memorizza i dati di traccia.

A meno che tu non apra la pagina Esplora tracce con un URL che include un ambito della traccia o un ID traccia e span, la pagina Esplora tracce cerca i dati di traccia nelle viste elencate nell'ambito della traccia predefinito. Quando crei il progetto, l'ambito della traccia denominato _Default viene impostato come ambito della traccia predefinito. Tuttavia, puoi selezionare un ambito della traccia diverso da utilizzare come ambito della traccia predefinito.

Informazioni sull'ambito di osservabilità

L'ambito di osservabilità specifica quali ambiti di traccia e ambiti di log utilizzare quando vengono aperte le pagine di esplorazione corrispondenti. Se non configuri l'ambito di osservabilità in modo da elencare le risorse che archiviano i tuoi dati, potresti non essere in grado di correlare i dati di traccia e log. Per saperne di più, consulta Configurare gli ambiti di osservabilità per le query multiprogetto.

Applicazioni App Hub e ambiti di traccia

Le tue applicazioni App Hub potrebbero scrivere dati di traccia in più progetti. Per ottenere una visualizzazione aggregata di questi dati, crea un ambito della traccia, configuralo in modo che elenchi la visualizzazione della traccia predefinita di tutti i progetti che archiviano i dati di traccia e poi configuralo come ambito della traccia predefinito. Una volta completati questi passaggi, la pagina Explorer tracce mostra automaticamente i dati scritti dalla tua applicazione, anche se sono archiviati in progetti diversi.

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

Prima di iniziare

  1. Accedi al tuo account Google Cloud . Se non conosci Google Cloud, crea un account per valutare le prestazioni dei nostri prodotti in scenari reali. I nuovi clienti ricevono anche 300 $di crediti senza costi per l'esecuzione, il test e il deployment dei workload.
  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 role (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 role (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. Per ottenere le autorizzazioni necessarie per creare e visualizzare gli ambiti di traccia, chiedi all'amministratore di concederti il ruolo IAM Editor ambiti di osservabilità (roles/observability.scopesEditor) nel progetto. Per saperne di più 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. Seleziona la scheda relativa a come intendi utilizzare i campioni in questa pagina:

    Console

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

    gcloud

    Nella console Google Cloud , attiva Cloud Shell.

    Attiva Cloud Shell

    Nella parte inferiore della console Google Cloud viene avviata una sessione di Cloud Shell e viene visualizzato un prompt della riga di comando. Cloud Shell è un ambiente shell con Google Cloud CLI già installata e con valori già impostati per il progetto corrente. L'inizializzazione della sessione può richiedere alcuni secondi.

    Terraform

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

    1. Installa Google Cloud CLI.

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

    3. Se utilizzi una shell locale, crea credenziali di autenticazione locali per il tuo account utente:

      gcloud auth application-default login

      Non è necessario eseguire questa operazione se utilizzi Cloud Shell.

      Se viene restituito un errore di autenticazione e utilizzi un provider di identità (IdP) esterno, verifica di aver acceduto a gcloud CLI con la tua identità federata.

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

    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.

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

    Per saperne di più, consulta Autenticati per usare REST nella documentazione sull'autenticazione di Google Cloud .

Elenca gli ambiti della traccia

Console

Per elencare gli ambiti di traccia, segui questi passaggi:

  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.
  3. Seleziona la scheda Ambiti di traccia.

    La finestra mostra un elenco degli ambiti di traccia. La voce che include un'icona "Predefinito", , è l'ambito di traccia predefinito.

  4. Per visualizzare i dettagli di un ambito di traccia, espandilo.

    Se espandi un ambito della traccia, puoi visualizzare l'elenco delle visualizzazioni incluse nell'ambito. Ogni riga elenca un ID progetto insieme a una voce come _Trace/Spans/_AllSpans, che identifica la posizione di archiviazione predefinita per i dati di traccia. I campi _Trace, Spans e _AllSpans si riferiscono al bucket, al set di dati e alla visualizzazione di osservabilità per i dati di traccia. La visualizzazione _AllSpans corrisponde a ogni voce nel bucket:

    Nome Descrizione Tipo Risorse
    _Default Trace scope 1
    myscope My description Trace scope 2
      _Trace/Spans/_AllSpans myproject Trace view
      _Trace/Spans/_AllSpans project-b Trace view

gcloud

Non supportati.

Terraform

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

REST

Per elencare tutti gli ambiti di traccia in un progetto Google Cloud , utilizza il comando projects.locations.traceScopes.list. Devi specificare un parametro di percorso.

Il parametro di percorso per questo endpoint ha la seguente sintassi:

projects/PROJECT_ID/locations/LOCATION_ID/traceScopes

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.
  • LOCATION_ID deve essere impostato su global.

La risposta è un array di oggetti TraceScope. Ogni oggetto include un nome e un elenco di risorse.

Per ottenere informazioni su un ambito di traccia specifico, utilizza il comando projects.locations.traceScopes.get.

Creare un ambito della traccia

Gli intervalli visualizzati dalla pagina Esplora tracce dipendono dalle viste cercate, dai tuoi ruoli IAM in queste viste, dall'impostazione dell'intervallo di tempo e dai filtri che applichi.

Puoi creare 100 ambiti della traccia per progetto. Un ambito della traccia può includere un totale di 20 viste.

Console

Per creare un ambito di traccia:

  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.
  3. Seleziona la scheda Ambiti di traccia e poi fai clic su Crea ambito di traccia.
  4. Fai clic su Aggiungi progetti e completa la finestra di dialogo.

  5. Nella sezione Ambito della traccia del nome, inserisci il nome e la descrizione che vuoi visualizzare nella scheda Ambiti della traccia.

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

  6. Fai clic su Crea ambito di traccia.

    Per impostazione predefinita, la tabella Ambiti di traccia elenca gli ambiti di traccia in forma compressa. Per ogni ambito, la tabella elenca un nome, una descrizione, un tipo e un numero di risorse.

    Se espandi un ambito della traccia, puoi visualizzare l'elenco delle visualizzazioni incluse nell'ambito. Ogni riga elenca un ID progetto insieme a una voce come _Trace/Spans/_AllSpans, che identifica la posizione di archiviazione predefinita per i dati di traccia. I campi _Trace, Spans e _AllSpans si riferiscono al bucket, al set di dati e alla visualizzazione di osservabilità per i dati di traccia. La visualizzazione _AllSpans corrisponde a ogni voce nel bucket:

    Nome Descrizione Tipo Risorse
    _Default Trace scope 1
    myscope My description Trace scope 2
      _Trace/Spans/_AllSpans myproject Trace view
      _Trace/Spans/_AllSpans project-b Trace view

gcloud

Non supportati.

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 di traccia in un progetto utilizzando Terraform:

  1. Utilizza la risorsa Terraform google_observability_trace_scope.

    Nel comando, imposta i seguenti campi:

    • project: il nome del progetto, della cartella o dell'organizzazione. Ad esempio, my-project. Per le configurazioni di App Hub, seleziona il progetto host di App Hub o il progetto di gestione.

    • provider: impostato su google-beta.

    • trace_scope_id: impostato su un ID ambito. Ad esempio, my-trace-scope.

    • location: impostato su "global".

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

    • description: una breve descrizione. Ad esempio, "Scope for production resources".

  2. Dopo aver aggiornato il file main.tf, esegui l'upgrade dell'installazione di Terraform:

    terraform -init upgrade
    

    L'upgrade è necessario perché la risorsa google_observability_trace_scope è in versione beta.

REST

Per creare un ambito di traccia, utilizza il comando projects.locations.traceScopes.create. Devi specificare un parametro di percorso e fornire un oggetto TraceScope. La risposta è un oggetto TraceScope.

Il parametro di percorso per questo endpoint ha la seguente sintassi:

projects/PROJECT_ID/locations/LOCATION_ID/traceScopes

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.
  • LOCATION_ID deve essere impostato su global.

Modificare o eliminare un ambito di traccia

Non puoi eliminare o modificare l'ambito della traccia denominato _Default. Puoi modificare o eliminare tutti gli altri ambiti di traccia.

Console

Per modificare o eliminare un ambito di traccia:

  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.
  3. Seleziona la scheda Ambiti di traccia.
  4. Trova l'ambito della traccia 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

Non supportati.

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 di traccia in un progetto utilizzando Terraform:

  1. Utilizza la risorsa Terraform google_observability_trace_scope.

  2. Dopo aver aggiornato il file main.tf, esegui l'upgrade dell'installazione di Terraform:

    terraform -init upgrade
    

    L'upgrade è necessario perché la risorsa google_observability_trace_scope è in versione beta.

REST

Modificare un ambito

Per modificare un ambito di traccia, utilizza il comando projects.locations.traceScopes.patch. Devi specificare un parametro di percorso, parametri di ricerca e fornire un oggetto TraceScope. I parametri di ricerca identificano i campi modificati. La risposta è un oggetto TraceScope.

Il parametro di percorso per questo endpoint ha la seguente sintassi:

projects/PROJECT_ID/locations/LOCATION_ID/traceScopes/TRACE_SCOPE_NAME

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.
  • LOCATION_ID deve essere impostato su global.
  • TRACE_SCOPE_NAME: il nome di un ambito di traccia. Ad esempio, my-trace-scope.

Eliminare un ambito

Per eliminare un ambito di traccia, utilizza il comando projects.locations.traceScopes.delete. Devi specificare un parametro di percorso.

Il parametro di percorso per questo endpoint ha la seguente sintassi:

projects/PROJECT_ID/locations/LOCATION_ID/traceScopes/TRACE_SCOPE_NAME

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.
  • LOCATION_ID deve essere impostato su global.
  • TRACE_SCOPE_NAME: il nome di un ambito di traccia. Ad esempio, my-trace-scope.

Configurare l'ambito della traccia predefinito

Quando si apre la pagina Esplora tracce, vengono cercati i dati di traccia nelle viste elencate nell'ambito della traccia predefinito. Se l'ambito della traccia non è accessibile, la pagina Esplora tracce esegue query sulla visualizzazione _AllSpans del progetto nel set di dati predefinito.

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

Console

Per impostare l'ambito della traccia 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.
  3. Seleziona la scheda Ambiti di traccia.

    La scheda mostra gli ambiti di traccia e include un pulsante per creare un ambito di traccia personalizzato. L'ambito della traccia mostrato con un'icona "Predefinito", , è l'ambito della traccia predefinito corrente.

  4. Per modificare l'ambito di traccia predefinito, individua l'ambito di traccia che vuoi impostare come predefinito, fai clic su  Altro e poi seleziona Imposta come predefinito.

    L'ambito della traccia selezionato viene mostrato con un'icona "Predefinito",.

gcloud

Non supportati.

Terraform

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

REST

Per ottenere e impostare l'ambito di log predefinito o l'ambito di traccia 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 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.
  • 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"
    }
    

Limiti relativi agli ambiti delle tracce

Limiti relativi agli ambiti delle tracce Valore
Numero massimo di ambiti della traccia per progetto 100
Numero massimo di visualizzazioni per ambito di traccia 20

Passaggi successivi