Create NRQL alert conditions

You can create alert conditions using NRQL queries.

Create NRQL alert condition

To create a NRQL alert condition: When you start to create a condition, where it prompts you to Select a product, click NRQL.

Tips for creating and using a NRQL condition:

Topic Tips
Condition types

NRQL condition types include static, baseline, and outlier.

Create a description

For some condition types, you can create a Description.

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

As with all alert conditions, NRQL 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:

  • Configure whether and how open violations are force-closed.
  • Adjust the evaluation offset.
  • Create a concise and descriptive condition name.
  • (NerdGraph API Only) Provide a text description for the condition that will be included in violations and notifications.
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.
Health status NRQL alert conditions do not affect an entity's health status display.

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 data type


Only one data type can be targeted.

Supported data types:

  • Event
  • Metric (RAW data points will be returned)

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

If a query returns intermittent or limited data, it may be difficult to set a meaningful threshold. 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 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%'

Create a description

You can define a description that passes useful information downstream for better violation responses or for use by downstream systems. For details, see Description.

For more help

If you need more help, check out these support and learning resources: