Administra buckets de observabilidad

Versión preliminar

Este producto o función está con sujeción a las "Condiciones de las Ofertas de la Fase Previa a la DG" de la sección de Términos Generales del Servicio de los Términos Específicos del Servicio. Los productos y las funciones de la fase previa a la DG están disponibles sin modificaciones y pueden estar sujetos a asistencia limitada. Para obtener más información, consulta las descripciones de la etapa de lanzamiento.

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

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.
Instala Google Cloud CLI.
Si usas un proveedor de identidad externo (IdP), primero debes acceder a la gcloud CLI con tu identidad federada.
Para inicializar gcloud CLI, ejecuta el siguiente comando:
gcloud init
Crea o selecciona un Google Cloud proyecto.
Roles necesarios para seleccionar o crear un proyecto
• Selecciona un proyecto: Para seleccionar un proyecto, no se requiere un rol de IAM específico. Puedes seleccionar cualquier proyecto en el que se te haya otorgado un rol.
• Crear un proyecto: Para crear un proyecto, necesitas el rol de Creador de proyectos (roles/resourcemanager.projectCreator), que contiene el permiso resourcemanager.projects.create. Obtén más información para otorgar roles.
Nota: Si no planeas conservar los recursos que creaste durante este procedimiento, crea un proyecto en lugar de seleccionar uno existente. Cuando termines, puedes borrar el proyecto y quitar todos los recursos asociados con él.
• Crea un Google Cloud proyecto:

  gcloud projects create PROJECT_ID

  Reemplaza PROJECT_ID por un nombre para el proyecto Google Cloud que estás creando.

• Selecciona el proyecto Google Cloud que creaste:

  gcloud config set project PROJECT_ID

  Reemplaza PROJECT_ID por el nombre de tu Google Cloud proyecto.
Verifica que la facturación esté habilitada para tu proyecto de Google Cloud .
Habilita la API de Observability:
Roles necesarios para habilitar las APIs
Para habilitar las APIs, necesitas el rol de IAM de administrador de Service Usage (roles/serviceusage.serviceUsageAdmin), que contiene el permiso serviceusage.services.enable. Obtén más información para otorgar roles.
gcloud services enable observability.googleapis.com
Otorga roles a tu cuenta de usuario. Ejecuta el siguiente comando una vez para cada uno de los siguientes roles de IAM: roles/observability.viewer
gcloud projects add-iam-policy-binding PROJECT_ID --member="user:USER_IDENTIFIER" --role=ROLE
Reemplaza lo siguiente:
• PROJECT_ID: ID del proyecto
• USER_IDENTIFIER: Es el identificador de tu cuenta de usuario de . Por ejemplo, [e-mail].
• ROLE: Es el rol de IAM que otorgas a tu cuenta de usuario.

Instala Google Cloud CLI.

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

Para inicializar gcloud CLI, ejecuta el siguiente comando:

gcloud init

Crea o selecciona un Google Cloud proyecto.

Roles necesarios para seleccionar o crear un proyecto

• Selecciona un proyecto: Para seleccionar un proyecto, no se requiere un rol de IAM específico. Puedes seleccionar cualquier proyecto en el que se te haya otorgado un rol.
• Crear un proyecto: Para crear un proyecto, necesitas el rol de Creador de proyectos (roles/resourcemanager.projectCreator), que contiene el permiso resourcemanager.projects.create. Obtén más información para otorgar roles.

Nota: Si no planeas conservar los recursos que creaste durante este procedimiento, crea un proyecto en lugar de seleccionar uno existente. Cuando termines, puedes borrar el proyecto y quitar todos los recursos asociados con él.

• Crea un Google Cloud proyecto:

  gcloud projects create PROJECT_ID

  Reemplaza PROJECT_ID por un nombre para el proyecto Google Cloud que estás creando.

• Selecciona el proyecto Google Cloud que creaste:

  gcloud config set project PROJECT_ID

  Reemplaza PROJECT_ID por el nombre de tu Google Cloud proyecto.

Verifica que la facturación esté habilitada para tu proyecto de Google Cloud .

Habilita la API de Observability:

Roles necesarios para habilitar las APIs

Para habilitar las APIs, necesitas el rol de IAM de administrador de Service Usage (roles/serviceusage.serviceUsageAdmin), que contiene el permiso serviceusage.services.enable. Obtén más información para otorgar roles.

gcloud services enable observability.googleapis.com

Otorga roles a tu cuenta de usuario. Ejecuta el siguiente comando una vez para cada uno de los siguientes roles de IAM: roles/observability.viewer

gcloud projects add-iam-policy-binding PROJECT_ID --member="user:USER_IDENTIFIER" --role=ROLE

Reemplaza lo siguiente:

• PROJECT_ID: ID del proyecto
• USER_IDENTIFIER: Es el identificador de tu cuenta de usuario de . Por ejemplo, [e-mail].
• ROLE: Es el rol de IAM que otorgas a tu cuenta de usuario.

Enumera los buckets de observabilidad

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

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

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.

Enumera los vínculos en un conjunto de datos

REST

Para enumerar los vínculos en un conjunto de datos, envía una solicitud al extremo 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/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 .

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

{
  "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 una lista completa de los extremos de la API de Observabilidad, consulta la documentación de referencia de la API de Observabilidad.

Crea una vinculación en un conjunto de datos

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.

Antes de comenzar

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:

• Editor de Observability (roles/observability.editor)
• Usuario de BigQuery (roles/bigquery.user)

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

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.