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 saperne di più su come Google Cloud Observability archivia i dati, consulta la panoramica dell'archiviazione.

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

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

Prima di iniziare

  1. Accedi al tuo Google Cloud account. Se non hai mai utilizzato Google Cloud, crea un account per valutare il rendimento 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 Service Usage Admin (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 Service Usage Admin (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.

Puoi creare un link in un set di dati, che consente di eseguire query sui dati delle tracce da BigQuery. Puoi anche eliminare l'oggetto Link collegato a un set di dati.

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, 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 come eseguire query sulla telemetria, consulta Visualizzare e analizzare la telemetria.