Cómo guardar y compartir consultas de SQL

En este documento, se describe cómo guardar y compartir las consultas que creas en Estadísticas de observabilidad.

En este documento, se supone que estás familiarizado con Estadísticas de observabilidad y cómo usar la página Estadísticas de observabilidad para consultar tus datos de registros. Si no estás familiarizado con estos temas, consulta Consulta y analiza registros.

Para obtener información sobre cómo graficar los resultados de tus consultas y cómo guardar esos gráficos en un panel personalizado, consulta Grafica los consulta en SQL SQL.

Diferencias entre las consultas guardadas y las vistas de estadísticas

Una consulta guardada es una consulta que ejecutas con la página Estadísticas de observabilidad y que luego guardas como consulta. La acción de guardar te permite volver a ejecutar esta consulta cuando lo desees. Cuando guardas la consulta, tienes la opción de hacerla privada para ti o hacerla visible para otras personas que tengan los permisos necesarios para usar Estadísticas de observabilidad. No puedes escribir una consulta en SQL en la que la cláusula FROM especifique una consulta guardada.

Una vista de estadísticas contiene una consulta que puedes volver a ejecutar cuando lo desees. Para crear una vista de estadísticas, escribe una consulta en SQL en una vista de registros y, luego, guarda el resultado como una vista. A diferencia de las consultas guardadas, no puedes hacer que una vista de estadísticas sea privada para ti. Puedes consultar una vista de estadísticas. Esta capacidad te permite transformar tus datos de registros del formato LogEntry a otro formato que te resulte más adecuado. Luego, en lugar de escribir tus consultas en una vista de registros, consultas la vista de estadísticas.

Puedes guardar consultas que consulten una vista de registros o una vista de estadísticas.

Antes de comenzar

En esta sección, se describen los pasos que debes completar antes de poder usar Estadísticas de observabilidad.

Configura buckets de registros

Asegúrate de que tus buckets de registros se hayan actualizado para usar Estadísticas de observabilidad:

  1. En la Google Cloud consola, ve a la página Explorador de registros:

    Ir a Explorador de registros

    Si usas la barra de búsqueda para encontrar esta página, selecciona el resultado cuyo subtítulo es Logging.

  2. Para cada bucket de registros que tenga una vista de registros que deseas consultar, asegúrate de que la columna Análisis de observabilidad disponibles muestre Abrir. Si se muestra Actualizar, haz clic en Actualizar y completa el diálogo.

Configura roles y permisos de IAM

En esta sección, se describen los roles o permisos de IAM que se requieren para usar Estadísticas de observabilidad:

  • Para obtener los permisos que necesitas para usar Estadísticas de observabilidad y consultar vistas de registros, pídele a tu administrador que te otorgue los siguientes roles de IAM en tu proyecto:

    Puedes restringir una principal a una vista de registros específica agregando una condición de IAM al otorgamiento del rol Descriptor de acceso de vista de registros que se realiza a nivel del proyecto o agregando una vinculación de IAM al archivo de política de la vista de registros. Para obtener más información, consulta Controla el acceso a una vista de registros.

    Estos son los mismos permisos que necesitas para ver las entradas de registros en la página Explorador de registros. Para obtener información sobre roles adicionales que necesitas para consultar vistas en buckets definidos por el usuario o para consultar la vista _AllLogs del _Default bucket de registros, consulta Roles de Cloud Logging.

  • Para obtener los permisos que necesitas para consultar vistas de estadísticas, pídele a tu administrador que te otorgue el rol de IAM Usuario de Estadísticas de observabilidad (roles/observability.analyticsUser) en tu proyecto.

Selecciona la interfaz que planeas usar

Console

Cuando usas la Google Cloud consola para acceder a Google Cloud servicios y APIs, no necesitas configurar la autenticación.

gcloud

En la Google Cloud consola, activa Cloud Shell.

Activa Cloud Shell

En la parte inferior de la Google Cloud consola, 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 la Google Cloud CLI.

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

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

Guarda una consulta

Todas las consultas que ejecutas se guardan automáticamente durante 30 días y se puede acceder a ellas seleccionando la pestaña Recientes en la página Estadísticas de observabilidad. Puedes buscar, ver, ejecutar y compartir las consultas que aparecen en la pestaña Recientes.

Para reutilizar una consulta, agregar descripciones personalizadas o compartirla con compañeros de equipo, guarda la consulta. Puedes buscar y ordenar tus consultas guardadas por su nombre, su descripción y su etiqueta de visibilidad. También puedes editar y borrar estas consultas. Las consultas que guardas se conservan hasta que las borras.

