Administra el almacenamiento de registros

En este documento, se describe cómo usar la API de Observability para obtener información sobre el bucket de observabilidad que almacena tus datos de seguimiento. Incluye información sobre cómo enumerar conjuntos de datos, vínculos y vistas. Para obtener más información sobre cómo se almacenan tus datos de seguimiento, consulta Descripción general del almacenamiento de seguimientos.

Antes de comenzar

  1. Accede a tu Google Cloud cuenta de. 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. Instala Google Cloud CLI.

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

  4. Para inicializar gcloud CLI, ejecuta el siguiente comando: 

    gcloud init

  5. Crea o selecciona un Google Cloud proyecto.

    Roles necesarios para seleccionar o crear un proyecto

    • Seleccionar 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 resourcemanager.projects.create permiso. Obtén información para otorgar roles.

    • Crea un Google Cloud proyecto de la siguiente manera:

      gcloud projects create PROJECT_ID

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

    • Selecciona el Google Cloud proyecto de que creaste:

      gcloud config set project PROJECT_ID

      Reemplaza PROJECT_ID por el nombre de tu Google Cloud proyecto de.

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

  7. 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 serviceusage.services.enable permiso. Obtén información para otorgar roles. 

    gcloud services enable observability.googleapis.com

  8. 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: Es el ID del proyecto.
    • USER_IDENTIFIER: Es el identificador de tu cuenta de usuario. Por ejemplo, myemail@example.com.
    • ROLE: Es el rol de IAM que otorgas a tu cuenta de usuario.

  9. Instala Google Cloud CLI.

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

  11. Para inicializar gcloud CLI, ejecuta el siguiente comando: 

    gcloud init

  12. Crea o selecciona un Google Cloud proyecto.

    Roles necesarios para seleccionar o crear un proyecto

    • Seleccionar 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 resourcemanager.projects.create permiso. Obtén información para otorgar roles.

    • Crea un Google Cloud proyecto de la siguiente manera:

      gcloud projects create PROJECT_ID

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

    • Selecciona el Google Cloud proyecto de que creaste:

      gcloud config set project PROJECT_ID

      Reemplaza PROJECT_ID por el nombre de tu Google Cloud proyecto de.

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

  14. 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 serviceusage.services.enable permiso. Obtén información para otorgar roles. 

    gcloud services enable observability.googleapis.com

  15. 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: Es el ID del proyecto.
    • USER_IDENTIFIER: Es el identificador de tu cuenta de usuario. Por ejemplo, myemail@example.com.
    • ROLE: Es el rol de IAM que otorgas a tu cuenta de usuario.
    16.

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 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 enumerarán 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.

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 projects.locations.buckets.datasets.list extremo.

Debes especificar el parámetro superior, 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 Dataset objetos. 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 superior 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 emitir 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 Observability, consulta la documentación de referencia de la API de Observability.

Enumera las vistas en un conjunto de datos

REST

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

Debes especificar el parámetro superior, 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 que se consulta. Por ejemplo, este ID podría ser Spans.

La respuesta es un array de View objetos. 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 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.

Por ejemplo, cuando se emitió un comando al extremo buckets.datasets.views.list con el parámetro superior 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 Observability, consulta la documentación de referencia de la API de Observability.

REST

Para enumerar los vínculos de un conjunto de datos, envía una solicitud al projects.locations.buckets.datasets.links.list extremo.

Debes especificar el parámetro superior, 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 que se consulta. Por ejemplo, este ID podría ser Spans.

La respuesta es un array de Link objetos. 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 Google Cloud proyecto.

Por ejemplo, cuando se emitió un comando al extremo buckets.datasets.links.list con el parámetro superior 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 Observability, consulta la documentación de referencia de la API de Observability.

En esta sección, se describe cómo crear un vínculo en un conjunto de datos, lo que permite que tus datos de seguimiento se consulten desde BigQuery.

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

REST

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

Debes especificar el parámetro superior, 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 que se consulta. Por ejemplo, este ID podría ser Spans.

Este comando requiere un parámetro de consulta y un cuerpo de solicitud:

  • Se debe especificar el parámetro de consulta linkId y establecerlo 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 Google Cloud proyecto, 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 Link objeto. 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 Operation objeto. 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.

¿Qué sigue?

Para obtener más información sobre el uso de la página Explorador de seguimiento, consulta Busca y explora seguimientos.

Para obtener información sobre cómo analizar tus intervalos de seguimiento con SQL, consulta Consulta y analiza seguimientos.