Creare e gestire gli ambiti delle tracce

Questo documento descrive come creare e gestire un ambito della 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 intervalli. Per informazioni su questo argomento, vedi Trovare ed esplorare le tracce.

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

Informazioni sugli ambiti delle tracce

Gli ambiti Trace sono risorse permanenti a livello di progetto che elencano un insieme di progetti. Google Cloud Puoi configurare la pagina Esplora tracce per eseguire ricerche in base all'ambito della traccia, il che significa che la pagina esegue ricerche nei progetti elencati nell'ambito selezionato. I ruoli IAM (Identity and Access Management) nei progetti cercati e l'impostazione dell'intervallo di tempo determinano quali dati vengono recuperati dallo spazio di archiviazione e poi visualizzati.

Quando crei un progetto Google Cloud , viene creato un ambito della traccia denominato _Default. Questo ambito include solo il progetto Google Cloud . Non puoi aggiungere progetti a questo ambito o eliminarlo.

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 span in più progetti Google Cloud .

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 nei progettiGoogle Cloud elencati 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.

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 da elencare tutti i progetti che archiviano i tuoi 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 di traccia 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.

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.

    Go to project selector

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

  4. Enable the Observability API.

    Enable the API

  5. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

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

  7. Enable the Observability API.

    Enable the API

    8.

  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. 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, utilizzi le credenziali fornite 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 alla 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 .

    Elenca 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 della cartella app.

    3. Seleziona la scheda Ambiti di traccia.

      La tabella elenca gli ambiti di traccia. Quando selezioni un Google Cloud progetto, viene visualizzata una voce con un'icona "Predefinito", , che indica che si tratta dell'ambito della traccia predefinito. La pagina Esplora tracce cerca i dati di traccia nei progetti elencati nell'ambito della traccia predefinito quando la pagina si apre.

    gcloud

    Non supportati.

    REST

    Per elencare tutti gli ambiti di traccia in un progetto, utilizza il comando projects.locations.traceScopes.list. Google Cloud 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 della cartella app.
    • 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 dai progetti cercati, dai tuoi ruoli IAM in questi progetti, dall'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 progetti.

    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 della cartella app.
    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.

      Se non sai quali progetti includere in un ambito, puoi utilizzare la pagina Esplora tracce legacy per identificarli. Per ulteriori informazioni, consulta la sezione Eseguire la migrazione agli ambiti di traccia di questo documento.

    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.

    gcloud

    Non supportati.

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

    Esegui la migrazione agli ambiti delle tracce

    La pagina Esplora tracce richiede di specificare i progettiGoogle Cloud in cui cercare i dati di traccia, il che rappresenta un cambiamento nel comportamento rispetto alla pagina Esplora tracce precedente. La pagina Esplora tracce precedente esegue ricerche in tutti i progetti di un'organizzazione. A causa di queste differenze, la pagina Esplora tracce potrebbe non mostrare gli intervalli visualizzati nelle pagine Esplora tracce legacy.

    Puoi utilizzare la sezione del riquadro Dettagli traccia della pagina Esplora tracce legacy per compilare un elenco di progettiGoogle Cloud che archiviano i dati di traccia:

    1. Vai alla pagina Esplora tracce precedente:

      Vai a Esplora tracce (legacy)

    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. Seleziona una traccia.

      Puoi provare a:

      • Visualizzare una traccia inserendo il relativo ID nel campo ID traccia.
      • Aggiunta di filtri.

    4. Nel riquadro Dettagli su Trace, seleziona la traccia e poi vai alla scheda Progetti.

      Questa scheda elenca i progetti che archiviano gli span per la traccia.

    5. Per creare un ambito della traccia che contenga i progetti elencati, vai alla barra degli strumenti della scheda Progetti e seleziona Crea ambito con questi progetti, quindi completa la finestra di dialogo.

    6. Ripeti i passaggi precedenti finché non hai compilato un elenco di progetti.

    Dopo aver compilato un elenco di progetti, crea un ambito della traccia. Puoi anche impostarlo come ambito della traccia predefinito.

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

    4. Individua 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.

    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 della cartella app.
    • 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 della cartella app.
    • 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 nei progetti elencati nell'ambito della traccia predefinito. Se l'ambito della traccia non è accessibile, i dati di traccia vengono cercati nel tuo progetto.

    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 della cartella app.

    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.

    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"
}

    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 progetti per ambito della traccia 20

    Passaggi successivi