Gestire i bucket di osservabilità

Questo documento descrive come utilizzare l'API Observability per ottenere informazioni sui bucket di osservabilità. Include anche informazioni su come elencare set di dati, link e visualizzazioni. Per scoprire di più su come Google Cloud Observability archivia i dati, consulta la Panoramica dell'archiviazione.

I dati di traccia vengono archiviati nei bucket osservabilità. Questo documento descrive come gestire l'archiviazione dei dati di traccia, ma non descrive il formato dei dati archiviati. Per informazioni su questo argomento, vedi Schema di traccia.

Questo documento non si applica all'archiviazione dei dati di log o delle metriche. I dati di log e metriche non vengono archiviati nei bucket di osservabilità.

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. 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 per il quale ti è stato concesso un ruolo.
    • Crea un progetto: per creare un progetto, devi disporre del ruolo Autore progetto (roles/resourcemanager.projectCreator), che contiene l'autorizzazione resourcemanager.projects.create. Scopri come concedere i ruoli.

    • Creare un progetto Google Cloud :

      gcloud projects create PROJECT_ID

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

    • Seleziona il progetto Google Cloud che hai creato:

      gcloud config set project PROJECT_ID

      Sostituisci PROJECT_ID con il nome del progetto Google Cloud .

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

  7. Abilita l'API Observability:

    Ruoli richiesti per abilitare le API

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

    gcloud services enable observability.googleapis.com

  8. Concedi 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 per il quale ti è stato concesso un ruolo.
    • Crea un progetto: per creare un progetto, devi disporre del ruolo Autore progetto (roles/resourcemanager.projectCreator), che contiene l'autorizzazione resourcemanager.projects.create. Scopri come concedere i ruoli.

    • Creare un progetto Google Cloud :

      gcloud projects create PROJECT_ID

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

    • Seleziona il progetto Google Cloud che hai creato:

      gcloud config set project PROJECT_ID

      Sostituisci PROJECT_ID con il nome del progetto Google Cloud .

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

  14. Abilita l'API Observability:

    Ruoli richiesti per abilitare le API

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

    gcloud services enable observability.googleapis.com

  15. Concedi 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'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 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 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à

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

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 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 API Observability, consulta la documentazione di riferimento dell'API Observability.

REST

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

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 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 Link. 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 progetto Google Cloud .

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 API Observability, consulta la documentazione di riferimento dell'API Observability.

Puoi creare un collegamento a un set di dati, che consente di eseguire query sui dati di traccia da BigQuery. Puoi anche eliminare l'oggetto Link collegato a un set di dati.

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

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 informazioni sull'esecuzione di query sulla telemetria, vedi Visualizzare e analizzare la telemetria.