Create alert conditions for NRQL queries

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

New Relic does not support or recommend using NRQL alerts for New Relic Infrastructure cloud integrations, due to service data latency issues. Instead, consider using Infrastructure alerting.

Create NRQL alert condition

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 category.
  2. Create a NRQL query based on the type of threshold you select: static, baseline, or outlier.
  3. Define the thresholds.

  4. Use the Conditions settings section to identify when New Relic Alerts will close the open violations, to adjust the time frame used to evaluate data from Insights with Advanced settings, and to create a concise and descriptive condition name.
  5. Optional: Include the runbook URL so that personnel responsible for the alert notification can follow standard procedures to manage the alert efficiently.
  6. Continue the rest of the policy workflow process.

The preview chart in the UI shows an example of your NRQL condition settings. Use it to adjust the thresholds as needed, then save your changes.

For NRQL query condition limits, see Alerts maximum values.

Queries used in NRQL alert conditions must result in a number. The number returned by the query is evaluated against the threshold.

Alert threshold types

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

NRQL alert threshold types Description
Static (basic type of alert threshold) Allows you to create a condition based on a NRQL query that returns a number or set of numbers. 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. Use 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)

Required. 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

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

Including a FACET clause in your NRQL syntax depends on the threshold type:

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

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

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. 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 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 min ago UNTIL 2 min ago

If the event type is sourced from a New Relic APM language agent and aggregated from many app instances (for example, Transactions, TransactionErrors, etc.), New Relic recommends 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, 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: