Introduction to New Relic NerdGraph

NerdGraph is New Relic's GraphQL API, an efficient and flexible query language that lets you request exactly the data you need, without over-fetching or under-fetching. While typical REST APIs require loading from multiple URLs, NerdGraph calls get all the data you need in a single request. NerdGraph also makes it easier to evolve APIs over time and enables powerful developer tools.

If your account hosts data in the EU data center, ensure you are using the proper API endpoints for EU region accounts.

Use the NerdGraph GraphiQL explorer

New Relic provides you with a powerful NerdGraph GraphiQL tool to explore the API with embedded schema definitions. To use the explorer:

Make sure you have a valid New Relic API key.
Go to https://api.newrelic.com/graphiql.

Authentication

To get started with the NerdGraph GraphiQL explorer, you must have a New Relic API key. If you do not already have one:

Generate a new API key in the NerdGraph GraphiQL explorer.

OR
Create a new API key from your New Relic account settings.

NerdGraph endpoint

NerdGraph has a single endpoint:

https://api.newrelic.com/graphql

To access the endpoint, use the following cURL command:

curl -X POST https://api.newrelic.com/graphql \
-H 'Content-Type: application/json' \
-H 'API-Key: YOUR_API_KEY' \
-d '{ "query":  "{ requestContext { userId apiKey } }" } '

NerdGraph tutorials

You can use NerdGraph to:

NerdGraph GraphiQL explorer	Tutorial
Query all the entities associated with your account.	See the entities API tutorial.
Create, manage, and add tags to your entities.	For more information and examples, see the tagging API tutorial.
Query your distributed tracing data.	See the trace data API tutorial.
Understand upstream and downstream relationships with your services.	See the relationships API tutorial
Configure your New Relic Infrastructure cloud integrations.	See the cloud integrations API examples.
Query event data and custom event data in New Relic Insights with NRQL.	See the NerdGraph GraphiQL and NRQL tutorial.
Watch video tutorials about NerdGraph.	Go to the New Relic University tutorial Intro to New Relic GraphQL API (NerdGraph). Or, go directly to the full online course New Relic APIs.

NerdGraph terminology

The New Relic GraphQL server explicitly defines the graph structure of NerdGraph. The following keywords are common to all GraphQL servers. Use these keywords to help build and understand your own queries. In addition:

To understand how NerdGraph provides unified access to all the things you monitor with New Relic, see NerdGraph entities.
To understand schema definitions: From the NerdGraph GraphiQL explorer, select Docs.

Term	Definition
Queries	Queries are basic requests that are intended to only fetch data, without any additional actions. Queries in the NerdGraph GraphiQL explorer are not static, meaning that you can ask for more or less data depending on your needs. For each query, you can specify exactly what data you want to retrieve, as long as it is supported by the schema.
Mutations	Mutations are requests that are intended to have additional actions, such as creating data or updating data on a server. Mutations require the keyword `mutation`, as well as the `name` of the mutation.
Type	Data in GraphQL is organized into types. Types can be scalars (like strings, numbers, or booleans) or object types. An object type is a custom type made up of a collection of fields. For example, an object type called `User` may represent a user in a system.
Field	A field represents a piece of information on an object type that can be queried. Fields can be scalars, lists, or objects. For example, a `User` object type could have a string field called `name`.
Interface	An interface is an abstract type that represents a collection of common fields that other object types can `implement`.

Make queries with the explorer

You can make queries with the NerdGraph GraphiQL explorer. The explorer provides built-in schema definitions and features, including auto-complete and query validation.

In GraphQL, you ask for specific information in the graph structure of New Relic's data. You can follow the nodes of the graph to query exactly the data that you want.

New fields are added seamlessly, and old fields can be marked as deprecated, which removes them from documentation and allows an eventual, graceful shutdown of that field.

Query account a New Relic user can access

You can query for the name of an account that an actor (a New Relic authorized user) has access to:

query {
   actor {
      account(id: YOUR_ACCOUNT_ID) {
         name
      }
   }
}

The response will mirror the query structure you defined in the request, making it easy to ask for the specific data that you want.

{
  "data": {
      "actor": {
         "account": {
            "name": "Data Nerd"
         }
      }
   }
}

Query user, account, and NRQL in one NerdGraph GraphiQL request

The graph structure shows its capabilities when queries become more complex. For example, you can query for user information, account information, and make a NRQL query with one request. With REST API, this would take three different requests to three different endpoints.

query {
   actor {
      account(id: YOUR_ACCOUNT_ID) {
         name
         nrql(query: "SELECT * FROM Transaction") {
            results
         }
      }
      user {
         name
         id
      }
   }
}

NerdGraph

始めてみましょう

チュートリアル