Puedes guardar 10,000 consultas por Google Cloud proyecto.

Console

Para guardar una consulta, haz lo siguiente:

  1. En la Google Cloud consola, ve a la página Estadísticas de observabilidad:

    Ir a Estadísticas de observabilidad

    Si usas la barra de búsqueda para encontrar esta página, selecciona el resultado cuyo subtítulo es Logging.

  2. Propaga el panel Consulta con una consulta.

    Puedes propagar el panel Consulta ingresando una consulta nueva, seleccionando una consulta de la pestaña Recientes o seleccionando una consulta de la pestaña Guardadas.

    Tu consulta puede incluir cualquier vista válida, varias vistas y vistas de estadísticas.

    Cuando la consulta en el panel Consulta es válida, se habilita el botón Guardar.

  3. Haz clic en Guardar, selecciona Guardar consulta, y completa los campos Nombre y Descripción. Los valores que establezcas para estos campos se muestran en la pestaña Guardadas.

  4. Opcional: Para permitir que todos los usuarios con acceso a la página Estadísticas de observabilidad del Google Cloud proyecto vean y ejecuten tu consulta guardada, habilita el botón de activación Compartir con el proyecto.

    De forma predeterminada, este botón de activación está inhabilitado y la visibilidad está restringida a ti.

  5. Haz clic en Guardar consulta.

  6. Opcional: Para ver, ordenar y ejecutar consultas guardadas que sean visibles para ti, selecciona la pestaña Guardadas.

    Puedes ordenar y filtrar tus consultas guardadas por su nombre, descripción y etiqueta de visibilidad. También puedes filtrar por el contenido de la consulta.

Puedes editar y borrar las consultas que creaste con las opciones de la pestaña Guardadas:

  • Para editar una consulta, haz clic en Más opciones y selecciona Editar. Puedes modificar los valores de los campos Nombre y Descripción; sin embargo, la consulta en sí no se puede modificar.

  • Para borrar una consulta guardada, haz clic en Más opciones y selecciona Borrar.

gcloud

Para crear y guardar una consulta, haz lo siguiente:

  1. Antes de usar cualquiera de los datos de comando a continuación, realiza los siguientes reemplazos:

    • DISPLAY_NAME: Es el nombre visible de la consulta guardada.
    • LOCATION: Es la ubicación de la consulta guardada.
    • VISIBILITY: Se establece en private o shared.
    • SQL_QUERY: Una consulta en SQL. Si las comillas invertidas simples (`) envuelven la ruta de acceso o los campos dentro de la ruta de acceso, debes escapar esas comillas invertidas: 
          "SELECT * FROM \`PROJECT_ID.LOCATION.my-log-bucket._AllLogs\`"

      o

          "SELECT * FROM \`PROJECT_ID.LOCATION._Trace.Spans._AllSpans\`"

      Se requieren comillas invertidas (`) cuando un elemento de ruta de acceso contiene un carácter de punto (.).

    • ID: Es el ID de la consulta guardada. Este ID es una entrada obligatoria para los comandos que describen, actualizan o borran una consulta guardada. Si no proporcionas el ID cuando creas una consulta guardada, el sistema genera un ID numérico.
    • DESCRIPTION: Es una descripción de texto de la consulta. Es opcional.
    • PROJECT_ID: Es el identificador del proyecto.

    Ejecuta el gcloud logging saved-queries create comando:

    Linux, macOS o Cloud Shell

    gcloud logging saved-queries create --display-name=DISPLAY_NAME \
 --location=LOCATION --visibility=VISIBILITY --sql-query-text=SQL_QUERY \
 --id=ID --description=DESCRIPTION --project=PROJECT_ID

    Windows (PowerShell)

    gcloud logging saved-queries create --display-name=DISPLAY_NAME `
 --location=LOCATION --visibility=VISIBILITY --sql-query-text=SQL_QUERY `
 --id=ID --description=DESCRIPTION --project=PROJECT_ID

    Windows (cmd.exe)

    gcloud logging saved-queries create --display-name=DISPLAY_NAME ^
 --location=LOCATION --visibility=VISIBILITY --sql-query-text=SQL_QUERY ^
 --id=ID --description=DESCRIPTION --project=PROJECT_ID

    A continuación, se muestra una respuesta de ejemplo cuando el ID proporcionado en el comando era my-saved-query:

    Created saved query [projects/PROJECT_ID/locations/LOCATION/savedQueries/my-saved-query].

    La respuesta al comando create muestra el nombre completo de la consulta, que incluye el ID de la consulta. El ID de la consulta, que en este ejemplo es my-saved-query, es una entrada obligatoria para los comandos de Google Cloud CLI que describen, borran o actualizan una consulta guardada.

  2. Para inspeccionar la consulta guardada, ejecuta el siguiente comando:

     gcloud logging saved-queries list --location=- --project=PROJECT_ID

    En la expresión anterior, el valor de la ubicación es un guion (-), que actúa como comodín. También puedes proporcionar una ubicación específica.

