Using PromQL

Notice

PromQL support is in Beta.

The Prometheus Query Language (PromQL) is the defacto standard for querying Prometheus metric data. PromQL is designed to allow the user to select and aggregate time-series data.

Sysdig Monitor's PromQL support includes all of the features, functions, and aggregations in standard open-source PromQL. The PromQL language is documented at Prometheus Query Basics.

Guidelines for Using PromQL

  • PromQL is in Beta. Contact Sysdig Support at beta@sysdig.com to enable PromQL in your environment.

  • The Advanced Query currently supports only running PromQL queries.

  • Only Prometheus metrics are currently available for executing PromQL queries.

  • Prometheus metrics currently appear with a prefix of promraw_.

Building Queries

You can filter Prometheus metrics and build dashboards only by using the Advanced Query mode. In Advanced Query mode, you directly execute a PromQL query. Use operators and functions to enable complex filtering.

Construct a PromQL Query

The Dashboard Panel helps you to construct PromQL queries in Advanced mode.

promQL_query.png

  • Display: Specify a meaningful display name for the legend. The text you enter replaces the metric name displayed in the legend. The default legend title is the metric name.

  • Query: Enter a PromQL query directly. For example:

    sum(rate(promraw_go_memstats_heap_released_bytes_total[5m])) by(kubernetes_cluster_name)

    In the construct you specify the following:

    • Metrics: Search the desired metric. The field supports auto-complete. Enter the text and the rest of the text you type is predicted so you can filter the metric easily. In the example: promraw_go_memstats_heap_released_bytes_total.

    • Segmentation: It is the process of categorizing aggregated data with labels in order to provide precise control over the data. Choose an appropriate value for segmenting the aggregated PromQL data. In this example, kubernetes_cluster_name.

    PromQL query field supports the following variables. Both the variables are replaced in the UI at runtime before issuing the data request to the Prometheus endpoints.

    • $__range: Replaced with the time range currently selected in the time navigation. In the Live mode, it gets constantly updated to reflect the new time range.

    • $__interval: Replaced with the time sampling, which in turn is based on the selected time range. What it implies that you do not directly control it. For example, when looking at the 1-hour of data, sampling will be one minute. Sampling is computed based on information published by the backend components about data rollup.

  • Unit and Y-Axes: Specify the unit of scale and display format.

  • Compare To: (Form-Based) Allows you to compare the current value to historical values. Not supported if Segmentation is specified.

  • Axes: Determine scale, unit, display format, and gauge for the Y-axes. See Configure New Dashboard for description.

  • Legend: Determine the position of the legend in the Dashboard. See Configure New Dashboard for description.

  • Panel: Specify a name and add details about the panel. See Configure New Dashboard for description.