Crea buckets de observabilidad

Puedes crear manualmente 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 proyecto de Google Cloud 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 los datos, consulta la 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 recursos, fallará la creación de un bucket si especificas una ubicación restringida.

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

Cuando Google Cloud Observability crea automáticamente un bucket de observabilidad debido a la transferencia de datos, utiliza la configuración predeterminada para los buckets de observabilidad que se aplica al recurso principal del bucket. Esos parámetros de configuración predeterminados se pueden definir en el elemento superior o en un elemento principal jerárquico del elemento superior, y especifican lo siguiente:

• Es la ubicación de almacenamiento.
• Es 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 tus parámetros de configuración predeterminados.

Para obtener información sobre la configuración predeterminada de los buckets de observabilidad, consulta Cómo establecer la configuración predeterminada para los buckets de observabilidad.

Limitaciones

Se aplican las siguientes restricciones:

• Debes especificar una ubicación admitida.
• 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 establecerlo en 30.
• Si proporcionas una clave de Cloud KMS, la ubicación de la clave debe coincidir exactamente con la ubicación principal del bucket de observabilidad.
• Solo puedes crear buckets de observabilidad en proyectos de Google Cloud .
• Un proyecto Google Cloud 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

Accede a tu cuenta de Google Cloud . Si eres nuevo en Google Cloud, crea una cuenta para evaluar el rendimiento de nuestros productos en situaciones reales. Los clientes nuevos también obtienen $300 en créditos gratuitos para ejecutar, probar y, además, implementar cargas de trabajo.

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. 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 a través de roles personalizados o cualquier otro rol predefinido.

Configura interfaces

gcloud

En la consola de Google Cloud , activa Cloud Shell.

Activa Cloud Shell

En la parte inferior de la consola de Google Cloud , se inicia una sesión de Cloud Shell en la que se muestra una ventana de línea de comandos. Cloud Shell es un entorno de shell con Google Cloud CLI ya instalada y con valores ya establecidos para el proyecto actual. La sesión puede tardar unos segundos en inicializarse.

Terraform

Para usar las muestras de Terraform de esta página en un entorno de desarrollo local, instala e inicializa la gcloud CLI y, luego, configura las credenciales predeterminadas de la aplicación con tus credenciales de usuario.

1. Instala Google Cloud CLI.

2. Si usas un proveedor de identidad (IdP) externo, primero debes acceder a gcloud CLI con tu identidad federada.

3. Si usas una shell local, crea credenciales de autenticación locales para tu cuenta de usuario:

   gcloud auth application-default login

   No es necesario que lo hagas si usas Cloud Shell.

   Si se devuelve un error de autenticación y usas un proveedor de identidad (IdP) externo, confirma que accediste a la gcloud CLI con tu identidad federada.

Para obtener más información, consulta Configura ADC para un entorno de desarrollo local en la documentación de autenticación de Google Cloud .

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.

Si usas un proveedor de identidad externo (IdP), primero debes acceder a la gcloud CLI con tu identidad federada.

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

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 APIs, necesitas el permiso serviceusage.services.enable. Si creaste el proyecto, es probable que ya tengas este permiso a través del rol de propietario (roles/owner). De lo contrario, puedes obtener este permiso a través del rol de administrador de Service Usage (roles/serviceusage.serviceUsageAdmin). Obtén más 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 esta no existe. La respuesta del comando muestra el ID de la cuenta de servicio.

4. Otorga el rol de 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:[e-mail] \
   --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 tu proyecto de Google Cloud y un número asignado de forma aleatoria, del proyecto de Google Cloud 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 Observabilidad que se indicó 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. Su formato es el siguiente: projects/KMS_PROJECT_ID/locations/LOCATION/keyRings/KMS_KEY_RING/cryptoKeys/KEY.

Crea un bucket de observabilidad

gcloud

No compatible.

Terraform

Para crear un bucket de observabilidad, usa el recurso de Terraform google_observability_bucket y configura los siguientes campos:

• project: Es el ID del proyecto
• location: Es la ubicación del bucket de observabilidad. Para obtener más información, consulta Ubicaciones.
• bucket_id: Es el ID del bucket de observabilidad. Este campo debe establecerse en _Trace.

También puedes establecer una descripción y un nombre visible, y proporcionar una CMEK. Para obtener más información, consulta la documentación del recurso.

REST

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

Debes especificar el parámetro principal, 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.

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

• name: Configura este campo de la siguiente manera:

  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 clave de encriptación se determina según la configuración predeterminada que se aplica al recurso principal del bucket. 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 objeto Operation. Sondea el método projects.locations.operations.get hasta que el campo Operation.done 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.

En esta sección, se describe cómo enumerar tus buckets de observabilidad. Un bucket de observabilidad es la entidad de administración de los conjuntos de datos, que almacenan datos.

gcloud

Nota: Debes usar la versión 563.0.0 de gcloud CLI o una posterior.

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

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

Ejecuta el 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 respuesta enumera el nombre, la descripción y la hora de creación de cada buckets de observabilidad. A continuación, se muestra 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

Terraform

No puedes usar Terraform para enumerar los buckets de observabilidad.

REST

Para enumerar los buckets de observabilidad que se encuentran en tu proyecto y en una ubicación específica, usa el método projects.locations.buckets.list.

Debes especificar el parámetro principal, 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 enumerarán todos los buckets de observabilidad de tu proyecto.

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

projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID

A continuación, se muestra una respuesta de ejemplo:

{
  "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 usar 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 más información, consulta la documentación de referencia de la API de Observability.

¿Qué sigue?

• Cómo buscar y explorar registros

• Cómo consultar y analizar registros con SQL

• Establece valores predeterminados para los buckets de observabilidad: Configura una ubicación de almacenamiento predeterminada y una clave de encriptación administrada por el cliente (CMEK) predeterminada para tus buckets de observabilidad.