Usa el editor de código para MQL

En esta sección, se describen las funciones del editor de código para el lenguaje de consulta de Monitoring (MQL). El editor está disponible en la consola de Google Cloud y proporciona sugerencias, detección de errores y otro tipo de asistencia para crear consultas de MQL válidas.

Esta página no cubre el lenguaje MQL. Para obtener un conjunto de ejemplos y obtener más información sobre el lenguaje, consulta Ejemplos y Acerca del lenguaje MQL. La Referencia de MQL proporciona una referencia completa para el lenguaje.

Cómo acceder al editor de código

Para acceder al editor de código cuando uses el Explorador de métricas, haz lo siguiente:

1. En el panel de navegación de la consola de Google Cloud, elige Monitoring y, luego,  Explorador de métricas:

   Ir al Explorador de métricas

2. En la barra de herramientas del panel del compilador de consultas, selecciona el botón cuyo nombre sea  MQL o  PromQL.
3. Verifica que MQL esté seleccionado en el botón de activación Idioma. El botón de activación del idioma está en la misma barra de herramientas que te permite dar formato a tu consulta.

Usas pasos similares para acceder al editor de código cuando creas un gráfico en un panel.

Usando el editor de código

Para usar el editor de código, escribe tu consulta en el cuadro de texto y haz clic en Run Query:

Autocompletado

A medida que escribes tu consulta, el editor muestra una lista de finalizaciones válidas de forma sintáctica. Puedes abrir el menú de autocompletado de forma manual si presionas Control+Space y puedes descartarlo si presionas Escape.

Para navegar por la lista de opciones, usa las teclas de flecha. Si presionas Enter, se inserta la opción seleccionada.

Para insertar el prefijo que se aplica a todas las opciones disponibles, presiona Tab.

Mensajes de error

Los mensajes de error aparecen en la parte inferior del panel del editor.

Si hay errores en la consulta que interfieren con las sugerencias de autocompletado, los mensajes de error aparecen a medida que escribes. De lo contrario, aparecerán los mensajes de error cuando ejecutes la consulta.

Plegado de código

El editor proporciona plegado de código, la capacidad de contraer segmentos de tus consultas, para que puedas ocultarlos temporalmente de la vista.

El editor indica segmentos plegables de la consulta con signos de intercalación junto a los números de línea, como se muestra en la siguiente captura de pantalla:

Buscar y reemplazar

El editor admite la función de buscar y reemplazar. Para buscar términos en tu consulta y, de manera opcional, reemplazarlos, presiona Control+F (o Command+F en Mac). En la siguiente captura de pantalla, se muestra la función:

Controles del editor

El editor tiene dos controles que determinan cómo interactúa con tu consulta.

De forma predeterminada, tu consulta se ejecuta solo cuando haces clic en Ejecutar consulta. Puedes configurar el editor de código para que ejecute automáticamente tu consulta mientras escribes, pero esta opción está inhabilitada de forma predeterminada.

Para habilitar la opción de ejecución automática, usa el botón de activación Auto-run. Cuando esta opción está habilitada, el editor funciona de la siguiente manera:

• No se muestra el botón Ejecutar consulta.
• Los mensajes de error aparecen de forma continua a medida que escribes.

• Si el cursor está al final de una consulta que está incompleta, pero no tiene errores, el editor muestra un triángulo amarillo en la barra de control. Si hay espacio, también aparece el texto Consulta incompleta.

  El editor de código no intenta evaluar las consultas incompletas.

También hay una barra de herramientas entre el editor de código y la región del gráfico. Usa esta barra para cambiar los tamaños relativos de las dos regiones.

Guarda gráficos

Desde el Explorador de métricas

En el editor de código del Explorador de métricas, tienes la opción de guardar el gráfico en un panel. Para guardar el gráfico, haz lo siguiente:

1. Si no tienes habilitada la opción de ejecución automática, haz clic en Ejecutar consulta para ejecutar tu consulta antes de guardar el gráfico. Si no ejecutas tu consulta primero, el editor de código guarda la última consulta que ejecutaste.

2. Haz clic en Save Chart. Un cuadro de diálogo te indica que guardar el gráfico reemplaza la consulta con un formato estricto. Para obtener más información, lee Consultas estrictas.

3. Para seguir guardando el gráfico, sigue estos pasos:

   1. Ponle un título descriptivo al gráfico.
   2. Selecciona el panel deseado para el gráfico nuevo.
   3. Haz clic en Guardar en el cuadro de diálogo.

Desde un panel

Para guardar un gráfico que agregues a un panel, haz lo siguiente:

1. Ponle un título descriptivo al gráfico.

2. Si no tienes habilitada la opción de ejecución automática, haz clic en Ejecutar consulta para ejecutar tu consulta antes de guardar el gráfico. Si no ejecutas tu consulta primero, el editor de código guarda la última consulta que ejecutaste.

