The NRQL Cookbook: Queries Every New Relic Engineer Should Know

NRQL turns raw telemetry into the exact number you need

Dashboards are convenient, but NRQL is where New Relic gets powerful. The New Relic Query Language looks like SQL but is built for time-series telemetry, and once you internalise a handful of patterns you can answer almost any question about your systems in seconds. This is the cookbook I reach for.

The Anatomy of a Query

Every NRQL query has the same skeleton: SELECT a function, FROM an event type, optionally WHERE you filter, FACET to group, and SINCE to bound time.

SELECT count(*) FROM Transaction
WHERE appName = 'my-api'
FACET name SINCE 1 hour ago

Learn that shape and every recipe below is a variation on it.

Latency: Stop Looking at Averages

Averages hide pain. A 200 ms average can still mean one in twenty users waits three seconds. Always query percentiles.

SELECT percentile(duration, 50, 95, 99)
FROM Transaction WHERE appName = 'my-api'
TIMESERIES SINCE 6 hours ago

The gap between p50 and p99 is your consistency story. A wide gap means a tail of slow requests worth hunting.

Error Rate as a Percentage

Raw error counts are meaningless without volume. Compute a real rate:

SELECT percentage(count(*), WHERE error IS true)
FROM Transaction WHERE appName = 'my-api'
SINCE 1 day ago

Error rate as a percentage of traffic is the number that actually matters

Find the Slowest Endpoints

When something is slow, this tells you where to look first:

SELECT average(duration), count(*)
FROM Transaction WHERE appName = 'my-api'
FACET name SINCE 3 hours ago LIMIT 10

Sort mentally by average times count — the endpoint that is both slow and busy is where you get the biggest win.

Throughput Over Time

SELECT rate(count(*), 1 minute)
FROM Transaction WHERE appName = 'my-api'
TIMESERIES SINCE 2 hours ago

Week Over Week With COMPARE WITH

One of NRQL's best features. Overlay this week against last:

SELECT count(*) FROM Transaction
WHERE appName = 'my-api'
TIMESERIES SINCE 1 week ago COMPARE WITH 1 week ago

A sudden dip that is not present in the prior week is a real regression, not normal seasonality.

A Quick Reference

You want Function
How many count(*)
How fast (typical) percentile(duration, 50)
How fast (worst) percentile(duration, 99)
Requests per minute rate(count(*), 1 minute)
Distinct users uniqueCount(userId)
Share of a subset percentage(count(*), WHERE ...)

Build Alerts From the Same Queries

Every query above can become an alert condition. If a query drives a dashboard chart you stare at during incidents, it should also drive an alert so New Relic tells you before you have to look.

If you can express a problem as a NRQL query, you can dashboard it, alert on it, and prove when it is fixed. Learn the language, not just the buttons.

What to Learn Next

  • TIMESERIES with FACET for per-service trend lines
  • Nested aggregation for percentages of percentages
  • Alert conditions built directly on your cookbook queries

Arivanandhan Chitheshwaran