How to Create NRQL Alert Conditions in New Relic

Last verified: September 10, 2026
By: PerfMonitoring

A New Relic NRQL alert condition turns a numeric query result into a continuously evaluated signal. The most important step happens before you configure the threshold: prove that the NRQL query returns the right data for the right entity. New Relic's current alerting documentation explicitly recommends running the query in the NRQL builder to verify that the condition receives valid data. [1]

This tutorial builds a simple application-latency alert from Transaction data. The exact threshold is intentionally not prescribed as a universal number. Your threshold should reflect the service's normal behavior, user impact, and the response action your team can take.

What You'll Accomplish

You will:

1. write and validate a numeric NRQL query before alerting on it;
2. create a NRQL alert condition using the current New Relic alert flow;
3. choose between static and anomaly threshold models;
4. understand aggregation windows, evaluation duration, and delayed data;
5. configure loss-of-signal behavior deliberately;
6. attach the condition to an alert policy and notification workflow; and
7. verify the condition without causing a real production outage.

Prerequisites

You need:

• a New Relic account with permission to create or edit alert conditions;
• an application or other entity already sending fresh telemetry;
• a specific operational question you want the alert to answer;
• a known NRQL data type and attribute for that signal; and
• an alert policy/workflow appropriate for testing.

If you have not yet instrumented your service, complete the companion New Relic Node.js APM tutorial first. Alerting on an empty or unreliable telemetry stream creates more confusion than protection.

Quick Answer

Start in New Relic's query builder and validate a numeric NRQL query such as SELECT average(duration) FROM Transaction WHERE appName = 'checkout-api'. Then create a new alert condition, choose Write your own query, reuse the validated NRQL, configure the signal/aggregation behavior, set a static or anomaly threshold, and attach the condition to the correct policy. Before enabling paging, verify that the condition is receiving data and use a safe threshold or controlled test to observe the expected alert-state transition. [1][2]

Step 1: Define One Operational Question

A useful alert begins with a question that has an actionable answer. For example:

Is sustained transaction latency for the checkout API high enough that an operator should investigate?

That is more useful than “alert me when anything changes.”

For a service named checkout-api, a simple starting query is:

SELECT average(duration)
FROM Transaction
WHERE appName = 'checkout-api'

New Relic's current NRQL alert syntax requires a numeric function in the SELECT clause. Supported examples include average, count, max, min, percentage, percentile, sum, and others documented by New Relic. [2]

Run the query interactively before you create the condition. Confirm that:

• it returns a number;
• it returns data for the intended service;
• the time series behaves as expected during known traffic; and
• the query is not accidentally mixing staging and production.

If the query is wrong, no alert setting can make the condition correct.

Step 2: Avoid Unnecessary FACET Cardinality

You can add FACET to create a separate signal per attribute value, but that is not automatically better. New Relic's current NRQL alert documentation allows faceted alert conditions and documents a maximum of 20,000 facet values for static and anomaly conditions. If the query exceeds the supported number of facets, the condition can fail. [2]

For a first service alert, a WHERE appName = ... filter is easier to reason about than a high-cardinality FACET across every endpoint, host, customer, or request identifier.

Use a facet only when each facet genuinely needs its own independent alert state and you know the cardinality is controlled.

Step 3: Create the NRQL Alert Condition

New Relic's current docs show alert creation through several starting points, including a chart, a policy page, and alert builders. For a transparent tutorial, use the Write your own query path. [2]

A current navigation path documented by New Relic is:

1. open one.newrelic.com;
2. go to Alerts;
3. open Alert conditions (policies) or the current equivalent alert-conditions view;
4. choose New alert condition; and
5. use the NRQL/query builder path. [1][3]

Interface labels can evolve. The durable goal is to create a NRQL alert condition, not to reproduce an old screenshot pixel-for-pixel.

Paste the already-tested query into the condition rather than rewriting it from memory.

Step 4: Configure the Signal Behavior

The alert condition continuously evaluates a stream derived from your query. New Relic groups incoming data into aggregation windows before threshold evaluation. [4]

As of this article's verification date, New Relic documents aggregation windows from 30 seconds to 6 hours, with a 1-minute default. It also documents delay/timer behavior that controls how long the condition waits for data associated with a window. [4]

Do not automatically choose the shortest window. Short windows react quickly but are more sensitive to outliers, sparse traffic, and delivery jitter. Longer windows smooth more variation but delay detection.

