Crea buckets de observabilidad

Puedes crear de forma manual el bucket de observabilidad _Trace antes de que tu proyecto reciba datos de seguimiento para personalizar su ubicación de almacenamiento y la configuración de la clave de encriptación administrada por el cliente (CMEK). Si tu Google Cloud proyecto ingiere datos de seguimiento antes de que exista este bucket, Google Cloud Observability aprovisiona automáticamente el bucket con la configuración predeterminada de tu proyecto para los buckets de observabilidad .

Para obtener información sobre cómo Google Cloud Observability almacena datos, consulta Descripción general del almacenamiento.

Interacción con las políticas de la organización

Una solicitud para crear un bucket de observabilidad verifica que los parámetros del comando cumplan con las políticas de la organización. Por ejemplo, si una política de la organización restringe las ubicaciones de los recursos, la creación de un bucket falla si especificas una ubicación restringida.

Interacción con la configuración predeterminada para los buckets de observabilidad

Cuando Google Cloud Observability crea automáticamente un bucket de observabilidad debido a la ingesta de datos, usa la configuración predeterminada para los buckets de observabilidad que se aplican al recurso superior del bucket. Esa configuración predeterminada se puede definir en el elemento superior o en un antecesor jerárquico del elemento superior, y especifica lo siguiente:

  • La ubicación de almacenamiento
  • La clave de Cloud KMS que se usará para los datos almacenados

Cuando creas un bucket de observabilidad, debes especificar una ubicación. Google Cloud Observability aplica la clave de Cloud KMS definida en tu configuración predeterminada, a menos que especifiques explícitamente una clave diferente en tu solicitud de creación.

No puedes crear un bucket con la encriptación predeterminada de Google si la configuración predeterminada aplicable especifica una clave de Cloud KMS. Para usar la encriptación predeterminada de Google, asegúrate de que no haya ninguna clave de Cloud KMS configurada en tu configuración predeterminada.

Para obtener información sobre la configuración predeterminada para los buckets de observabilidad, consulta Establece valores predeterminados para los buckets de observabilidad.

Limitaciones

Se aplican las siguientes restricciones:

  • Debes especificar una ubicación compatible.
  • El BUCKET_ID debe ser _Trace.
  • El nombre visible no debe superar los 100 bytes codificados.
  • La descripción no debe superar los 1,000 bytes codificados.
  • Los datos se almacenan durante 30 días. Debes omitir el período de retención o configurarlo en 30.
  • Si proporcionas una clave de Cloud KMS, la ubicación de la clave debe coincidir exactamente con la ubicación superior del bucket de observabilidad.
  • Solo puedes crear buckets de observabilidad en Google Cloud proyectos.
  • Un Google Cloud proyecto puede tener como máximo un bucket de observabilidad llamado _Trace.

Antes de comenzar

Configura tu proyecto y tus roles de IAM, y selecciona la interfaz que planeas usar.

Configura tu proyecto y tus roles

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

    Go to project selector

  2. Verify that billing is enabled for your Google Cloud project.

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

  4. Para obtener los permisos que necesitas para crear buckets de observabilidad, pídele a tu administrador que te otorgue el rol de IAM de editor de Observabilidad (roles/observability.editor) en tu proyecto. Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

    También puedes obtener los permisos necesarios mediante roles personalizados o cualquier otro rol predefinido.

Configura interfaces

gcloud

Instala Google Cloud CLI y, luego, accede a gcloud CLI con tu identidad federada. Después de acceder, inicializa Google Cloud CLI ejecutando el siguiente comando: 

gcloud init

REST

Para usar las muestras de la API de REST incluidas en esta página en un entorno de desarrollo local, debes usar las credenciales que proporciones a la gcloud CLI.

    Instala Google Cloud CLI y, luego, accede a gcloud CLI con tu identidad federada.

Para obtener más información, consulta Autentícate para usar REST en la Google Cloud documentación de autenticación de.

Configura la clave de Cloud KMS

Es opcional. Si planeas crear un bucket de observabilidad y especificar una clave de Cloud KMS, haz lo siguiente:

  1. Habilita la API de Cloud Key Management Service.

    Roles necesarios para habilitar las APIs

    Para habilitar las APIs, necesitas el permiso serviceusage.services.enable. Si creaste el proyecto, es probable que ya tengas este permiso a través del rol Propietario (roles/owner). De lo contrario, puedes obtener este permiso a través del rol Administrador de Service Usage (roles/serviceusage.serviceUsageAdmin). Obtén información para otorgar roles.

    Habilitar la API

  2. Crea un llavero de claves y claves.

    La ubicación del bucket de observabilidad debe coincidir con la ubicación de la clave.

  3. Reemplaza PROJECT_ID por el ID de tu proyecto y, luego, ejecuta el siguiente comando:

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

    El comando anterior verifica si configuraste una ubicación de almacenamiento predeterminada. También crea la cuenta de servicio de Google Cloud Observability cuando esa cuenta no existe. La respuesta del comando muestra el ID de la cuenta de servicio.

  4. Otorga el rol Encriptador/Desencriptador de CryptoKey de Cloud KMS a la cuenta de servicio de Google Cloud Observability.

    gcloud kms keys add-iam-policy-binding \
--project=KMS_PROJECT_ID \
--member=serviceAccount:service-PROJECT_NUMBER@gcp-sa-observability. \
--role=roles/cloudkms.cryptoKeyEncrypterDecrypter \
--location=KMS_KEY_LOCATION \
--keyring=KMS_KEY_RING \
KMS_KEY_NAME

    Antes de ejecutar el comando anterior, realiza los siguientes reemplazos:

    • KMS_PROJECT_ID: Es el identificador alfanumérico único, compuesto por el nombre de Google Cloud tu proyecto y un número asignado de forma aleatoria, del Google Cloud proyecto que ejecuta Cloud KMS. Para obtener información sobre cómo obtener este identificador, consulta Identifica proyectos.
    • service-PROJECT_NUMBER: Es el nombre de la cuenta de servicio de Observability que se mostró en la respuesta del paso anterior.
    • KMS_KEY_LOCATION: Es la región de la clave de Cloud KMS.
    • KMS_KEY_RING: Es el nombre del llavero de claves de Cloud KMS.
    • KMS_KEY_NAME: Es el nombre de la clave de Cloud KMS. Tiene el siguiente formato: projects/KMS_PROJECT_ID/locations/LOCATION/keyRings/KMS_KEY_RING/cryptoKeys/KEY.

Crea un bucket de observabilidad

REST

Para crear un bucket de observabilidad, envía una solicitud a projects.locations.buckets.create.

Debes especificar el parámetro superior, que tiene el siguiente formato:

projects/PROJECT_ID/locations/LOCATION

Los campos de la expresión anterior tienen los siguientes significados:

El cuerpo de la solicitud es un Bucket objeto. Completa los siguientes campos:

  • name: Establece este campo en lo siguiente:

    projects/PROJECT_ID/locations/LOCATION/buckets/_Trace

  • Opcional: Proporciona valores para los campos displayName y description.

  • Opcional: Proporciona una CMEK. Cuando se especifica, esta clave encripta los datos almacenados.

    Si no proporcionas una CMEK, la configuración predeterminada que se aplica al recurso superior del bucket determina la clave de encriptación. Si la configuración predeterminada especifica una clave de Cloud KMS, esa clave encripta los datos almacenados. De lo contrario, se usa la encriptación predeterminada de Google.

La respuesta es un Operation objeto. Sondea el projects.locations.operations.get método hasta que el Operation.done campo se establezca en true. Otros campos de la estructura Operation proporcionan información sobre el éxito o el fracaso de la solicitud.

Enumera los buckets de observabilidad

Puedes enumerar los buckets de observabilidad para verificar que la solicitud de creación se haya completado correctamente.

gcloud

Antes de usar cualquiera de los datos de comando a continuación, realiza los siguientes reemplazos:

  • LOCATION: Es la ubicación de los buckets de observabilidad. Para enumerar todos los buckets de observabilidad, sin importar la ubicación, establece la ubicación en un guion (-).
  • PROJECT_ID: Es el identificador del proyecto.

Ejecuta el 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 respuesta muestra el nombre, la descripción y la hora de creación de cada buckets de observabilidad. El siguiente es un ejemplo de una respuesta cuando el comando se ejecuta correctamente: 

---
createTime: '2026-01-21T21:39:22.381083860Z'
description: Bucket for storing spans from Cloud Trace.
name: projects/my-project/locations/us/buckets/_Trace

REST

Para enumerar los buckets de observabilidad que se encuentran en tu proyecto y en una ubicación específica, envía una solicitud al extremo projects.locations.buckets.list.

Debes especificar el parámetro superior, que tiene el siguiente formato:

projects/PROJECT_ID/locations/LOCATION

Los campos de la expresión anterior tienen los siguientes significados:

  • PROJECT_ID: Es el identificador del proyecto.
  • LOCATION: Es la ubicación del bucket de observabilidad. Si estableces LOCATION en un guion, (-), se enumeran todos los buckets de observabilidad de tu proyecto.

La respuesta es un array de Bucket objetos. Para cada objeto, el valor del campo name tiene el siguiente formato:

projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID

Por ejemplo, cuando se emitió un comando al extremo buckets.list con el parámetro superior establecido en projects/my-project/locations/us, la respuesta fue la siguiente:

{
  "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
    }
  ]
}

Puedes emitir comandos a otros extremos de la API de Observability para obtener más información sobre el bucket cuyo ID es BUCKET_ID. Por ejemplo, puedes enumerar los conjuntos de datos en ese bucket, y las vistas y los vínculos en cada conjunto de datos. Para obtener una lista completa de los extremos de la API de Observability, consulta la documentación de referencia de la API de Observability.

¿Qué sigue?