Create alert conditions for NRQL queries

New Relic Insights allows you to create NRQL queries with SQL-style syntax to analyze and visualize your event data. Use New Relic Alerts to monitor basic Insights NRQL queries that return a number. There is a maximum limit of 2000 NRQL conditions per account.

Supported NRQL syntax

Here is the basic syntax and supported functions for basic NRQL queries that return a number.

SELECT function(attribute)
FROM Event
WHERE attribute [comparison] [AND|OR ...]
Clause Notes

SELECT function(attribute)

Required. Supported functions that return numbers include:

  • apdex
  • average
  • count
  • latest
  • max
  • min
  • percentage
  • percentile
  • sum
  • uniqueCount

FROM Event

Required. Only one event can be targeted.

WHERE attribute [comparison] [AND|OR ...]

Optional. Use the WHERE clause to specify a series of one or more conditions. All the operators are supported.

FACET attribute

Optional. Use the FACET clause to separate your results by attribute, and alert on each attribute independently. Queries with up to 150 entities are supported using faceting.

Once an Alert condition with the NRQL FACET query is saved, the entity count for the NRQL FACET attribute can grow above the initial 150 limit. However, Alerts will not evaluate more than 250 entities, total, for any single NRQL query. If the entity count grows above 250, the results are indeterminate.

Create NRQL alert condition

NRQL alerts are not supported or recommended for AWS integrations and other cloud integrations, due to service data latency issues. Instead, consider using Infrastructure alerting.

You can create a maximum of 2000 NRQL conditions per account. To create an alert condition for a NRQL query, follow the basic workflow process to set up a policy. In addition:

  1. When creating a condition, select NRQL as the product target.
  2. Select Query or Baseline query as the type of condition.
  3. Create a basic NRQL query that returns a number.
  4. Optional: To set a threshold on a value with sparse metrics or random gaps, select sum of query results.
  5. Define the thresholds. Recommendation: Select query data from three minutes ago or longer, especially if your app runs on multiple hosts.
  6. Optional: To adjust the time frame used to evaluate data from Insights, select Advanced settings > Evaluation offset.
  7. Give your condition a concise and descriptive name.
  8. Continue the rest of the policy workflow process.

The preview chart shows an example of your condition settings.

Use sum of query results

If you have a key performance indicator (KPI) with intermittent or limited data, normally it could be difficult to set a meaningful threshold. This is because false positives or false negatives could result from the one-minute time frame used to check data against the threshold setting.

To avoid this problem, select the sum of query results option to update the time series preview in the NRQL condition. This allows you to set thresholds on rolling sums more easily. New Relic Alerts holds up to two hours of the one-minute data checks. The duration you select determines the width of the rolling sum, and the preview chart will update accordingly.

Offset the query time window

Every minute New Relic Alerts evaluates the NRQL query in one-minute time windows. The start time depends on the value you select in the Evaluate query data from X min ago threshold setting. For example:

Threshold setting

Evaluate query from 3 mins ago

NRQL time window applied to your query

SINCE 3 min ago UNTIL 2 min ago

If the event type is sourced from a New Relic language agent and aggregated from many app instances (for example, Transactions, TransactionErrors, etc.), New Relic recommends evaluating data from three minutes ago or longer. If you do not offset the time window by at least three minutes, violations will trigger sooner, but they may also increase the number of false positives.

Custom event types are less affected by the agent harvest cycle. They are more effectively evaluated every minute.


Here are some common use cases for NRQL alerting.

Alert on specific segments of your data

Create constrained alerts that target a specific segment of your data, such as a few key customers or a range of data. Use the WHERE clause to define those conditions.

SELECT average(duration) FROM Transaction WHERE account_id in (91290, 102021, 20230)
SELECT percentile(duration, 75) FROM Transaction WHERE name LIKE 'Controller/checkout/%'
Alert on Nth percentile of your data

Create alerts when an Nth percentile of your data hits a specified threshold; for example, maintaining SLA service levels.

SELECT percentile(duration, 95) FROM Transaction
SELECT percentile(databaseDuration, 75) FROM Transaction
Alert on max, min, avg of your data

Create alerts when your data hits a certain maximum, minimum, or average; for example, ensuring that a duration or response time does not pass a certain threshold.

SELECT max(duration) FROM Transaction
SELECT average(duration) FROM Transaction
Alert on a percentage of your data

Create alerts when a proportion of your data goes above or below a certain threshold.

SELECT percentage(count(*), WHERE duration > 2) FROM Transaction
SELECT percentage(count(*), WHERE httpResponseCode = '500') FROM Transaction
Alert on Apdex with any T-value

Create alerts on Apdex, applying your own T-value for certain transactions. For example, get an alert notification when your Apdex for a T-value of 500ms on transactions for production apps goes below 0.8.

SELECT apdex(duration, t:0.5) FROM Transaction WHERE appName like '%prod%'

For more help

Recommendations for learning more: