Gestisci l'archiviazione delle tracce

Questo documento descrive come utilizzare l'API Observability per ottenere informazioni sul bucket Observability che archivia i dati di traccia. Include informazioni su come elencare set di dati, link e visualizzazioni. Per scoprire di più su come vengono archiviati i dati di traccia, consulta la panoramica dell'archiviazione delle tracce.

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.

  8. Per ottenere le autorizzazioni necessarie per elencare bucket, link e visualizzazioni, chiedi all'amministratore di concederti il ruolo IAM Visualizzatore osservabilità (roles/observability.viewer) 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.

  9. Seleziona la scheda relativa a come intendi utilizzare i campioni in questa pagina:

    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.

    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 i bucket di osservabilità

gcloud

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

  • LOCATION: la posizione dei bucket di osservabilità. Per elencare tutti i bucket osservabilità, indipendentemente dalla posizione, imposta la posizione su un trattino (-).
  • PROJECT_ID: l'identificatore del progetto.

Esegui il comando gcloud beta observability buckets list:

Linux, macOS o Cloud Shell

gcloud beta observability buckets list \
 --location=LOCATION --project=PROJECT_ID

Windows (PowerShell)

gcloud beta observability buckets list `
 --location=LOCATION --project=PROJECT_ID

Windows (cmd.exe)

gcloud beta observability buckets list ^
 --location=LOCATION --project=PROJECT_ID

La risposta elenca il nome, la descrizione e l'ora di creazione di ogni bucket di osservabilità. Di seguito è riportato un esempio di risposta quando il comando ha esito positivo: 

---
createTime: '2026-01-21T21:39:22.381083860Z'
description: Bucket for storing spans from Cloud Trace.
name: projects/my-project/locations/us/buckets/_Trace

REST

Per elencare i bucket di osservabilità presenti nel tuo progetto e in una località specifica, invia una richiesta all'endpoint projects.locations.buckets.list.

Devi specificare il parametro padre, che ha il seguente formato:

projects/PROJECT_ID/locations/LOCATION

I campi nell'espressione precedente hanno i seguenti significati:

  • PROJECT_ID: l'identificatore del progetto.
  • LOCATION: la posizione del bucket di osservabilità. Se imposti LOCATION su un trattino, (-), vengono elencati tutti i bucket osservabilità nel tuo progetto.

La risposta è un array di oggetti Bucket. Per ogni oggetto, il valore del campo name ha il seguente formato:

projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID

Ad esempio, quando è stato inviato un comando all'endpoint buckets.list con il parametro parent impostato su projects/my-project/locations/us, la risposta è stata:

{
  "buckets": [
    {
      "name": "projects/my-project/locations/us/buckets/_Trace",
      "description": "Trace Bucket",
      "createTime": "2025-01-01T15:42:30.988919645Z",
      "updateTime": "2025-02-04T15:42:30.988919645Z",
      "retentionDays": 30
    }
  ]
}

Puoi inviare comandi ad altri endpoint dell'API Observability per ottenere ulteriori informazioni sul bucket il cui ID è BUCKET_ID. Ad esempio, puoi elencare i set di dati nel bucket e le visualizzazioni e i link di ogni set di dati. Per un elenco completo degli endpoint API Observability, consulta la documentazione di riferimento dell'API Observability.

Elenca i set di dati in un bucket osservabilità

gcloud

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

  • BUCKET_ID: l'ID del bucket di osservabilità. Ad esempio, questo ID potrebbe essere _Trace.
  • LOCATION: la posizione dei bucket di osservabilità.
  • PROJECT_ID: l'identificatore del progetto.

Esegui il comando gcloud beta observability buckets datasets list:

Linux, macOS o Cloud Shell

gcloud beta observability buckets datasets list \
 --bucket=projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID \
 --location=LOCATION \
 --project=PROJECT_ID

Windows (PowerShell)

gcloud beta observability buckets datasets list `
 --bucket=projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID `
 --location=LOCATION `
 --project=PROJECT_ID

Windows (cmd.exe)

gcloud beta observability buckets datasets list ^
 --bucket=projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID ^
 --location=LOCATION ^
 --project=PROJECT_ID

La risposta elenca il nome, la descrizione e l'ora di creazione di ogni set di dati. Di seguito è riportato un esempio di risposta quando il comando ha esito positivo: 