3. Haz clic en Guardar. Un cuadro de diálogo te indica que guardar el gráfico reemplaza la consulta con un formato estricto. Para obtener más información, lee Consultas estrictas.

4. Haz clic en Guardar en el cuadro de diálogo para guardar tu gráfico y regresar al panel.

Salir del editor de código

Para salir del editor de código sin guardar un gráfico o una condición, haz clic en Volver al widget del selector de consultas. Cualquier texto de consulta en el editor se descarta, pero tienes la opción de guardarlo en el portapapeles.

Ver consultas de forma estricta

Para ver una consulta de forma estricta cuando uses el editor de código, haz clic en Más opciones y selecciona Ver formato estricto.

Para obtener más información, lee Consultas estrictas.

Períodos, gráficos y el editor de código

Excepto por las consultas de MQL que se usan en condiciones para las políticas de alertas, las consultas de MQL en el editor de código deben incluir un intervalo de tiempo. El intervalo de tiempo especifica el subconjunto de datos que se mostrará como parte de la consulta. El intervalo de tiempo se puede expresar de forma implícita mediante el selector de rango de tiempo del gráfico o de forma explícita en el texto de consulta de MQL.

De forma predeterminada, el selector de intervalo de tiempo se establece en una hora.

Para cambiar el intervalo de tiempo de un gráfico, usa el selector de intervalo de tiempo. Por ejemplo, si deseas ver los datos de la última semana, selecciona Última semana en el selector de intervalo de tiempo. También puedes especificar una hora de inicio y finalización, o bien especificar una hora para ver los alrededores.

Para obtener información sobre cómo crear políticas de alertas con el editor de código, consulta Crea políticas de alertas de MQL.

Usa la configuración del gráfico para la selección de tiempo

Puedes configurar el período de una consulta con el selector de hora del gráfico. Este selector es la forma predeterminada para establecer el período. Para cambiar el período, selecciona una opción de tiempo diferente en el gráfico. Si seleccionas, por ejemplo, una semana, tu consulta muestra los datos de hoy a una semana.

Cuando usas este mecanismo predeterminado, no tienes que especificar un intervalo de tiempo explícito en el texto de tu consulta. El valor del gráfico se usa de forma implícita.

Usa within para seleccionar la hora

Puedes especificar el intervalo de tiempo de la consulta de forma explícita en la consulta con la operación within. Esta operación determina el rango de datos mostrados. Si tu consulta incluye una operación within, las opciones de selección de tiempo del gráfico están inhabilitadas y se usa el intervalo de tiempo especificado en la consulta.

Si quitas una operación explícita within de tu consulta, las opciones de gráfico se vuelven a habilitar de forma automática, lo que garantiza que tu consulta siempre incluya un período.

Debes usar una selección de tiempo explícita si deseas usar el método de API timeSeries.query para emitir la consulta. Para obtener más información, consulta Usa MQL desde la API de Monitoring.

Configuración de hora y gráficos guardados

Si usas MQL para crear un gráfico y luego guardas el gráfico en un panel, a la consulta le ocurren dos cosas:

1. La consulta que proporcionaste en el editor se convierte en una forma canónica o estricta. La conversión no cambia el significado de tu consulta, pero realiza acciones explícitas que se suponen en la consulta, como operaciones de alineación o nombres de columna completos. Para obtener más información, lee Consultas estrictas.

2. Se quita la selección de intervalo de tiempo en tu consulta. Los gráficos de los paneles comparten un selector de tiempo, y los cambios en ese selector se aplican a todos los gráficos del panel. Por lo tanto, ya no se necesita el selector de intervalo de tiempo de la consulta original.

Para obtener información sobre cómo administrar paneles y editar gráficos, consulta Administra paneles personalizados.

Períodos de consulta, alineación y visualización

MQL tiene varias operaciones potencialmente confusas que especifican períodos. Las siguientes operaciones están relacionadas con el rango de una consulta:

• within: especifica la ventana de resultados de las consultas. Esta operación determina cuántos datos se muestran. Por ejemplo, si especificas within 1h, la consulta produce solo puntos cuyas marcas de tiempo se encuentran dentro de la última hora, por lo que esta operación anula las opciones del selector de tiempo del gráfico.

• Las siguientes operaciones se relacionan con el período de alineación de sus tablas de salida. Ambos necesitan una tabla alineada como entrada, o proporcionan una configuración predeterminada:

  • every: Especifica el período para el resultado de la tabla alineada.

  • window: Especifica la ventana para las operaciones de alineación

  En ambos casos, si se proporciona una operación align con una ventana de alineación explícita, debe coincidir con el período especificado para la operación window, si se proporciona. Para la función de alineación delta, la ventana de alineación y el período deben ser iguales. Si se proporciona una ventana de alineación explícita, la operación every debe aceptar, si se la incluye. En todos los casos, la ventana de alineación debe ser al menos tan grande como el período de alineación o los datos de entrada que se ignorarán.

