Administra buckets de observabilidad

En este documento, se describe cómo usar la API de Observability para obtener información sobre tus buckets de observabilidad. También incluye información sobre cómo mostrar conjuntos de datos, vínculos y vistas. Para obtener más información sobre cómo Google Cloud Observability almacena los datos, consulta la Descripción general del almacenamiento.

Tus datos de seguimiento se almacenan en buckets de observabilidad. En este documento, se describe cómo administrar el almacenamiento de tus datos de seguimiento, pero no se describe el formato de los datos almacenados. Para obtener información sobre ese tema, consulta Esquema de Trace.

Este documento no se aplica al almacenamiento de datos de registro o de métricas. Los datos de registros y métricas no se almacenan en buckets de observabilidad.

Antes de comenzar

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

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

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

  4. Enable the Observability API.

    Roles required to enable APIs

    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

    Enable the API

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

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

  7. Enable the Observability API.

    Roles required to enable APIs

    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

    Enable the API

    8.

  8. Para obtener los permisos que necesitas para enumerar buckets, vínculos y vistas, pídele a tu administrador que te otorgue el rol de IAM de Visualizador de Observabilidad (roles/observability.viewer) 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.

  9. Selecciona la pestaña que corresponda a la forma en que planeas usar las muestras de esta página:

    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 que muestra una ventana emergente con una 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.

    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 .

Enumera los buckets de observabilidad

gcloud

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 fecha 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

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 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 configuras LOCATION como 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

Por ejemplo, cuando se emitió un comando al extremo buckets.list con el parámetro principal 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 enviar comandos a otros extremos de la API de Observabilidad 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 Observabilidad, consulta la documentación de referencia de la API de Observabilidad.

Enumera los conjuntos de datos en un bucket de observabilidad

gcloud

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

  • BUCKET_ID: Es el ID del bucket de observabilidad. Por ejemplo, este ID podría ser _Trace.
  • LOCATION: Es la ubicación de los buckets de observabilidad.
  • PROJECT_ID: Es el identificador del proyecto.

Ejecuta el comando gcloud beta observability buckets datasets list:

Linux, macOS o Cloud Shell

gcloud beta observability buckets datasets list \
 --bucket=projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID \
 --location=LOCATION \
 --project=PROJECT_ID

Windows (PowerShell)

gcloud beta observability buckets datasets list `
 --bucket=projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID `
 --location=LOCATION `
 --project=PROJECT_ID

Windows (cmd.exe)

gcloud beta observability buckets datasets list ^
 --bucket=projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID ^
 --location=LOCATION ^
 --project=PROJECT_ID

La respuesta enumera el nombre, la descripción y la hora de creación de cada conjunto de datos. A continuación, se muestra un ejemplo de la respuesta cuando el comando se ejecuta correctamente: 

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

REST

Para enumerar los conjuntos de datos de un bucket de observabilidad, envía una solicitud al extremo projects.locations.buckets.datasets.list.

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

projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID

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.
  • BUCKET_ID: Es el ID del bucket de observabilidad. Por ejemplo, este ID podría ser _Trace.

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

projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID/dataset/DATASET_ID

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

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

Puedes enviar comandos a otros extremos de la API de Observability para obtener información sobre el conjunto de datos cuyo ID es DATASET_ID. Por ejemplo, puedes enumerar las vistas y los vínculos en cada conjunto de datos. Para obtener una lista completa de los extremos de la API de Observabilidad, consulta la documentación de referencia de la API de Observabilidad.

Enumera las vistas de un conjunto de datos

gcloud

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

  • DATASET_ID: El ID del conjunto de datos. Tus datos de seguimiento se almacenan en un conjunto de datos llamado Spans.
  • BUCKET_ID: Es el ID del bucket de observabilidad. Por ejemplo, este ID podría ser _Trace.
  • LOCATION: Es la ubicación de los buckets de observabilidad.
  • PROJECT_ID: Es el identificador del proyecto.

Ejecuta el comando gcloud beta observability buckets datasets views list:

Linux, macOS o Cloud Shell

gcloud beta observability buckets datasets views list \
 --dataset=projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID/datasets/DATASET_ID \
 --bucket=BUCKET_ID \
 --location=LOCATION \
 --project=PROJECT_ID

Windows (PowerShell)

gcloud beta observability buckets datasets views list `
 --dataset=projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID/datasets/DATASET_ID `
 --bucket=BUCKET_ID `
 --location=LOCATION `
 --project=PROJECT_ID

Windows (cmd.exe)

gcloud beta observability buckets datasets views list ^
 --dataset=projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID/datasets/DATASET_ID ^
 --bucket=BUCKET_ID ^
 --location=LOCATION ^
 --project=PROJECT_ID

La respuesta enumera el nombre, la hora de creación y la hora de actualización de cada vista 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'
displayName: _AllSpans
name: projects/pamstestproject1/locations/us/buckets/_Trace/datasets/Spans/views/_AllSpans
updateTime: '2026-01-21T21:39:22.381083860Z'

REST

Para enumerar las vistas de un conjunto de datos, envía una solicitud al extremo projects.locations.buckets.datasets.views.list.

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

projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID/datasets/DATASET_ID/views

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.
  • BUCKET_ID: Es el ID del bucket de observabilidad. Por ejemplo, este ID podría ser _Trace.
  • DATASET_ID: Es el ID del conjunto de datos para el que se realiza la consulta. Por ejemplo, este ID podría ser Spans.

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

projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID/views/OBS_VIEW_ID

En el ejemplo anterior, el ID de una vista se representa con OBS_VIEW_ID. Por ejemplo, este campo podría tener un valor de _AllSpans.

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

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

Para obtener una lista completa de los extremos de la API de Observabilidad, consulta la documentación de referencia de la API de Observabilidad.

Puedes crear un vínculo en un conjunto de datos, lo que permite que tus datos de seguimiento se consulten desde BigQuery. También puedes borrar el objeto Link que está adjunto a un conjunto de datos.

  1. Completa la configuración necesaria para mostrar vínculos.

  2. Para obtener los permisos que necesitas para crear un vínculo en un conjunto de datos, pídele a tu administrador que te otorgue los siguientes roles de IAM 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.

Crea un conjunto de datos vinculado a BigQuery

gcloud

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

  • LINK_ID: El nombre del conjunto de datos de BigQuery
  • DATASET_ID: El ID del conjunto de datos. Tus datos de seguimiento se almacenan en un conjunto de datos llamado Spans.
  • BUCKET_ID: Es el ID del bucket de observabilidad. Por ejemplo, este ID podría ser _Trace.
  • LOCATION: Es la ubicación de los buckets de observabilidad.
  • PROJECT_ID: Es el identificador del proyecto.

Ejecuta el comando gcloud beta observability buckets datasets links create:

Linux, macOS o Cloud Shell

gcloud beta observability buckets datasets links create \
  projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID/datasets/DATASET_ID/links/LINK_ID \
 --dataset=DATASET_ID\
 --bucket=BUCKET_ID \
 --location=LOCATION \
 --project=PROJECT_ID

Windows (PowerShell)

gcloud beta observability buckets datasets links create `
  projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID/datasets/DATASET_ID/links/LINK_ID `
 --dataset=DATASET_ID`
 --bucket=BUCKET_ID `
 --location=LOCATION `
 --project=PROJECT_ID

