NerdGraph entities API tutorial

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)

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

1. Go to the NerdGraph GraphiQL explorer at https://api.newrelic.com/graphiql.

2. 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
           }
         }
       }
     }
   }
   

3. Add the following variables to the Query variables section in NerdGraph:

   {"query": "name LIKE 'nerd-graph' AND type IN ('APPLICATION')"}

Search by entity GUID

1. Use a specific entity's GUID to query deeper into its related data. For example:

   query($guids: EntityGuid!) {
     actor {
       entities(guids: $guids) {
         entityType
         name
       }
     }
   }

2. 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
            }
          }
        }
      }
    }
  }
}

Get all tags for each entity in search results

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
        }
      }
    }
  }
}

For more help