For a request-latency alert, choose a window that matches the traffic rate and how quickly the team needs to react. A low-traffic service usually needs different treatment from a high-throughput API.

Delayed and out-of-order data

If telemetry arrives late, the condition can evaluate incomplete windows unless the aggregation method/delay accommodates the data flow. This is one reason to inspect the signal preview and not treat default settings as universally correct.

Step 5: Choose Static or Anomaly Thresholds

New Relic documents two NRQL condition types relevant here: static and anomaly. [2]

Static threshold

Use a static threshold when you can define a meaningful numeric boundary. It is easier to explain in a runbook:

• latency is above X;
• for a sustained duration;
• for this application scope.

A static threshold is usually the better teaching example because the alert criterion is explicit.

Anomaly threshold

An anomaly condition uses past behavior to build a dynamic baseline. It can be useful when the signal has predictable time-based variation and a fixed threshold would be too noisy or too insensitive.

Do not choose anomaly detection simply because it sounds more advanced. If the business has a hard service-level boundary, a static condition may be clearer.

Step 6: Set the Threshold and Duration from Real Baseline Data

Before entering a threshold, inspect the service's recent latency distribution and incident history.

Ask:

• What value represents user-visible degradation?
• How often does the service cross that value during healthy operation?
• How long must the condition persist before action is warranted?
• Is there enough traffic for the average to be meaningful?

Avoid copying a threshold such as “1 second for 5 minutes” from a tutorial and using it unchanged in production. You can use a deliberately reachable value temporarily in a test policy to verify alert mechanics, then restore the production threshold after validation.

The goal is to test the alert engine without deliberately degrading a production service.

Step 7: Configure Loss of Signal Deliberately

Loss of signal answers a different question from “is latency high?” It asks whether matching telemetry has stopped arriving.

New Relic's current documentation says loss-of-signal detection requires a signal to have been present first. If a condition is enabled while no matching signal exists, the feature cannot immediately infer that the signal was lost. [2]

You can configure actions such as opening a lost-signal alert event or closing existing alert events when the signal expires. New Relic also supports an termination: expected tag for expected termination behavior in documented loss-of-signal configurations. [2]

Use loss of signal when absence of data itself is operationally meaningful. Do not enable it blindly on ephemeral workloads that frequently and intentionally stop.

Also note that New Relic documents limitations for loss-of-signal detection with nested NRQL queries. If you depend on this feature, keep the alert query compatible with the current documented constraints. [2]

Step 8: Attach the Condition to the Correct Policy and Workflow

An alert condition defines when an alert event opens. Notification routing is a separate concern.

New Relic's current documentation associates conditions with policies and uses workflows/destinations to control notification delivery. [3][5]

Keep these responsibilities separate:

• NRQL condition: What signal is unhealthy?
• Policy: How are related conditions grouped and how are incidents handled?
• Workflow/destination: Who or what is notified?

For initial verification, route the condition to a safe test destination rather than a broad paging rotation.

Name the condition so an operator can understand it without opening the editor. For example:

checkout-api — sustained transaction latency

Add a description or runbook context explaining what to check next.

Verify the Setup

A NRQL condition is ready for production only after you verify all of these:

1. The exact NRQL query returns fresh numeric data in the query builder.
2. The condition's signal preview matches the query you validated.
3. The scope contains only the intended application/environment.
4. The aggregation window and delay match the data's arrival pattern.
5. The threshold/duration are based on observed behavior, not copied blindly.
6. Loss-of-signal behavior is either deliberately configured or deliberately left off.
7. The condition belongs to the intended policy.
8. A safe test causes the expected state transition and notification path.

New Relic notes that a newly created condition must receive a valid matching signal before the platform can fully evaluate/link it to an entity, and this evaluation can take some time. [1]

Common Problems and Fixes

Problem: The NRQL query works in a chart, but the alert has no signal

Likely causes: the condition query differs from the tested query, the alert window has no matching events, or unsupported query constructs were introduced.

Fix: copy the condition's NRQL back into the query builder and compare the result. Simplify the query until it returns a stable numeric series, then reintroduce filters carefully.

Problem: The condition creates too many independent alerts

Likely cause: a high-cardinality FACET is creating a signal for many values.

Fix: decide whether you really need one alert state per facet. Replace the facet with a narrower WHERE scope or a lower-cardinality attribute where appropriate. New Relic's documented facet limits are a technical ceiling, not a recommendation to approach that ceiling. [2]

