NerdGraph is New Relic’s GraphQL API, and the reason you’re looking at migrating from REST v2 is that REST v2 is being sunsetted.
Let’s dive into how you can actually query New Relic data using NerdGraph. Imagine you want to get a list of all your applications and their current error rates. In REST v2, you’d likely be making multiple calls: one to list applications, and then for each application, another call to get its error rate data. This is inefficient and chatty.
NerdGraph, being GraphQL, lets you ask for exactly what you need in a single request.
Here’s a sample NerdGraph query to get application names and their error rates for the last hour:
{
actor {
accounts(filter: { name: "Your Account Name" }) {
apps: applications {
name
alertSeverity
errorRate {
errorCount
duration
}
}
}
}
}
To run this, you’ll need a NerdGraph API key. You can generate one in the New Relic UI under Account Settings -> API Keys. Make sure it has at least application_read and infra_infrastructure_read permissions.
You can use curl to send this query to the NerdGraph endpoint:
curl -X POST 'https://api.newrelic.com/graphql' \
-H 'Content-Type: application/json' \
-H 'Api-Key: YOUR_API_KEY' \
--data-binary '{
"query": "{ actor { accounts(filter: { name: \"Your Account Name\" }) { apps: applications { name alertSeverity errorRate { errorCount duration } } } } }"
}'
Replace YOUR_API_KEY with your actual key and "Your Account Name" with the name of your New Relic account. The response will look something like this:
{
"data": {
"actor": {
"accounts": [
{
"apps": [
{
"name": "My Web App",
"alertSeverity": "CRITICAL",
"errorRate": {
"errorCount": 15,
"duration": 3600
}
},
{
"name": "My Background Service",
"alertSeverity": "WARNING",
"errorRate": {
"errorCount": 2,
"duration": 3600
}
}
]
}
]
}
}
}
This single query fetched the names, alert severities, and error counts for all applications within a specified account. The errorRate field itself is a nested object that provides errorCount and duration (in seconds, here set to 3600 for one hour).
The core of working with NerdGraph is understanding its schema. You can explore this schema using tools like GraphiQL, which is often available within the New Relic UI under the API explorer section. This interactive tool allows you to browse available types, fields, and arguments, and to test your queries directly.
The actor field is your entry point. From actor, you can access accounts. You can filter accounts by name or id. Within an account, you can then query various entities like applications, servers, alerts, and more. The applications field returns a list of application objects, and each application object has fields like name, guid, language, alertSeverity, and many others. You can then traverse further, for example, to query errorRate, throughput, or cpuPercentage for that application.
When migrating from REST v2, you’ll find that many REST endpoints have direct GraphQL equivalents, but they are structured differently. For instance, data that might have required multiple REST calls (e.g., getting application details and then its performance metrics) can often be consolidated into a single NerdGraph query. You’ll need to map your existing REST query logic to the GraphQL schema.
A common pitfall is trying to replicate REST v2’s filtering and pagination mechanisms directly in NerdGraph. GraphQL uses arguments on fields for filtering and directives for things like pagination. For example, if you wanted to filter applications by alertSeverity, you’d add an argument to the applications field: applications(filter: { alertSeverity: "CRITICAL" }). Pagination typically involves using arguments like first and after with a pageInfo type.
The power of GraphQL lies in its flexibility. You can shape the response exactly to your needs. If you only need the application name and not the alert severity, you simply omit alertSeverity from your query. This reduces payload size and processing on both the client and server sides.
The actor object in NerdGraph represents the authenticated user or service account making the request. This is significant because all queries originate from this context, and the data returned is scoped by the permissions associated with that actor. This means that if your API key doesn’t have permission to view a certain account or application, it simply won’t appear in the results, and there’s no explicit error for "access denied" on that specific item; it’s just absent.
Understanding the structure of nested queries and how they map to relationships between entities in New Relic is key. For example, account has applications, and applications have errorRate and throughput. You can chain these relationships in a single query to pull related data efficiently.
The next step in your API migration journey will likely involve understanding how to perform mutations (creating, updating, deleting data) using NerdGraph, as well as exploring more advanced querying techniques like filtering by time windows and custom attributes.