Gestisci l'archiviazione delle tracce

Questo documento descrive come utilizzare l'API Observability per ottenere informazioni sul bucket di osservabilità 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 Google Cloud account. 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. Installa Google Cloud CLI.

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

  4. Per inizializzare gcloud CLI, esegui questo comando: 

    gcloud init

  5. Crea o seleziona un Google Cloud progetto.

    Ruoli richiesti per selezionare o creare un progetto

    • Seleziona un progetto: la selezione di un progetto non richiede un ruolo IAM specifico. Puoi selezionare qualsiasi progetto su cui ti è stato concesso un ruolo.
    • Crea un progetto: per creare un progetto, devi disporre del ruolo Autore progetto (roles/resourcemanager.projectCreator), che contiene l' resourcemanager.projects.create autorizzazione. Scopri come concedere i ruoli.

    • Crea un Google Cloud progetto:

      gcloud projects create PROJECT_ID

      Sostituisci PROJECT_ID con un nome per il Google Cloud progetto che stai creando.

    • Seleziona il Google Cloud progetto che hai creato:

      gcloud config set project PROJECT_ID

      Sostituisci PROJECT_ID con il nome del Google Cloud progetto.

  6. Verifica che la fatturazione sia abilitata per il tuo Google Cloud progetto.

  7. Abilita l'API Observability:

    Ruoli richiesti per abilitare le API

    Per abilitare le API, devi disporre del ruolo IAM Amministratore utilizzo servizi (roles/serviceusage.serviceUsageAdmin), che contiene l' serviceusage.services.enable autorizzazione. Scopri come concedere i ruoli. 

    gcloud services enable observability.googleapis.com

  8. Concedi i ruoli al tuo account utente. Esegui il seguente comando una volta per ciascuno dei seguenti ruoli IAM: roles/observability.viewer 

    gcloud projects add-iam-policy-binding PROJECT_ID --member="user:USER_IDENTIFIER" --role=ROLE

    Sostituisci quanto segue:

    • PROJECT_ID: il tuo ID progetto.
    • USER_IDENTIFIER: l'identificatore del tuo account utente. Ad esempio, myemail@example.com.
    • ROLE: il ruolo IAM che concedi al tuo account utente.

  9. Installa Google Cloud CLI.

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

  11. Per inizializzare gcloud CLI, esegui questo comando: 

    gcloud init

  12. Crea o seleziona un Google Cloud progetto.

    Ruoli richiesti per selezionare o creare un progetto

    • Seleziona un progetto: la selezione di un progetto non richiede un ruolo IAM specifico. Puoi selezionare qualsiasi progetto su cui ti è stato concesso un ruolo.
    • Crea un progetto: per creare un progetto, devi disporre del ruolo Autore progetto (roles/resourcemanager.projectCreator), che contiene l' resourcemanager.projects.create autorizzazione. Scopri come concedere i ruoli.

    • Crea un Google Cloud progetto:

      gcloud projects create PROJECT_ID

      Sostituisci PROJECT_ID con un nome per il Google Cloud progetto che stai creando.

    • Seleziona il Google Cloud progetto che hai creato:

      gcloud config set project PROJECT_ID

      Sostituisci PROJECT_ID con il nome del Google Cloud progetto.

  13. Verifica che la fatturazione sia abilitata per il tuo Google Cloud progetto.

  14. Abilita l'API Observability:

    Ruoli richiesti per abilitare le API

    Per abilitare le API, devi disporre del ruolo IAM Amministratore utilizzo servizi (roles/serviceusage.serviceUsageAdmin), che contiene l' serviceusage.services.enable autorizzazione. Scopri come concedere i ruoli. 

    gcloud services enable observability.googleapis.com

  15. Concedi i ruoli al tuo account utente. Esegui il seguente comando una volta per ciascuno dei seguenti ruoli IAM: roles/observability.viewer 

    gcloud projects add-iam-policy-binding PROJECT_ID --member="user:USER_IDENTIFIER" --role=ROLE

    Sostituisci quanto segue:

    • PROJECT_ID: il tuo ID progetto.
    • USER_IDENTIFIER: l'identificatore del tuo account utente. Ad esempio, myemail@example.com.
    • ROLE: il ruolo IAM che concedi al tuo account utente.
    16.

Elenca i bucket di osservabilità

REST

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

Devi specificare il parametro parent, 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 località del bucket di osservabilità. Se imposti LOCATION su un trattino, (-), vengono elencati tutti i bucket di osservabilità nel tuo progetto.

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

projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID

Ad esempio, quando è stato emesso 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 emettere 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, nonché le visualizzazioni e i link in ogni set di dati. Per un elenco completo degli endpoint dell'API Observability, consulta la documentazione di riferimento dell'API Observability.

Elenca i set di dati in un bucket di osservabilità

REST

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

Devi specificare il parametro parent, 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 Dataset oggetti. 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 emettere 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 in ogni set di dati. Per un elenco completo degli endpoint dell'API Observability, consulta la documentazione di riferimento dell'API Observability.

Elenca le visualizzazioni in un set di dati

REST

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

Devi specificare il parametro parent, 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 località 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 View oggetti. 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 visualizzazione è rappresentato da OBS_VIEW_ID. Ad esempio, questo campo potrebbe avere un valore di _AllSpans.

Ad esempio, quando è stato emesso 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 dell'API Observability, consulta la documentazione di riferimento dell'API Observability.

REST

Per elencare i link in un set di dati, invia una richiesta all' projects.locations.buckets.datasets.links.list endpoint.

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

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

I campi nell'espressione precedente hanno i seguenti significati:

  • PROJECT_ID: l'identificatore del progetto.
  • LOCATION: la località 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 Link oggetti. Per ogni oggetto, il valore del campo name ha il seguente formato:

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

LINK_ID è il nome del set di dati BigQuery. Questo campo è univoco a livello globale per il tuo Google Cloud progetto.

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

{
  "links": [
    {
      "name": "projects/my-project/locations/us/buckets/_Trace/datasets/Spans/links/my_link",
      "description": "My link for traces to BigQuery",
      "createTime": "2025-01-12T15:42:30.988919645Z"
    }
  ]
}

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

Questa sezione descrive come creare un link in un set di dati, che consente di eseguire query sui dati di traccia da BigQuery.

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

REST

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

Devi specificare il parametro parent, 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 località 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 di 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 Google Cloud progetto, e deve essere limitato a 100 caratteri e può includere solo lettere, cifre e trattini bassi.

  • Il corpo della richiesta è un Link oggetto. 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 fornito per il campo name deve corrispondere al set di dati BigQuery collegato a cui fa riferimento il parametro di query.

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

La risposta è un Operation oggetto. 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 dell'API Observability, consulta la documentazione di riferimento dell'API Observability.

Passaggi successivi

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

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