Problem: The alert flaps between open and closed

Likely causes: threshold too close to normal behavior, aggregation window too short, or threshold duration too sensitive.

Fix: inspect the raw signal history, then adjust threshold, duration, and aggregation window to represent a sustained problem. Do not hide a bad signal with an excessively long window; fix the monitored question first.

Problem: Loss of signal never opens

Likely causes: no signal was ever established, the NRQL query is filtering all data, or the query uses a construct not compatible with loss-of-signal behavior.

Fix: confirm that the condition first receives matching data. Then review the current loss-of-signal constraints and expiration settings. [2]

Problem: The alert event opens but nobody is notified

Likely cause: the condition and policy are working, but the workflow/destination routing is missing or does not match the event.

Fix: inspect the workflow/destination configuration separately. Do not keep changing the NRQL query when the event itself is already opening correctly.

Best Practices

Test the query first. This is the single most useful defense against an alert that evaluates the wrong data.

Use low-cardinality scope. Alert on service/team/environment dimensions, not request IDs or other unbounded attributes.

Separate signal logic from notification routing. A clean condition can be reused with different workflow decisions without rewriting the query.

Document the response. Put a concise runbook or diagnostic note in the alert description. An alert without a next action is only a notification.

Use loss of signal selectively. It is valuable for agents/services that are expected to report continuously, but can be noisy for expected ephemeral workloads.

Review alerts after real incidents. False positives and missed incidents are feedback about your query, threshold, duration, and routing design.

When This Setup Makes Sense

NRQL alert conditions are appropriate when the signal you care about can be expressed as a numeric NRQL result and you want control over scope, aggregation, and threshold behavior.

If you are still discovering which signal matters, start from dashboards and query exploration rather than creating an alert immediately. If you simply need a vendor-provided standard/golden-metric alert, New Relic's guided workflows may be faster than writing NRQL from scratch. [3]

For surrounding context, see the New Relic software profile, application performance monitoring guide, APM tools category, and Datadog vs New Relic comparison.

If your service is not sending reliable APM data yet, complete How to Monitor a Node.js Application with New Relic APM before implementing this alert.

FAQ

What is the difference between a NRQL query and a NRQL alert condition?

A NRQL query retrieves and aggregates New Relic data. A NRQL alert condition continuously evaluates a numeric result from that query against configured signal and threshold rules to decide when alert events should open.

When should I use a static threshold instead of anomaly detection?

Use a static threshold when the unhealthy boundary is explainable as a number and duration. Consider anomaly detection when normal behavior varies in a predictable way and a fixed boundary would create too much noise or miss meaningful deviations.

What does loss of signal mean in New Relic alerts?

It means no data has matched the condition's NRQL signal for a configured expiration period. It is not the same as a numeric value crossing a threshold. New Relic requires the signal to exist before it can detect that the signal disappeared. [2]

Conclusion

A strong NRQL alert is built in this order: define an operational question, validate a numeric query, configure the signal, choose a threshold model, set a duration from real baseline data, decide loss-of-signal behavior, and then connect the condition to notification routing.

That order keeps alert logic explainable and reduces the temptation to “fix” a noisy condition by stacking arbitrary thresholds on top of an unvalidated query.

References

1. New Relic Documentation — Alert conditions — https://docs.newrelic.com/docs/alerts/create-alert/create-alert-condition/alert-conditions/ — accessed September 10, 2026.
2. New Relic Documentation — Create NRQL alert conditions — https://docs.newrelic.com/docs/alerts/create-alert/create-alert-condition/create-nrql-alert-conditions/ — accessed September 10, 2026.
3. New Relic Documentation — Create an alert condition using New Relic — https://docs.newrelic.com/docs/tutorial-create-alerts/create-an-alert/ — accessed September 10, 2026.
4. New Relic Documentation — Streaming alerts: key terms and concepts — https://docs.newrelic.com/docs/alerts/create-alert/fine-tune/streaming-alerts-key-terms-concepts/ — accessed September 10, 2026.
5. New Relic Documentation — Create “host not reporting” NRQL alert conditions — https://docs.newrelic.com/docs/alerts/create-alert/create-alert-condition/create-nrql-host-not-reporting-conditions/ — accessed September 10, 2026. Used for current policy/workflow/destination and loss-of-signal context.

Editorial note: This tutorial was fact-checked against current official New Relic alerting documentation. No live New Relic production alert or paging workflow was triggered to claim hands-on test results.