IBM Cloud Docs
Utilización de PromQL

Utilización de PromQL

Utilice el lenguaje de consulta de Prometheus (PromQL) para seleccionar y agregar datos de métricas de series temporales para Prometheus.

Para obtener más información sobre PromQL, consulte la documentación de código abierto.

Creación de una consulta PromQL

Para crear una consulta de PromQL para una métrica en un panel de control existente.

  1. En el panel de control de supervisión, pulse Abrir panel de control para la instancia de servicio.
  2. En Paneles de control, seleccione el panel de control que contiene las métricas que desea consultar.
  3. Para un panel del panel de control, pulse el icono Editar.
  4. Seleccione el tipo de consulta PromQL.
  5. En el formulario de consulta, especifique los datos de Visualización, por ejemplo, el nombre de consulta y el nombre de la serie temporal.
  6. Especifique la Consulta de PromQL, por ejemplo, avg(avg_over_time(host_cpu_used_percent[$__interval])) by(kubernetes_cluster_name). Especifique los siguientes campos en la consulta:
    • Métrica: Especifique la métrica que desea consultar, como por ejemplo host_cpu_used_percent. Nota: los valores generados en la tabla son la métrica más reciente.
    • Rango de tiempo: especifique un rango o un intervalo de tiempo, como por ejemplo 5m. Para utilizar el rango de tiempo seleccionado en la interfaz de usuario, especifique $__range. Para utilizar el intervalo de tiempo que se basa en el rango de tiempo seleccionado en la interfaz de usuario, especifique $__interval. Las variables $__range y $__interval de esta consulta se actualizan automáticamente cuando se cambia el rango de tiempo en la interfaz de usuario. Para obtener más información, consulte Aplicación de los ámbitos del panel de control a las consultas PromQL.
    • Segmentación: elija un valor para segmentar los datos agregados de PromQL, como por ejemplo kubernetes_cluster_name.
  7. Pulse Ejecutar consulta.
  8. Ajuste los resultados configurando las Opciones adicionales, por ejemplo, las unidades en las que se devuelven los datos y cómo se visualizan los datos.

Aplicación de ámbitos de panel de control

Para delimitar el ámbito un panel creado a partir de una consulta PromQL, debe utilizar una variable de ámbito dentro de la consulta.

Hay dos variables predefinidas para los ámbitos basados en el tiempo que puede especificar en la consulta. Estas variables se actualizan automáticamente cuando se cambia el rango de tiempo en la interfaz de usuario.

  • $__range: representa el marco de tiempo seleccionado en la interfaz de usuario del panel de control. Por ejemplo, puede utilizar esta variable para calcular un promedio del marco de tiempo seleccionado.
  • $__interval: representa el intervalo que se basa en el rango de tiempo seleccionado en la interfaz de usuario del panel de control. Por ejemplo, puede utilizar esta variable para adaptar el rango de tiempo para diferentes operaciones, como la tasa o el valor medio a lo largo del tiempo.

Por ejemplo, supongamos que utiliza la siguiente consulta para obtener el porcentaje de uso de CPU de todos los hosts:

avg_over_time(host_cpu_used_percent[$__interval])

Esta consulta utiliza la variable $__interval, que delimita los datos al intervalo de tiempo dinámico basado en el rango de tiempo seleccionado en la interfaz de usuario del panel de control.

También puede especificar sus propias variables en la consulta para delimitar su salida. Por ejemplo, para ampliar el ámbito de la consulta anterior a una etiqueta específica como, por ejemplo, hostname, primero debe definir una variable de ámbito en el nivel del panel de control. A continuación, puede especificar esa variable en la consulta:

avg_over_time(host_cpu_used_percent{host_name=$hostname}[$__interval])

Utilización de etiquetas

Al ejecutar consultas PromQL, los datos se devuelven con un conjunto mínimo de etiquetas. Para añadir más etiquetas, como por ejemplo un nombre de clúster, utilice una operación de coincidencia de vector.

Prometheus devuelve métricas de información que tienen un valor 1 con varias etiquetas. La unión de las etiquetas de una métrica de información con una métrica de no información puede proporcionar información útil como, por ejemplo, el valor de una métrica en una aplicación. Puede utilizar una operación de coincidencia de vector, que es similar a una unión SQL, para añadir las etiquetas de información a los datos de métricas.

Ejemplo: Filtrado de una métrica de aplicación por clúster

En este ejemplo, una métrica que devuelve una aplicación se filtra por clúster. PromQL agrega un valor de esa métrica para un clúster teniendo solo un clúster seleccionado en el ámbito.

sum (myapp_metric * on (container_id) kube_pod_container_info{cluster=$cluster})

Esta consulta:

  • Filtra la métrica de información kube_pod_container_info solo para un clúster específico ($cluster, que se establece como una variable de panel de control) en base a la etiqueta cluster y para una determinada serie temporal.
  • La métrica de no información myapp_metric coincide con la métrica de información filtrada kube_pod_container_info cuando la etiqueta container_id tiene el mismo valor. Los valores se multiplican, pero debido a que la métrica de información tiene un valor de 1, el resultado no se modifica. La etiqueta del clúster se añade a los datos resultantes.
  • Agrega la serie temporal con el valor myapp_metric utilizando la función sum y devuelve el resultado.

Ejemplo: Filtrado del valor medio de CPU utilizada por cuenta y región

En este ejemplo, se calcula el promedio de CPU utilizada (en porcentaje) para una cuenta y región específicas de IBM Cloud.

avg by(region,account_id) (host_cpu_used_percent * on (host_mac) group_left(region,account_id) sysdig_cloud_provider_info{account_id=~$account, region=~$region})

Esta consulta:

  • Filtra la métrica de información sysdig_cloud_provider_info solo para una región específica ($region) y una cuenta específica ($account) que se establecen como variables de panel de control basadas en las etiquetas region y account_id.
  • La métrica de no información host_cpu_used_percent coincide con la métrica de información filtrada sysdig_cloud_provider_info cuando la etiqueta host_mac tiene el mismo valor. Los valores se multiplican, pero debido a que la métrica de información tiene un valor de 1, el resultado no se modifica. Las etiquetas de región y cuenta se añaden a los datos resultantes.
  • Calcula el valor medio de las nuevas métricas por cuenta y región.

Ejemplo de cURL para extraer la métrica más reciente

Para obtener el último valor de una métrica, especifique solo el nombre de la métrica. Se devuelve el valor más reciente que se ha generado no hace más de 5 minutos.

Por ejemplo, para obtener el último valor de host_cpu_used_percent:

curl <SYSDIG_REST_API_ENDPOINT>/prometheus/api/v1/query?query=sysdig_host_cpu_used_percent -H "Authorization: $AUTH_TOKEN" -H "IBMInstanceID: $GUID" -H "SysdigTeamID: $TEAM_ID" -H "content-type: application/json"

Donde

  • <SYSDIG_REST_API_ENDPOINT> indica el punto final al que se dirige la llamada de API REST. Para obtener más información, consulte Puntos finales de API REST de supervisión. Por ejemplo, el punto final público de una instancia que está disponible en us-south es el siguiente: https://us-south.monitoring.cloud.ibm.com/api

  • Puede pasar varias cabeceras utilizando -H.

    Authorization e IBMInstanceID son cabeceras necesarias para la autenticación.

    SysdigTeamID es opcional. Al especificar esta cabecera, se limita la solicitud a los datos y los recursos disponibles para el equipo especificado.

    Para obtener una AUTH_TOKEN y el GUID consulte, Cabeceras para señales IAM.

Todos los paneles de control admiten la API completa de PromQL. Para obtener más información sobre lo que es posible con PromQL, consulte la documentación dePrometheus.