---
createTime: '2026-01-21T21:39:22.381083860Z'
description: Dataset for storing spans from Cloud Trace.
name: projects/my-project/locations/us/buckets/_Trace/datasets/Spans

REST

Per elencare i set di dati per un bucket di osservabilità, invia una richiesta all'endpoint projects.locations.buckets.datasets.list.

Devi specificare il parametro padre, che ha il seguente formato:

projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID

I campi nell'espressione precedente hanno i seguenti significati:

La risposta è un array di oggetti Dataset. Per ogni oggetto, il valore del campo name ha il seguente formato:

projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID/dataset/DATASET_ID

Ad esempio, quando è stato emesso un comando all'endpoint buckets.datasets.list con il parametro parent impostato su projects/my-project/locations/us/buckets/_Trace, la risposta è stata:

{
  "datasets": [
    {
      "name": "projects/my-project/locations/us/buckets/_Trace/datasets/Spans",
      "description": "Trace Spans",
      "createTime": "2025-01-01T15:42:30.988919645Z",
      "updateTime": "2025-02-04T15:42:30.988919645Z",
    }
  ]
}

Puoi inviare comandi ad altri endpoint dell'API Observability per ottenere informazioni sul set di dati il cui ID è DATASET_ID. Ad esempio, puoi elencare le visualizzazioni e i link di ogni set di dati. Per un elenco completo degli endpoint API Observability, consulta la documentazione di riferimento dell'API Observability.

Elenca le visualizzazioni di un set di dati

gcloud

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

  • DATASET_ID: l'ID del set di dati. I dati di traccia vengono archiviati in un set di dati denominato Spans.
  • BUCKET_ID: l'ID del bucket di osservabilità. Ad esempio, questo ID potrebbe essere _Trace.
  • LOCATION: la posizione dei bucket di osservabilità.
  • PROJECT_ID: l'identificatore del progetto.

Esegui il comando gcloud beta observability buckets datasets views list:

Linux, macOS o Cloud Shell

gcloud beta observability buckets datasets views list \
 --dataset=projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID/datasets/DATASET_ID \
 --bucket=BUCKET_ID \
 --location=LOCATION \
 --project=PROJECT_ID

Windows (PowerShell)

gcloud beta observability buckets datasets views list `
 --dataset=projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID/datasets/DATASET_ID `
 --bucket=BUCKET_ID `
 --location=LOCATION `
 --project=PROJECT_ID

Windows (cmd.exe)

gcloud beta observability buckets datasets views list ^
 --dataset=projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID/datasets/DATASET_ID ^
 --bucket=BUCKET_ID ^
 --location=LOCATION ^
 --project=PROJECT_ID

La risposta elenca il nome, l'ora di creazione e l'ora di aggiornamento di ogni visualizzazione di osservabilità. Di seguito è riportato un esempio di risposta quando il comando ha esito positivo: 

---
createTime: '2026-01-21T21:39:22.381083860Z'
displayName: _AllSpans
name: projects/pamstestproject1/locations/us/buckets/_Trace/datasets/Spans/views/_AllSpans
updateTime: '2026-01-21T21:39:22.381083860Z'

REST

Per elencare le visualizzazioni di un set di dati, invia una richiesta all'endpoint projects.locations.buckets.datasets.views.list.

Devi specificare il parametro padre, che ha il seguente formato:

projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID/datasets/DATASET_ID/views

I campi nell'espressione precedente hanno i seguenti significati:

  • PROJECT_ID: l'identificatore del progetto.
  • LOCATION: la posizione del bucket di osservabilità.
  • BUCKET_ID: l'ID del bucket di osservabilità. Ad esempio, questo ID potrebbe essere _Trace.
  • DATASET_ID: l'ID del set di dati su cui viene eseguita la query. Ad esempio, questo ID potrebbe essere Spans.

La risposta è un array di oggetti View. Per ogni oggetto, il valore del campo name ha il seguente formato:

projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID/views/OBS_VIEW_ID

Nell'espressione precedente, l'ID di una vista è rappresentato da OBS_VIEW_ID. Ad esempio, questo campo potrebbe avere un valore pari a _AllSpans.

Ad esempio, quando è stato inviato un comando all'endpoint buckets.datasets.views.list con il parametro parent impostato su projects/my-project/locations/us/buckets/_Trace/datasets/Spans/views, la risposta è stata:

