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
- 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.
-
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 theresourcemanager.projects.createpermission. Learn how to grant roles.
-
Verify that billing is enabled for your Google Cloud project.
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 theserviceusage.services.enablepermission. Learn how to grant roles.-
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 theresourcemanager.projects.createpermission. Learn how to grant roles.
-
Verify that billing is enabled for your Google Cloud project.
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 theserviceusage.services.enablepermission. Learn how to grant roles.-
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.
-
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.
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.
-
Installa Google Cloud CLI.
-
Se utilizzi un provider di identità (IdP) esterno, devi prima accedere a gcloud CLI con la tua identità federata.
-
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:
-
Nella console Google Cloud , vai alla pagina settings Impostazioni:
Se utilizzi la barra di ricerca per trovare questa pagina, seleziona il risultato con il sottotitolo Monitoring.
- 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.
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.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,Spanse_AllSpanssi riferiscono al bucket, al set di dati e alla visualizzazione di osservabilità per i dati di traccia. La visualizzazione_AllSpanscorrisponde a ogni voce nel bucket:Nome Descrizione Tipo Risorse arrow_right _DefaultTrace scope1arrow_drop_down myscopeMy descriptionTrace scope2_Trace/Spans/_AllSpansmyprojectTrace view_Trace/Spans/_AllSpansproject-bTrace 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:
-
Nella console Google Cloud , vai alla pagina settings Impostazioni:
Se utilizzi la barra di ricerca per trovare questa pagina, seleziona il risultato con il sottotitolo Monitoring.
- 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.
- Seleziona la scheda Ambiti di traccia e poi fai clic su Crea ambito di traccia.
Fai clic su Aggiungi progetti e completa la finestra di dialogo.
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.
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,Spanse_AllSpanssi riferiscono al bucket, al set di dati e alla visualizzazione di osservabilità per i dati di traccia. La visualizzazione_AllSpanscorrisponde a ogni voce nel bucket:Nome Descrizione Tipo Risorse arrow_right _DefaultTrace scope1arrow_drop_down myscopeMy descriptionTrace scope2_Trace/Spans/_AllSpansmyprojectTrace view_Trace/Spans/_AllSpansproject-bTrace 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:
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 sugoogle-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".
Dopo aver aggiornato il file
main.tf, esegui l'upgrade dell'installazione di Terraform:terraform -init upgradeL'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:
-
Nella console Google Cloud , vai alla pagina settings Impostazioni:
Se utilizzi la barra di ricerca per trovare questa pagina, seleziona il risultato con il sottotitolo Monitoring.
- 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.
- Seleziona la scheda Ambiti di traccia.
Trova l'ambito della traccia che vuoi modificare o eliminare, fai clic su more_vert 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:
Utilizza la risorsa Terraform
google_observability_trace_scope.Dopo aver aggiornato il file
main.tf, esegui l'upgrade dell'installazione di Terraform:terraform -init upgradeL'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:
-
Nella console Google Cloud , vai alla pagina settings Impostazioni:
Se utilizzi la barra di ricerca per trovare questa pagina, seleziona il risultato con il sottotitolo Monitoring.
- 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.
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.Per modificare l'ambito di traccia predefinito, individua l'ambito di traccia che vuoi impostare come predefinito, fai clic su more_vert 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 oggettoScope, 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 oggettoScope. I parametri di ricerca identificano i campi modificati. La risposta è un oggettoScope.
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'oggettoScopecon 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:
- Fai clic su
projects.locations.scopes.get. Nel widget Prova questo metodo, inserisci quanto segue nel campo Nome:
projects/PROJECT_ID/locations/global/scopes/_DefaultPrima di copiare il campo precedente, sostituisci PROJECT_ID con il nome del tuo progetto.
Seleziona Esegui.
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
Cloud Logging e Cloud Monitoring contengono costrutti simili che consentono di controllare i dati di log o delle metriche che puoi visualizzare o monitorare. Per informazioni su questi ambiti, consulta i seguenti documenti: