Crea bucket di osservabilità

Puoi creare manualmente il bucket di osservabilità _Trace prima che il tuo progetto riceva dati di traccia per personalizzare la posizione di archiviazione e le impostazioni della chiave di crittografia gestita dal cliente (CMEK). Se il tuo Google Cloud progetto inserisce i dati di traccia prima che esista questo bucket, Google Cloud Observability esegue automaticamente il provisioning del bucket utilizzando le impostazioni predefinite per i bucket di osservabilità del tuo progetto.

Per informazioni su come Google Cloud Observability archivia i dati, consulta la panoramica dell'archiviazione.

Interazione con le norme dell'organizzazione

Una richiesta di creazione di un bucket di osservabilità verifica che i parametri del comando siano conformi alle norme dell'organizzazione. Ad esempio, se un criterio dell'organizzazione limita le località delle risorse, la creazione di un bucket non va a buon fine se specifichi una località limitata.

Interazione con le impostazioni predefinite per i bucket di osservabilità

Quando Google Cloud Observability crea automaticamente un bucket di osservabilità a causa dell'importazione dei dati, utilizza le impostazioni predefinite per i bucket di osservabilità che si applicano alla risorsa padre del bucket. Queste impostazioni predefinite potrebbero essere definite nell'elemento principale o in un elemento gerarchico predecessore dell'elemento principale e specificano quanto segue:

• La posizione di archiviazione.
• La chiave Cloud KMS da utilizzare per i dati archiviati.

Quando crei un bucket di osservabilità, devi specificare una località. Google Cloud Observability applica la chiave Cloud KMS definita nelle impostazioni predefinite, a meno che tu non ne specifichi esplicitamente una diversa nella richiesta di creazione.

Non puoi creare un bucket con la crittografia predefinita di Google se le impostazioni predefinite applicabili specificano una chiave Cloud KMS. Per utilizzare la crittografia predefinita di Google, assicurati che non sia configurata alcuna chiave Cloud KMS nelle impostazioni predefinite.

Per informazioni sulle impostazioni predefinite per i bucket di osservabilità, vedi Imposta i valori predefiniti per i bucket di osservabilità.

Limitazioni

Si applicano le seguenti limitazioni:

• Devi specificare una località supportata.
• BUCKET_ID deve essere _Trace.
• Il nome visualizzato non deve superare i 100 byte codificati.
• La descrizione non deve superare i 1000 byte codificati.
• I dati vengono archiviati per 30 giorni. Devi omettere il periodo di conservazione o impostarlo su 30.
• Se fornisci una chiave Cloud KMS, la posizione della chiave deve corrispondere esattamente alla posizione principale del bucket di osservabilità.
• Puoi creare bucket di osservabilità solo nei progetti Google Cloud .
• Un progetto Google Cloud può avere al massimo un bucket di osservabilità denominato _Trace.

Prima di iniziare

Configura il progetto e i ruoli IAM e seleziona l'interfaccia che prevedi di utilizzare.

Configura il progetto e i ruoli

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 carichi di lavoro.

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.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

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 serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

Enable the API

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.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

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 serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

Enable the API

1. Per ottenere le autorizzazioni necessarie per creare bucket di osservabilità, chiedi all'amministratore di concederti il ruolo IAM Editor osservabilità (roles/observability.editor) 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.

Configura interfacce

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.

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.

1. Installa Google Cloud CLI.

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

3. Se utilizzi una shell locale, crea le 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 .

Configura la chiave Cloud KMS

Facoltativo. Se prevedi di creare un bucket di osservabilità e di specificare una chiave Cloud KMS, segui questi passaggi:

1. Abilita l'API Cloud Key Management Service.

   Ruoli richiesti per abilitare le API

   Per abilitare le API, devi disporre dell'autorizzazione serviceusage.services.enable. Se hai creato il progetto, probabilmente disponi già di questa autorizzazione tramite il ruolo Proprietario (roles/owner). In caso contrario, puoi ottenere questa autorizzazione tramite il ruolo Amministratore utilizzo dei servizi (roles/serviceusage.serviceUsageAdmin). Scopri come concedere i ruoli.

   Abilitare l'API

2. Crea un keyring e le chiavi.

   La località del bucket di osservabilità deve corrispondere a quella della chiave.