Windows (cmd.exe)

gcloud beta observability buckets datasets links create ^
  projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID/datasets/DATASET_ID/links/LINK_ID ^
 --dataset=DATASET_ID^
 --bucket=BUCKET_ID ^
 --location=LOCATION ^
 --project=PROJECT_ID

El comando create inicia una operación de larga duración. A continuación, se muestra un ejemplo de la respuesta cuando el comando se ejecuta correctamente: 

Create request issued for: [mydataset]
Waiting for operation [projects/my-project/locations/us/operations/operation-1775164903749-64e80c9817833-9ff804b6-c3e9cbe7] to complete...done.
Created link [mydataset].

REST

Para crear un vínculo a un conjunto de datos de BigQuery, envía una solicitud al extremo projects.locations.buckets.datasets.links.create.

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

projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID/datasets/DATASET_ID

Los campos de la expresión anterior tienen el siguiente significado:

  • PROJECT_ID: Es el identificador del proyecto.
  • LOCATION: Es la ubicación del bucket de observabilidad.
  • BUCKET_ID: Es el ID del bucket de observabilidad. Por ejemplo, este ID podría ser _Trace.
  • DATASET_ID: Es el ID del conjunto de datos para el que se realiza la consulta. Por ejemplo, este ID podría ser Spans.

Este comando requiere un parámetro de búsqueda y un cuerpo de solicitud:

  • El parámetro de consulta, linkId, se debe especificar y establecer en el nombre del conjunto de datos de BigQuery. Por ejemplo, linkId="my_link" El nombre del conjunto de datos de BigQuery debe ser único para tu proyecto Google Cloud , debe tener un límite de 100 caracteres y solo puede incluir letras, dígitos y guiones bajos.

  • El cuerpo de la solicitud es un objeto Link. El valor del campo name tiene el siguiente formato:

    projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID/dataset/DATASET_ID/links/LINK_ID

    El valor que proporcionas para el campo name debe coincidir con el conjunto de datos de BigQuery vinculado al que hace referencia el parámetro de consulta.

    El campo LINK_ID es el nombre del conjunto de datos de BigQuery.

La respuesta es un objeto Operation. Este objeto contiene información sobre el progreso del método. Cuando se completa el método, el objeto Operation contiene datos de estado.

Para obtener una lista completa de los extremos de la API de Observabilidad, consulta la documentación de referencia de la API de Observabilidad.

¿Qué sigue?

Para obtener información sobre cómo consultar tus datos de telemetría, consulta Cómo ver y analizar los datos de telemetría.