Create alert conditions for NRQL queries

With New Relic Alerts, you can create alert conditions using Insights NRQL queries.

Create NRQL alert condition

To create a NRQL alert condition: When you start to create an alert condition, select NRQL as the product category.

NRQL conditions Tips
Condition types

NRQL condition types include static, baseline, and outlier.

Query results Queries must return a number. The alert condition works by evaluating that returned number against the thresholds you set.
Time period

As with all alert conditions, NRQL alert conditions evaluate one single minute at a time. The implicit SINCE ... UNTIL clause specifying which minute to evaluate is controlled by your Evaluation offset setting. Since very recent data may be incomplete, you may want to query data from 3 minutes ago or longer, especially for:

  • Applications that run on multiple hosts.

  • SyntheticCheck data: Timeouts can take 3 minutes, so 5 minutes or more is recommended.

Also, if a query will generate intermittent data, consider using the sum of query results option.

Condition settings

Use the Condition settings to:

Troubleshooting procedures

Optional: To include your organization's procedures for handling the incident, add the runbook URL to the condition.

Limits on conditions See the maximum values.

For more information, see:

Alert threshold types

When you create a NRQL alert, you can choose from different types of thresholds:

NRQL alert threshold types Description

This is the simplest type of NRQL threshold. It allows you to create a condition based on a NRQL query that returns a numeric value.

Optional: Include a FACET clause.

Baseline Uses a self-adjusting condition based on the past behavior of the monitored values. Uses the same NRQL query form as the static type, except you cannot use a FACET clause.
Outlier Looks for group behavior and values that are outliers from those groups. Uses the same NRQL query form as the static type, but requires a FACET clause.

NRQL alert syntax

Here is the basic syntax for creating all NRQL alert conditions. Depending on the threshold type, also include a FACET clause as applicable.

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

SELECT function(attribute)


Supported functions that return numbers include:

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

If you use the percentile aggregator in a faceted alert condition with many facets, this may cause the following error to appear:

An error occurred while fetching chart data.

If you see this error, use average instead.

FROM Event


Only one event can be targeted.

Use of the Metric event type is prohibited.

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


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

FACET attribute

  • Static: Optional
  • Baseline: Not allowed
  • Outlier: Required

Including a FACET clause in your NRQL syntax depends on the threshold type: static, baseline, or outlier.

Use the FACET clause to separate your results by attribute and alert on each attribute independently. Faceted queries can return a maximum of 5000 values for static conditions and a maximum of 500 values for outlier conditions.

If the query returns more than this number of values, the alert condition cannot be created. If you create the condition and the query returns more than this number later, the alert will fail.

Sum of query results (limited or intermittent data)

Available only for static (basic) threshold type.

If a query returns intermittent or limited data, it may be difficult to set a meaningful threshold. This is because the missing or limited data will sometimes generate false positives or false negatives.

To avoid this problem when using the static threshold type, you can set the When the selector to sum of query results. This lets you set the alert on an aggregated sum instead of a value from a single harvest cycle. Up to two hours of the one-minute data checks can be aggregated. 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, we evaluate the NRQL query in one-minute time windows. The start time depends on the value you select in the NRQL condition's Advanced settings > Evaluation offset.

Example: Using the default time window to evaluate violations

With the Evaluation offset at the default setting of three minutes, the NRQL time window applied to your query will be:

SINCE 3 minutes ago UNTIL 2 minutes ago

If the event type is sourced from an APM language agent and aggregated from many app instances (for example, Transactions, TransactionErrors, etc.), we recommend evaluating data from three minutes ago or longer. An offset of less than 3 minutes will trigger violations sooner, but you might see more false positives and negatives due to data latency.

For cloud data, such as AWS integrations, you may need an offset longer than 3 minutes. Check our AWS polling intervals documentation to determine your best setting.

NRQL alert threshold examples

Here are some common use cases for NRQL alert conditions. These queries will work for static and baseline threshold types. The outlier threshold type will require additional FACET clauses.

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, 95) 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. Since we evaluate the NRQL query in one-minute time windows, percentiles will be calculated for each minute separately.

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: