Run PromQL queries in the Wavefront Query Editor

Wavefront supports both PromQL and WQL (Wavefront Query Language) queries. The Query Editor includes admin-level organization settings for enabling PromQL and a query line GUI that includes a translation option.

  • Administrators have control over user defaults:
    • On the Organization Settings page (New User Defaults) administrators can enable users to write queries in PromQL.
    • If queries in PromQL are enabled, administrators can also set other options.
  • Users can then type PromQL or Wavefront query language (WQL) queries into the Query Editor.
    • If users enter a PromQL query when PromQL is selected, or a Wavefront query language query, when WQL is selected, the Query Editor parses the query. The corresponding chart shows the information you’d expect.
    • If users enter a PromQL query when WQL is selected, or the reverse, the Query Editor doesn’t parse the query and displays a syntax error.
    • In PromQL mode, users can see the translation to Wavefront query language and translate the query if that is set in their preferences.
    • Users can add charts that use PromQL to dashboards, create alerts from charts that use PromQL, and use PromQL queries in the query line of a Create Alert page.

Set PromQL Organization Settings (Administrator Only)

Users with Accounts, Groups & Roles permissions can navigate to the Organization Settings and enable the PromQL support.

  • If PromQL Support is not enabled, other users cannot use PromQL or change PromQL user preferences.
  • If PromQL Support is enabled, administrators can set additional New User Default query settings, and other users can override those settings.

To set PromQL settings for your organization:

  1. From the gear icon, select Organization Settings.
  2. Under Query Settings, select the Users can write queries in PromQL check box.
  3. Select the default query language for new users.
  4. Select the default way for building queries.

    If the default language is set to PromQL, the only way to build queries is to use the Query Editor.

  5. Enable Show WQL translation to show the translation for all PromQL queries.

    Select this check box if you expect that users want to learn Wavefront query language. The translation appears only if the query is with a valid PromQL syntax. Otherwise, you see an error.

Set PromQL User Preferences (All Users)

If an administrator has enabled PromQL support (discussed above), each user can control some aspects of PromQL.

  1. From the gear icon, select your username.
  2. Under Query Settings, select:
    • The default query language.
    • The default way of building queries.

      If your default language is set to PromQL, you can build your queries only in the Query Editor. Chart Builder was designed for Wavefront query language and doesn’t support PromQL.

    • Whether to show the translation to Wavefront query language when you click inside the Query Editor.

Video: Wavefront and PromQL

This short video shows how you can create a PromQL chart and an alert:

Use PromQL in Charts and Alerts

This example shows how to use PromQL, when:

  • An administrator has enabled PromQL support.
  • The default query language is set to be Wavefront query language.
  • The translation to Wavefront query language is enabled.

Query settings when PromQL is enabled, WQL is the default language and translation to WQL is also available.

If your preferred default language is PromQL, and you have selected to not see the translation to Wavefront query language, the button for converting to Wavefront query language is not available.

  1. Create or edit a chart or alert.
  2. Enter a PromQL query in the Query Editor.
  3. Click inside the Query Editor to see the translation to Wavefront query language.
  4. Finally, click the Convert to WQL button to convert to Wavefront query language if that's your primary mode. The query is translated to Wavefront query language. A small number of PromQL constructs are not supported, as discussed below.
query line in PromQL, with hover text that tells you can't switch the language without clearing the query

Button to convert to WQL.

Next, you can make changes to the visualization.

Prometheus query

Frequently Asked Questions

Wavefront supports most PromQL functions and operators out of the box. There are a small number of differences and best practices.

FAQ: Do You Have Best Practices?

A few functions work differently in PromQL and Wavefront QL. Here are some best practices.

rate() If you use the PromQL rate() function on an instant vector in Wavefront UI provide the time resolution.
where x is time span length, y is the resolution, m is the time unit minute.

If you include the time resolution, Wavefront will automatically call align() on the translated query. If you don't include the time resolution, you might get different results depending on the monitor resolution. See Chart Resolution for details on how your monitor's resolution can affect how the chart looks.
count_values() The PromQL count_values aggregation function is not supported. Wavefront histograms and histogram functions allow you to perform the corresponding tasks -- and more!
topk(), bottomk() The topk() and bottomk() functions work slightly differently in PromQL and Wavefront query language.
  • PromQL computes topk() and bottomk() at the point level. It picks the top points at each timestamp.
  • Wavefront computes topk() and bottomk() at time series level. It returns the top or bottom series (based on the avg/min/max... value).

In the Wavefront Query Editor, topk() and bottomk() always return results based on the time series.

FAQ: Can I Use Variables in Wavefront?

Dashboard variables are a powerful feature in Wavefront.

  • Wavefront users with Dashboard permissions can create dashboard variables.
  • All Wavefront users can select dashboard variable values at the top of dashboards, and can specify variables inside a query. When Wavefront runs the query, it automatically substitutes the current value of the variable with the selected value for the dashboard.

This approach to variables is different from PromQL variables.

  • If the dashboard variable represents the actual value (or glob), use =.
  • In the rare case that you want to explicitly use a regex, use =~