Existen comandos de Google Cloud CLI para borrar, enumerar, describir y actualizar consultas guardadas. Para obtener más información, consulta la descripción general de gcloud logging saved-queries.

REST

Puedes guardar una consulta con la API de Cloud Logging. Para guardar una consulta, usa el savedQueries.create método.

Para ejecutar este método, haz lo siguiente:

  1. Selecciona savedQueries.create.
  2. En la página de referencia, usa el Explorador de APIs para emitir un comando. Debes especificar el campo opsAnalyticsQuery.

En el siguiente ejemplo, se muestra un cuerpo de solicitud de muestra, que contiene una instancia de SavedQuery:

{
   "parent": "projects/my-project/locations/global"
   "saved_query":
   {
      "ops_analytics_query":
      {
         "sql_query_text" :
            "SELECT
            timestamp, log_name, severity, json_payload, resource, labels
            FROM
            `VIEW`
            WHERE
            timestamp > TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 1 HOUR)
            ORDER BY timestamp ASC
            LIMIT 100"
      }
   "visibility": "PRIVATE"
   }
}

Comparte una consulta

Puedes compartir una consulta guardada con todos los usuarios que tengan acceso a tu Google Cloud proyecto. Sin embargo, los roles de IAM de la principal determinan si se puede ejecutar la consulta y los datos que muestra la consulta.

Console

Cuando solucionas un problema o ves resultados anómalos, es posible que desees compartir una consulta y sus resultados con un compañero de equipo. Cuando ves los resultados de la consulta en la página Estadísticas de observabilidad, puedes copiar una URL que, cuando se abre, muestra la consulta que ejecutaste y sus resultados.

Para compartir una consulta y los resultados con un compañero de equipo, haz lo siguiente:

  1. En la Google Cloud consola, ve a la página Estadísticas de observabilidad:

    Ir a Estadísticas de observabilidad

    Si usas la barra de búsqueda para encontrar esta página, selecciona el resultado cuyo subtítulo es Logging.

  2. Propaga el panel Consulta con una consulta y, luego, haz clic en Ejecutar consulta.

    Puedes propagar el panel Consulta ingresando una consulta nueva, seleccionando una consulta de la pestaña Recientes o seleccionando una consulta de la pestaña Guardadas.

  3. Haz clic en Compartir vínculo.

  4. Envía el vínculo a tu compañero de equipo.

    Cuando tu compañero de equipo abre el vínculo, se abre la página Estadísticas de observabilidad y se muestra la consulta, pero no se ejecuta. Tu compañero de equipo debe ejecutar la consulta de forma manual.

    La página Estadísticas de observabilidad muestra un diálogo de advertencia cuando la consulta se ejecuta en el motor de BigQuery y los recursos consultados no están en el mismo límite de propiedad. Los límites de propiedad se determinan por varios factores, uno de los cuales es la jerarquía de los recursos que usa la consulta.

    Para abrir la URL correctamente, el rol de IAM de tu compañero de equipo en el Google Cloud proyecto debe incluir los permisos necesarios para ver la página Estadísticas de observabilidad.

gcloud

Cuando quieras crear una consulta guardada que puedan ejecutar otros usuarios, establece el valor del campo visibility en shared:

--visibility=shared

Para cambiar la visibilidad de una consulta guardada existente, usa el comando update. Para obtener más información sobre los comandos disponibles, consulta la gcloud logging saved-queries descripción general.

REST

Puedes usar la API de Logging para crear una consulta compartida con el método savedQueries.create y especificar un valor de SHARED en el campo visibility. Para obtener más información, consulta la página de referencia de savedQueries.create.

Consulta y ejecuta consultas recientes o guardadas

Para ver o volver a ejecutar una consulta, selecciona la pestaña Recientes en la página Estadísticas de observabilidad y busca la consulta:

  • Para ejecutar la consulta, haz clic en Ejecutar.
  • Para ver la consulta, usa las opciones del menú Más opciones.

Para ver, editar o ejecutar una consulta guardada, selecciona la pestaña Guardadas en la página Estadísticas de observabilidad y busca la consulta:

  • Para ejecutar la consulta, haz clic en Ejecutar.
  • Para editar, ver o borrar la consulta, usa las opciones del menú Más opciones.

¿Qué sigue?