MQL también tiene una operación graph_period, que especifica el período de los puntos de salida para los gráficos. Esta operación es útil en las consultas a la API cuyos resultados se reportan mediante software de terceros. El software de gráfico de Monitoring ignora la operación graph_period en las consultas y configura el período de los puntos según el ancho en el momento del gráfico de salida.

En los gráficos de Monitoring, el período del gráfico se establece en función del valor del selector de intervalo de tiempo del gráfico y la cantidad máxima de puntos que puede mostrar un gráfico. Por ejemplo, si seleccionas una semana, el período del grafo puede ser una hora. Para ver el período del gráfico, haz clic en Estadísticas de consultas para los gráficos de los paneles.

La relación entre el período de alineación de la consulta y el período del gráfico puede cambiar el aspecto de un gráfico. Esta relación se describe en la siguiente sección.

Bandas máximas y mínimas

Cuando el período de alineación de consultas está cerca del período del grafo, el gráfico representa cada serie temporal gráfica con una sola línea. Si el período de alineación de la fila es menor que la mitad del período del gráfico del gráfico, este incluye una región sombreada alrededor de cada línea. Esta región, denominada banda máxima y máxima, muestra el rango de valores que produjeron el valor medio.

Por ejemplo, supongamos que la siguiente consulta simple de MQL es la siguiente:

fetch gce_instance::compute.googleapis.com/instance/cpu/utilization
| group_by [zone], mean(val())
| every 1h

Esta consulta muestra el uso promedio de CPU de las VM por zona, con un período de alineación de una hora.

Si el selector de hora del gráfico se establece en una semana, el período del gráfico es de una hora, lo que se indica en un chip. Para la consulta de ejemplo, el período del grafo y el período de alineación son iguales. Cuando se ejecuta la consulta, se genera un gráfico similar al siguiente:

Por ejemplo, si cambias el período de alineación que se pasó a la operación every de 1h a 1m en la consulta anterior, la consulta produce un gráfico que incluye el mínimo y máximo bandas:

Las líneas del gráfico se representan con un período de grafo de una hora, según la selección de una semana para el gráfico, por lo que las líneas son las mismas que las del ejemplo anterior. Sin embargo, la consulta produce un punto cada minuto, por lo que las bandas de mínimo y máxima muestran el rango de valores de un minuto de la consulta que corresponden a cada punto del gráfico de una hora.

Si se omite la operación every, el período de alineación de consulta predeterminado es el valor de la ventana de alineación o, si no se especifica la ventana de alineación, un minuto.

Políticas de alertas basadas en MQL

También puedes usar MQL y el editor de código para crear consultas y usarlas en políticas de alertas.

Si deseas crear una política de alertas basada en MQL desde la consola de Google Cloud, sigue los pasos habituales para crear la política, que se describen en Administra políticas de alertas, pero, cuando creas la condición para la política de alertas, debes usar el editor de código en lugar del selector de métricas basadas en formularios.

Para obtener más información, consulta Crea políticas de alertas de MQL.

Conversión de consultas

Puedes usar el selector de métricas para gráficos o en el Explorador de métricas a fin de crear una consulta y, luego, convertirla en MQL. La consulta de MQL correspondiente se muestra en el editor.

Para convertir una consulta compilada en un menú en MQL, cuando uses el Explorador de métricas, haz lo siguiente:

1. En la barra de herramientas del panel del compilador de consultas, selecciona el botón cuyo nombre sea  MQL o  PromQL.
2. Verifica que MQL esté seleccionado en el botón de activación Idioma. El botón de activación del idioma está en la misma barra de herramientas que te permite dar formato a tu consulta.

Para convertir una consulta basada en formularios en MQL, haz clic en MQL cuando veas un gráfico en un panel.

Considera una solicitud muy simple, como “Obtener el uso de CPU de mis instancias de VM de Compute Engine”. Esta consulta implica el tipo de recurso supervisado gce_instance y el tipo de métrica compute.googleapis.com/instance/cpu/usage_time.

En la siguiente captura de pantalla, se muestra esta consulta en el selector de métricas basadas en formularios:

Los tipos de métricas y recursos supervisados se ingresaron de forma manual. Todos los demás campos tienen sus valores predeterminados.

En la siguiente captura de pantalla, se muestra el resultado de convertir la selección basada en el formulario en una consulta de MQL:

La consulta de MQL recupera las series temporales de los tipos de recursos y métrica especificados y realiza la alineación de tarifas en intervalos de 1 minuto. La consulta convertida está en formato strict.

Nota: No puedes convertir la representación de MQL de nuevo en la configuración en el selector de métricas basadas en formularios. MQL admite consultas que no puedes compilar con el selector de métricas. Cuando sales del editor de código, el texto de la consulta se descarta si no lo guardas.