Translate PromQL queries to NRQL

Are you familiar with PromQL or have a PromQL query you’d like to convert to NRQL? This document provides examples that show you how to convert some common PromQL queries to NRQL queries. You can use NRQL to simulate PromQL, and query your Prometheus OpenMetrics integration data with other data sent to New Relic.

Prometheus and New Relic metric types

The different metric types supported by Prometheus and New Relic are related to each other:

New Relic Prometheus Description
Count Counter

The Prometheus counter is a cumulative sum while the New Relic count is a delta sum.

For example, if you see 2 requests in the first reporting period and 3 requests in the second reporting period. The Prometheus counter will report 2 and then 5, while the New Relic count will report 2 and then 3.
Gauge Gauge A Prometheus gauge is similar to a New Relic gauge.
Multiple counts Histogram Prometheus automatically maps a histogram to a set of counters. In New Relic, these counters should be changed to deltas and reported as counts.
Gauges and counts Summary Prometheus automatically maps a summary to a set of counters and gauges. These can be translated to New Relic counts and gauges.
Summary (No equivalent in Prometheus) New Relic has a distinct metric type called a summary that is different than the Prometheus summary. It is designed for reporting aggregated discrete events so that you can query the count, sum, min, max, and average values.

Mapping between PromQL and NRQL

This table shows the mapping between PromQL and NRQL when exploring data. For more contextual information, see the examples.

Description Mapping between PromQL and NRQL

Search for attributes:

Explore the attributes on the container_memory_usage_bytes metric.

  • PromQL:

    container_memory_usage_bytes

  • NRQL:

    FROM Metric SELECT keyset() WHERE metricName = 'container_memory_usage_bytes'

Find attribute's value:

Explore the current value of the container_memory_usage_bytes metric for unique id attributes.

  • PromQL:

    sum(container_memory_usage_bytes) by (id)

  • NRQL:

    FROM Metric SELECT latest(container_memory_usage_bytes) FACET id

Visualize the attribute's value:

Chart the value of the container_memory_usage_bytes metric with the given id attribute value.

  • PromQL:

    container_memory_usage_bytes{id="/"}

  • NRQL:

    FROM Metric SELECT latest(container_memory_usage_bytes) WHERE id = '/' TIMESERIES
PromQL query example

1. Start your query.

When exploring your data for a particular metric in PromQL, such as memory by container usage in bytes, you can start with a query such as:

container_memory_usage_bytes

This will chart all the unique metric timeseries for the input metric.

2. Filter the query results.

Looking at the data, you can add more query parameters to filter down the number of metric timeseries. For example, if you only want timeseries where the id is /, the PromQL query will be:

container_memory_usage_bytes{id="/"}
a query using PromQL
PromQL example: To filter the data, run this PromQL query: container_memory_usage_bytes{id="/"}.
NRQL query example

1. Query available metrics.

To explore your data, start by looking at all the available metrics. Use the following NRQL query:

FROM Metric SELECT uniques(metricName)

2. Find unique attributes.

Once you have found the metric you want to review, such as container_memory_usage_bytes, you can find the unique attributes with the following query:

FROM Metric SELECT keyset() WHERE metricName = 'container_memory_usage_bytes'

The results will show each available attribute key and the value type (string, boolean, or number).

3. Aggregate and chart the metrics.

To chart metrics using NRQL, you first need an aggregation function. For example, you can use latest for gauges, sum for counts, and average for summaries.

As the following chart shows, all the unique timeseries are aggregated into one unique timeseries by default:

NRQL-example-3.png
one.newrelic.com > Chart builder: This example shows the data you see after running FROM Metric SELECT keyset() WHERE metricName = 'container_memory_usage_bytes'.

4. View metrics by ID.

To view the unique metric timeseries with various id values, run the following query:

FROM Metric SELECT latest(container_memory_usage_bytes) FACET id
NRQL-query-example-4.png
one.newrelic.com > Chart builder: This example shows the data you see after running FROM Metric SELECT latest(container_memory_usage_bytes) FACET id.

5. Add the selected ID to the query.

Next you can select an id value and put it in the NRQL where clause.

FROM Metric SELECT latest(container_memory_usage_bytes) WHERE id = "/" timeseries
NRQL-query-example-5.png
one.newrelic.com > Chart builder: This example shows the data displayed after running From Metric select latest(container_memory_usage_bytes) where id = "/" timeseries.

Filter examples

Both PromQL and NRQL provide syntax to filter down the number of unique metric timeseries.

  • PromQL uses brackets to filter.
  • NRQL uses a WHERE clause.

Here are some example queries:

Description PromQL and NRQL queries

Select data with specific values.

  • PromQL:

    go_memstats_heap_alloc_bytes{job="apiserver", instance="1234"})

  • NRQL:

    To only select data with specific values in NRQL, use the WHERE clause with =. In this example, all data must have the selected value for job and handler.

    FROM Metric SELECT latest(go_memstats_heap_alloc_bytes) WHERE job = 'apiserver' AND instance = '1234' TIMESERIES

Select data with multiple values.

  • PromQL:

    go_memstats_heap_alloc_bytes{environment=~"staging|testing|development",method!="GET"}

  • NRQL:

    In NRQL use the in clause to select multiple values for an attribute and the != sign to select all values but the one listed. In this example, the environment can be staging, testing, or development, and the method cannot be GET.

    FROM Metric SELECT latest(go_memstats_heap_alloc_bytes) WHERE environment IN ('staging', 'testing', 'development') AND method != 'GET' TIMESERIES

Select data using partial string values.

  • PromQL:

    go_memstats_heap_alloc_bytes{job=~"api.*"}

  • NRQL:

    In NRQL use the LIKE clause to match part of a string value. In this example, all data will be returned where the job attributes start with api.

    FROM Metric SELECT latest(go_memstats_heap_alloc_bytes) WHEREe job LIKE 'api%' TIMESERIES

PromQL to NRQL query examples

You can simulate the following PromQL queries with NRQL queries:

Description PromQL and NRQL queries
Measure the per minute rate of the http_request_total metric.

  • PromQL:

    sum(rate(http_requests_total[1m]))

  • NRQL:

    FROM Metric SELECT rate(sum(http_request_total), 1 minute) TIMESERIES
Chart the difference of the two metrics, then divide by 1024.

  • PromQL:

    (instance_memory_limit_bytes - instance_memory_usage_bytes) / 1024

  • NRQL:

    FROM Metric SELECT (latest(instance_memory_limit_bytes) - latest(instance_memory_usage_bytes)) / 1024 TIMESERIES
Provide the summed rate per 30-second interval by each handler.

  • PromQL:

    sum(rate(http_requests_total[30s])) by (handler)

  • NRQL:

    FROM Metric SELECT rate(sum(http_requests_total), 30 seconds) FACET handler TIMESERIES
Chart the difference in the two metrics where the instance is named foo and the fstype is either ext4 or xfs.

  • PromQL:

    (node_filesystem_free_bytes{instance='foo',fstype=~"ext4|xfs"} / node_filesystem_size_bytes{instance='foo',fstype=~"ext4|xfs"})

  • NRQL:

    FROM Metric SELECTt latest(node_filesystem_free_bytes) / latest(node_filesystem_size_bytes) WHERE instance = 'foo' AND fstype IN ('ext4', 'xfs')

For more help

Recommendations for learning more:

  • Browse New Relic's Explorers Hub for community discussions about New Relic's APIs.
  • Use your preferred search engine to find other New Relic resources.