Crea bucket di osservabilità

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

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

Interazione con i criteri dell'organizzazione

Una richiesta di creazione di un bucket di osservabilità verifica che i parametri del comando siano conformi ai criteri dell'organizzazione. Ad esempio, se un criterio dell'organizzazione limita le località delle risorse, la creazione di un bucket non riesce 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'acquisizione dei dati, utilizza le impostazioni predefinite per i bucket di osservabilità che si applicano alla risorsa principale del bucket. Queste impostazioni predefinite potrebbero essere definite nell'elemento principale o in un predecessore gerarchico dell'elemento principale e specificano quanto segue:

• La località 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à, consulta Impostare i valori predefiniti per i bucket di osservabilità.

Limitazioni

Si applicano le seguenti limitazioni:

• Devi specificare una località supportata.
• Il 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 località della chiave deve corrispondere esattamente alla località principale del bucket di osservabilità.
• Puoi creare bucket di osservabilità solo nei Google Cloud progetti.
• Un Google Cloud progetto 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 intendi utilizzare.

Configurare il progetto e i ruoli

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 eseguire, testare e implementare 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 di osservabilità (roles/observability.editor) nel tuo progetto. Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

   Potresti anche essere in grado di ottenere le autorizzazioni richieste tramite ruoli personalizzati o altri ruoli predefiniti.

Configurare le interfacce

gcloud

Nella Google Cloud console, attiva Cloud Shell.

Attiva Cloud Shell

Nella parte inferiore della Google Cloud console, 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à inclusa e 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 Google Cloud documentazione sull'autenticazione di.

Configurare la chiave Cloud KMS

Facoltativo. Se prevedi di creare un bucket di osservabilità e di specificare una chiave Cloud KMS, procedi nel seguente modo:

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 hai già questa autorizzazione tramite il ruolo Proprietario (roles/owner). In caso contrario, puoi ottenere questa autorizzazione tramite il ruolo Amministratore utilizzo servizi (roles/serviceusage.serviceUsageAdmin). Scopri come concedere i ruoli.

   Abilitare l'API

2. Crea chiavi automatizzate e 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 seguente comando:

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

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

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 Google Cloud progetto e da un numero assegnato in modo casuale, del Google Cloud progetto che esegue Cloud KMS. Per informazioni su come ottenere questo identificatore, consulta Identificare i progetti.
   • service-PROJECT_NUMBER: il nome del service account di osservabilità 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. Il formato è il seguente: projects/KMS_PROJECT_ID/locations/LOCATION/keyRings/KMS_KEY_RING/cryptoKeys/KEY.

Creare un bucket di osservabilità

REST

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

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

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

• name: imposta questo campo su:

  projects/PROJECT_ID/locations/LOCATION/buckets/_Trace
  

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

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

  Se non fornisci una CMEK, le impostazioni predefinite che si applicano alla risorsa principale del bucket determinano la chiave di crittografia. 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 Operation oggetto. Esegui il polling del projects.locations.operations.get metodo finché il Operation.done campo non è impostato su true. Altri campi nella struttura Operation forniscono informazioni sul successo o sul fallimento della richiesta.

Elencare i bucket di osservabilità

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

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 località dei bucket di osservabilità. Per elencare tutti i bucket di osservabilità, indipendentemente dalla località, imposta la località su un trattino (-).
• PROJECT_ID: l'identificatore del progetto.

Esegui il gcloud beta observability buckets list comando:

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

Passaggi successivi

• Visualizzare e analizzare la telemetria

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