FAQ: Can You Show Me a Query Example That Doesn’t Translate?

In many cases the translation from PromQL to WQL is straightforward. You type the PromQL query into the query editor and click WQL to see the corresponding query in WQL.

However, the syntax for for joining queries in PromQL and in WQL is fundamentally different. In addition, Wavefront does not support the use of ignore, on, group_left, and group_right for vector matching with PromQL queries. However, after a bit of practice (and after looking at our examples and this video) we expect you’ll find joins in WQL quite powerful.

Joining Queries in WQL and PromQL

Wavefront query language has several options for combining time series with joins. Here’s a summary of the syntax:

join(<<WQUERY1>>  AS ts1
<<WQUERY2>> AS ts2
metric='<<NEW METRIC NAME>>',
ts1 (edited)

In <<HOW TO JOIN METRICS>>, you specify the new output metric, the source you want to focus on, point tags in the output, and the value you want to use, as in this example:

metric='cf_app_memory_used_gb',               //New output metric name.
source=ts2.application_name,                  //What do you want to use as source.
<<OUTPUT COLUMNS>>,                           //Source and point tags in output.
ts1                                           //What value do you want to use as value

In PromQL, you specify Query 1, how to join the metrics, the output colums, and Query 2, as follows:

(<<QUERY1>> + on(<<HOW TO JOIN METRICS>>) group_left(<<OUTPUT COLUMNS>>) (<<QUERY2>>)

This section shows an example for how 2 queries can be combined with joins in WQL and PromQL.

Example Join in WQL

The following example joins two Wavefront queries (WQL 1 and WQL 2) using an inner join.

WQL 1:

ts(kubernetes.pod_container.status, cluster="a-cluster" and nodename="ip-*" and pod_name="a-pod" and namespace_name="a-namespace" and status="running")

WQL 2:

ts(kubernetes.pod_container.uptime, cluster="a-cluster" and nodename="ip-*" and pod_name="a-pod" and namespace_name="a-namespace")

WQL Join:

join(${WQL Q1} AS ts1 INNER JOIN ${WQL Q2} AS ts2 USING( cluster, nodename, pod_name, namespace_name ), metric='pods.running.uptime', source=ts2.source, cluster=ts1.cluster, nodename=ts1.nodename, pod_name=ts1.pod_name, namespace_name=ts1.namespace_name,  ts2)

See Inner Join Example for a discussion.

Example Join in PromQL

The following example joins two PromQL queries (PromQL 1 and PromQL 2).

PromQL 1:

kubernetes.pod_container.status{cluster="a-cluster",nodename="ip-*", pod_name="a-pod", namespace_name="a-namespace", status="running"}

PromQL 2:

kubernetes.pod_container.uptime{cluster="a-cluster",nodename="ip-*", pod_name="a-pod", namespace_name="a-namespace"} 

PromQL Join:

${PromQL Q1} * on(cluster,nodename,pod_name,namespace_name) group_left(status) ${PromQL Q2}

FAQ: Does Wavefront Have Recording Rules?

For expressions that are needed frequently or computationally expensive, PromQL supports creating recording rules, which allow you to save the expression result as a set of time series. The Wavefront derived metrics feature is similar.

It’s not currently possible to translate a query that includes recording rules. However, advanced PromQL users can:

  1. Break down their PromQL query into small-ish pieces.
  2. Use the Query Editor translation feature for each piece.
  3. Create a derived metric for one or more of the short queries.


Because the two languages are different, some limitations exist.

Unsupported PromQL Functions

sort(), sort_desc() PromQL sort() and sort_desc() show the data order in the Console view. Because Wavefront visualizes queries in charts instead of a console, we don't support this option.
ignore, on, group_left, group_right Wavefront does not support ignore, on, group_left, group_right for vector matching with Prometheus queries.

Limitations in Wavefront Query Editor

  • Autocomplete is not currently supported for PromQL functions and operators. However, autocomplete for metrics that you use inside your query continues to be supported.
  • The Wavefront query language supports using a query name as a chart variable in other queries for the same chart.
    • You can use a query name as a chart variable in a PromQL query if the named query was also a PromQL query.
    • You cannot use a query name as a chart variable if the named query is a Wavefront QL query.

How Wavefront Executes PromQL Queries

The following diagram shows how Wavefront handles a Wavefront QL (ts()) query and a PromQL query.

Image showing Wavefront query language (ts) and PromQL execution paths, explained in the text below

The top row shows the ts() query execution:

  1. The user enters the query into the Query Editor.
  2. The Wavefront service processes the query and shows the results in the chart. It also uses the result to determine whether an alert should fire, etc.

The bottom row shows the PromQL query execution:

  1. The user enters the query into the Query Editor.
  2. The translation service translates the query into the corresponding ts() query.
  3. The translated query is automatically sent to the Wavefront service.
  4. The Wavefront service processes the query and shows the results in the chart. It also uses the result to determine whether an alert should fire, etc.

More Info

New to Wavefront? Here are some links to get you started: