To query data with the New Relic NerdGraph, we use the concept of an entity. An entity provides unified access to all the things you monitor with New Relic, including but not limited to:
- Applications monitored by New Relic (APM)
- Cloud integrations, services, and hosts monitored by New Relic (Infrastructure monitoring)
To view entity details in the New Relic UI, use the entity explorer in New Relic One.
Entity definition
Each entity has similar traits:
- A unique entity GUID identifies it.
- It exists over a span of time, even if it is a short period.
- It provides a useful entry point for exploring data about specific metrics and events, or for exploring data related to other entities.
Requirements
You must have a user-specific API key to run NerdGraph queries. 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.
Search for entities
New Relic searches for entities by their attributes: primarily their name, but also by type of entity and other values. The search returns basic data about entities matching the search criteria. Then, from the basic query results, you can query a specific entity by its GUID.
For example, to use NerdGraph to query one or more entities, you can search by attribute or GUID.
Search by attribute
-
Go to the NerdGraph GraphiQL explorer at https://api.newrelic.com/graphiql.
-
Run a basic query to find entities that match your search criteria. For example:
query($query: String!) { actor { entitySearch(query: $query) { count results { entities { name entityType guid } } } } }
-
Add the following variables to the Query variables section in NerdGraph:
{"query": "name LIKE 'nerd-graph' AND type IN ('APPLICATION')"}
Search by entity GUID
-
Use a specific entity's GUID to query deeper into its related data. For example:
query($guids: EntityGuid!) { actor { entities(guids: $guids) { entityType name } } }
-
Add the following variables to the Query variables section:
{"guids": "entity-guid-here"}
Example queries
Queries are requests that are intended to only fetch data (no side effects). NerdGraph queries 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.
Entities in NerdGraph rely on GraphQL interfaces, a concept that allows objects to share common fields. Interfaces are used to provide data for specific entity types, as you will see in many of these NerdGraph query examples.
- Get alert information on alertable entities in search results
-
You can fetch the alert severity of any entity that can be monitored by New Relic Alerts. This NerdGraph query will tell you if New Relic is currently receiving data from your application (using the
reporting
field).- If the entity is an alertable type, results will include the alert severity of the entity.
- If the results include entities that are not alertable, they will not include the
AlertableEntityOutline
fields.
{ actor { entitySearch(query: "name like 'nerdgraph'") { results { entities { reporting ... on AlertableEntityOutline { alertSeverity } } } } } }
- Get summary data on APM entities in search results
-
Different entity types have specific data associated with them. The following NerdGraph query example shows a selection of fields available for APM application entities; more summary data can be requested in your query. If entities of other types are returned in your search results, they will not include these fields.
{ actor { entitySearch(query: "name like 'nerdgraph'") { results { entities { name ... on ApmApplicationEntityOutline { apmSummary { errorRate apdexScore webResponseTimeAverage responseTimeAverage } } } } } } }
- Get data specific to each entity type in search results
-
Different entity types have specific data associated with them. This NerdGraph query example requests the name for all entities regardless of which entity type they are, as well as the error rate for APM, Browser, and Mobile entities. If entities of other types are returned in your search results, they will not include an error rate field.
{ actor { entitySearch(query: "name like 'nerdgraph'") { results { entities { name ... on ApmApplicationEntityOutline { apmSummary { errorRate } } ... on BrowserApplicationEntityOutline { browserSummary { jsErrorRate } } ... on MobileApplicationEntityOutline { mobileSummary { httpErrorRate } } } } } } }
-
This NerdGraph query example fetches tags for every entity returned in the search results. For more information, see the NerdGraph GraphiQL tagging tutorial.
{ actor { entitySearch(query: "name like 'nerdgraph'") { results { entities { name tags { key values } } } } } }
- Get the nextCursor for paginated search results
-
The NerdGraph GraphiQL explorer paginates results from an entity search. If your search criteria yields more than the API limit and you want to view the rest of the results, you can request
nextCursor
in your initial request and use its value in another query to retrieve the following "page" of results. If there are no more results,nextCursor
will be null.{ actor { entitySearch(query: "name like 'nerd-graph'") { results { nextCursor entities { name } } } } }
Use the value of
nextCursor
in your next search:{ actor { entitySearch(query: "name like 'nerd-graph'") { results(cursor: "next_cursor_value") { nextCursor entities { name } } } } }