3. Sostituisci PROJECT_ID con l'ID del tuo progetto, quindi esegui il comando seguente:

   gcloud beta observability settings describe \
   --location=global --project=PROJECT_ID
   

   Il comando precedente verifica se hai configurato una posizione di archiviazione predefinita. Crea anche il account di servizio Google Cloud Observability quando non esiste. La risposta del comando elenca l'ID delaccount di serviziot.

4. Concedi il ruolo Cloud KMS CryptoKey Encrypter/Decrypter al account di servizio Google Cloud Observability.

   gcloud kms keys add-iam-policy-binding \
   --project=KMS_PROJECT_ID \
   --member=serviceAccount:[e-mail] \
   --role=roles/cloudkms.cryptoKeyEncrypterDecrypter \
   --location=KMS_KEY_LOCATION \
   --keyring=KMS_KEY_RING \
   KMS_KEY_NAME
   

   Prima di eseguire il comando precedente, effettua le seguenti sostituzioni:

   • KMS_PROJECT_ID: l'identificatore alfanumerico univoco, composto dal nome del tuo progetto Google Cloud e da un numero assegnato in modo casuale, del progetto Google Cloud che esegue Cloud KMS. Per informazioni su come ottenere questo identificatore, consulta Identificazione dei progetti.
   • service-PROJECT_NUMBER: il nome del service account di Observability elencato nella risposta del passaggio precedente.
   • KMS_KEY_LOCATION: la regione della chiave Cloud KMS.
   • KMS_KEY_RING: il nome delle chiavi automatizzate Cloud KMS.
   • KMS_KEY_NAME: Il nome della chiave Cloud KMS. È formattato nel seguente modo: projects/KMS_PROJECT_ID/locations/LOCATION/keyRings/KMS_KEY_RING/cryptoKeys/KEY.

Crea un bucket di osservabilità

gcloud

Non supportati.

Terraform

Per creare un bucket di osservabilità, utilizza la risorsa Terraform google_observability_bucket e imposta i seguenti campi:

• project: l'ID del progetto.
• location: la posizione del bucket di osservabilità. Per saperne di più, vedi Località.
• bucket_id: l'ID del bucket di osservabilità. Questo campo deve essere impostato su _Trace.

Puoi anche impostare una descrizione e un nome visualizzato e fornire una chiave CMEK. Per saperne di più, consulta la documentazione della risorsa.

REST

Per creare un bucket di osservabilità, invia una richiesta a projects.locations.buckets.create.

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à.

Il corpo della richiesta è un oggetto Bucket. Completa i seguenti campi:

• name: imposta questo campo su:

  projects/PROJECT_ID/locations/LOCATION/buckets/_Trace
  

• (Facoltativo) Fornisci i valori per i campi displayName e description.

• (Facoltativo) Fornisci una chiave CMEK. Se specificata, questa chiave cripta i dati memorizzati.

  Se non fornisci una chiave CMEK, la chiave di crittografia è determinata dalle impostazioni predefinite che si applicano alla risorsa padre del bucket. Se le impostazioni predefinite specificano una chiave Cloud KMS, questa chiave cripta i dati archiviati. In caso contrario, viene utilizzata la crittografia predefinita di Google.

La risposta è un oggetto Operation. Esegui il polling del metodo projects.locations.operations.get finché il campo Operation.done non è impostato su true. Altri campi nella struttura Operation forniscono informazioni sull'esito positivo o negativo della richiesta.

Elenca i bucket osservabilità

Puoi elencare i bucket di osservabilità per verificare che la richiesta di creazione sia stata completata correttamente.

Questa sezione descrive come elencare i bucket di osservabilità. Un bucket di osservabilità è l'entità di gestione per i set di dati, che archiviano i dati.

gcloud

Nota: devi utilizzare gcloud CLI versione 563.0.0 o successive.

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 località, imposta la località 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

Terraform

Non puoi utilizzare Terraform per elencare i bucket di osservabilità.

REST

Per elencare i bucket di osservabilità presenti nel tuo progetto e in una località specifica, utilizza il metodo 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

Di seguito è riportato un esempio di risposta:

{
  "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 utilizzare l'API Observability per ottenere maggiori 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 saperne di più, consulta la documentazione di riferimento dell'API Observability.

Passaggi successivi

• Visualizzare e analizzare la telemetria

• Imposta valori predefiniti per i bucket di osservabilità: configura una posizione di archiviazione predefinita e una chiave di crittografia gestita dal cliente (CMEK) predefinita per i bucket di osservabilità.