Enumera los buckets de seguimiento y administra los conjuntos de datos

Puedes usar la API de Observability o Google Cloud CLI para ver tus buckets de observabilidad, inspeccionar conjuntos de datos y vistas, y crear vínculos para analizar los datos de seguimiento almacenados con SQL.

Para obtener información conceptual y detalles de almacenamiento, consulta Descripción general del almacenamiento de registros y Esquema de registros.

Antes de comenzar

Configura tu proyecto y tus roles de Identity and Access Management (IAM), y selecciona la interfaz que planeas usar.

Configura tu proyecto y tus roles

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

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

  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.

Selecciona la interfaz que planeas usar

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.

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

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

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

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

Enumera los conjuntos de datos en un bucket de observabilidad

En esta sección, se describe cómo enumerar los conjuntos de datos de observabilidad en un bucket de observabilidad. Un bucket de observabilidad es el contenedor de administración de los conjuntos de datos, que almacenan datos. Cuando Google Cloud Observability crea un bucket, también crea automáticamente un conjunto de datos.

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, usa el método 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/datasets/DATASET_ID

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

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

Enumera las vistas de un conjunto de datos

En esta sección, se describe cómo enumerar tus vistas de observabilidad. Cada conjunto de datos de observabilidad aloja una o más vistas. Una vista proporciona acceso de lectura a un subconjunto de entradas del conjunto de datos. Google Cloud Observability crea una vista cuando crea un conjunto de datos. Esa vista incluye todos los datos del 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 mostrar una lista de las vistas de un conjunto de datos, usa el método 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/datasets/DATASET_ID/views/OBS_VIEW_ID

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

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

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

En esta sección, se describe cómo enumerar los vínculos en tus conjuntos de datos de observabilidad. Una vinculación puede permitirte consultar tus datos con los servicios de BigQuery o permitir que un servicio de Google Cloud consulte un subconjunto de esos 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 links list:

Linux, macOS o Cloud Shell

gcloud beta observability buckets datasets links 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 links 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 links 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 y la hora de creación de cada vínculo. A continuación, se muestra un ejemplo de la respuesta cuando el comando se ejecuta correctamente:

---
createTime: '2026-04-02T21:23:09.272323714Z'
name: projects/my-project/locations/us/buckets/_Trace/datasets/Spans/links/mydataset

REST

Para enumerar los vínculos en un conjunto de datos, usa el método projects.locations.buckets.datasets.links.list.

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 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 Link. Para cada objeto, el valor del campo name tiene el siguiente formato:

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

LINK_ID es el nombre del conjunto de datos de BigQuery. Este campo es único a nivel global para tu proyecto Google Cloud .

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

{
  "links": [
    {
      "name": "projects/my-project/locations/us/buckets/_Trace/datasets/Spans/links/my_link",
      "description": "My link for traces to BigQuery",
      "createTime": "2025-01-12T15:42:30.988919645Z"
    }
  ]
}

Para obtener más información, consulta la documentación de referencia de la API de Observability.

En esta sección, se describe cómo crear un conjunto de datos de BigQuery vinculado en un conjunto de datos de observabilidad, lo que te permite usar los servicios de BigQuery para consultar tus datos de seguimiento. Cada conjunto de datos de observabilidad admite un conjunto de datos de BigQuery vinculado.

Cuando creas una vinculación en un conjunto de datos de observabilidad, ocurre lo siguiente:

  • Google Cloud Observability puede crear las siguientes cuentas de servicio o modificar sus otorgamientos de roles de IAM:

  • Los registros de auditoría registran la solicitud para crear un vínculo y la solicitud del administrador del agente de servicio para otorgar a la cuenta de servicio de Monitoring el rol de IAM de Agente de servicio de Monitoring. Estos registros también registran la finalización de la operación de larga duración.

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 Cloud Monitoring and Observability APIs.

    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 APIs

  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 Cloud Monitoring and Observability APIs.

    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 APIs

  8. Para obtener los permisos que necesitas para crear un vínculo en un conjunto de datos 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.

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/datasets/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 Observability, consulta la documentación de referencia de la API de Observability.

Si encuentras errores de permiso cuando creas un conjunto de datos vinculado, consulta Soluciona problemas de permisos.

¿Qué sigue?