{
  "views": [
    {
      "name": "projects/my-project/locations/us/buckets/_Trace/datasets/Spans/views/_AllSpans",
      "filter": "",
      "createTime": "2025-01-01T15:42:30.988919645Z",
      "updateTime": "2025-02-04T15:42:30.988919645Z",
    }
  ]
}

Per un elenco completo degli endpoint API Observability, consulta la documentazione di riferimento dell'API Observability.

Questa sezione descrive come creare un collegamento a un set di dati, che consente di eseguire query sui dati di tracciamento da BigQuery.

  1. Completa la configurazione richiesta per elencare i link.

  2. Per ottenere le autorizzazioni necessarie per creare un link a un set di dati, chiedi all'amministratore di concederti i seguenti ruoli IAM 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.

Crea un set di dati BigQuery collegato

gcloud

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

  • LINK_ID: il nome del set di dati BigQuery.
  • DATASET_ID: l'ID del set di dati. I dati di traccia vengono archiviati in un set di dati denominato Spans.
  • BUCKET_ID: l'ID del bucket di osservabilità. Ad esempio, questo ID potrebbe essere _Trace.
  • LOCATION: la posizione dei bucket di osservabilità.
  • PROJECT_ID: l'identificatore del progetto.

Esegui il comando gcloud beta observability buckets datasets links create:

Linux, macOS o Cloud Shell

gcloud beta observability buckets datasets links create \
  projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID/datasets/DATASET_ID/links/LINK_ID \
 --dataset=DATASET_ID\
 --bucket=BUCKET_ID \
 --location=LOCATION \
 --project=PROJECT_ID

Windows (PowerShell)

gcloud beta observability buckets datasets links create `
  projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID/datasets/DATASET_ID/links/LINK_ID `
 --dataset=DATASET_ID`
 --bucket=BUCKET_ID `
 --location=LOCATION `
 --project=PROJECT_ID

Windows (cmd.exe)

gcloud beta observability buckets datasets links create ^
  projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID/datasets/DATASET_ID/links/LINK_ID ^
 --dataset=DATASET_ID^
 --bucket=BUCKET_ID ^
 --location=LOCATION ^
 --project=PROJECT_ID

Il comando create avvia un'operazione a lunga esecuzione. Di seguito è riportato un esempio di risposta quando il comando ha esito positivo: 

Create request issued for: [mydataset]
Waiting for operation [projects/my-project/locations/us/operations/operation-1775164903749-64e80c9817833-9ff804b6-c3e9cbe7] to complete...done.
Created link [mydataset].

REST

Per creare un link a un set di dati BigQuery, invia una richiesta all'endpoint projects.locations.buckets.datasets.links.create.

Devi specificare il parametro padre, che ha il seguente formato:

projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID/datasets/DATASET_ID

I campi nell'espressione precedente hanno il seguente significato:

  • PROJECT_ID: l'identificatore del progetto.
  • LOCATION: la posizione del bucket di osservabilità.
  • BUCKET_ID: l'ID del bucket di osservabilità. Ad esempio, questo ID potrebbe essere _Trace.
  • DATASET_ID: l'ID del set di dati su cui viene eseguita la query. Ad esempio, questo ID potrebbe essere Spans.

Questo comando richiede un parametro di query e un corpo della richiesta:

  • Il parametro della query, linkId, deve essere specificato e impostato sul nome del set di dati BigQuery. Ad esempio, linkId="my_link". Il nome del set di dati BigQuery deve essere univoco per il tuo progetto Google Cloud e deve essere limitato a 100 caratteri e può includere solo lettere, cifre e trattini bassi.

  • Il corpo della richiesta è un oggetto Link. Il valore del campo name ha il seguente formato:

    projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID/dataset/DATASET_ID/links/LINK_ID

    Il valore che fornisci per il campo name deve corrispondere al set di dati BigQuery collegato a cui fa riferimento il parametro della query.

    Il campo LINK_ID è il nome del set di dati BigQuery.

La risposta è un oggetto Operation. Questo oggetto contiene informazioni sullo stato di avanzamento del metodo. Al termine del metodo, l'oggetto Operation contiene i dati di stato.

Per un elenco completo degli endpoint API Observability, consulta la documentazione di riferimento dell'API Observability.

Passaggi successivi

Per scoprire di più sull'utilizzo della pagina Esplora tracce, vedi Trovare ed esplorare le tracce.

Per scoprire come analizzare gli intervalli di traccia con SQL, consulta Eseguire query e analizzare le tracce.