NerdGraph tutorial: View entity data

With NerdGraph, you can query details about your monitored entities.

Important

To work with an entity's golden metrics and tags, see the golden metrics API tutorial.

Entity definition

Entities are an important New Relic concept: we define an entity as anything we monitor. This includes (but is not limited to):

Applications monitored by APM.
Cloud integrations, services, and hosts monitored by our infrastructure monitoring.

To view entity details in the UI, you can use the Explorer.

When working with entities in NerdGraph, it's important to keep in mind that:

A unique entity GUID identifies an entity.
An entity exists over a span of time, even if it's a short period.
An entity provides a useful entry point for exploring data about specific metrics and events, or for contextualizing data related to other entities.

Requirements

To use entities, you need a user key.

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.

Besides domainType, other common entity attributes are:

id
accountId
name
domainId
alertSeverity
reporting

You can filter by any of the above attributes. Additionally, you can use tags for filtering too.

Caution

You cannot filter by custom, root-level entity properties. Custom properties are only retrieved as part of the entity's metadata in the actual search response. To filter by a custom field, transform it into an entity tag.

You can craft a query in one of two ways:

Use the queryBuilder argument to help you craft a query.
Use the freeform query argument to build your own search.

To use NerdGraph to query one or more entities, you can search by attribute or GUID.

Tip

NerdGraph sets the total number of entities that can be returned in one query to 200. If you need to retrieve all entities for a query, use cursor pagination as explained in the examples.

In addition to the examples below, we highly recommend exploring the API using the NerdGraph GraphiQL explorer, and benefiting from its inline documentation.

Search with `queryBuilder`

The queryBuilder argument is useful to construct simple queries. It allows you to add filters to your query from a predefined list of attributes, and their typical values. For more advanced queries, use the query argument instead.

Go to the NerdGraph GraphiQL explorer.
Run a basic query to find entities that match your search criteria. For example:

{
      actor {
        entitySearch(queryBuilder: {domain: APM, type: APPLICATION}) {
          query
          results {
            entities {
              name
              entityType
              guid
            }
          }
        }
      }
    }

Search with freeform `query`

This is useful to craft more complex queries.

Go to the NerdGraph GraphiQL explorer.
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 domainType IN ('APM-APPLICATION')"}
```

Fetch entities by GUID

When you know the GUID of the entity you want to fetch, you can just use the entity attribute:

{
    actor {
      entity(guid: "MTAwNDc5MzZ8QVBNfEFQUExJQ0FUSU9OfDExNzA0Mjk3") {
        name
        entityType
      }
    }
  }

This can also be written as a search query:

{
    actor {
      entitySearch(query: "id = 'MTAwNDc5MzZ8QVBNfEFQUExJQ0FUSU9OfDExNzA0Mjk3'") {
        query
        results {
          entities {
            name
            entityType
          }
        }
      }
    }
  }

Or, to fetch multiple entities at the same time, you can use the entities attribute:

{
    actor {
      entities(guids: ["MTAwNDc5MzZ8QVBNfEFQUExJQ0FUSU9OfDExNzA0Mjk3", "MTAwNDc5MzZ8QVBNfEFQUExJQ0FUSU9OfDExNzA0MTM3"]) {
        name
        entityType
      }
    }
  }

Otherwise, use a search query:

{
    actor {
      entitySearch(query: "id in ('MTAwNDc5MzZ8QVBNfEFQUExJQ0FUSU9OfDExNzA0Mjk3', 'MTAwNDc5MzZ8QVBNfEFQUExJQ0FUSU9OfDExNzA0MTM3')") {
        query
        results {
          entities {
            name
            entityType
          }
        }
      }
    }
  }

Example queries

Queries are requests that are intended to only fetch data (and don't have any other effect). 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's 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.

If you aren't sure how to start crafting an entity search query, use NerdGraph to help you build one. Next, retrieve entity data and the query string that was built.

Request the query field in your results to see the query string built by the queryBuilder argument.
You cannot use the query and queryBuilder arguments at the same time.

We highly recommend exploring the API using the NerdGraph GraphiQL explorer, and using its inline documentation to see the query options available to you.

{
  actor {
    entitySearch(queryBuilder: {domain: APM, type: APPLICATION}) {
      query
      results {
        entities {
          reporting
          ... on AlertableEntityOutline {
            alertSeverity
          }
        }
      }
    }
  }
}

There are many different types of Infrastructure integration entities and they are listed separately from other entity types. Use the infrastructureIntegrationType input argument to explore them.

You cannot use the query and queryBuilder arguments at the same time.
Use infrastructureIntegrationType in place of the type input argument.

We highly recommend exploring the API using the NerdGraph GraphiQL explorer and using its inline documentation to see the query options available to you.

{
  actor {
    entitySearch(queryBuilder: {infrastructureIntegrationType: F5_NODE}) {
      query
      results {
        entities {
          entityType
          domain
        }
      }
    }
  }
}

Fetch the alert severity of any entity that can be monitored by New Relic's alerts. This NerdGraph query will tell you if we are 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' and alertSeverity is not null") {
      results {
        entities {
          reporting
          ... on AlertableEntityOutline {
            alertSeverity
          }
        }
      }
    }
  }
}

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' and domainType = 'APM-APPLICATION'") {
      results {
        entities {
          name
          ... on ApmApplicationEntityOutline {
            apmSummary {
              errorRate
              apdexScore
              webResponseTimeAverage
              responseTimeAverage
            }
          }
        }
      }
    }
  }
}

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

This NerdGraph query example filters entities that belong to the INFRA domain and belong to awsRegion us-east-1, and returns their name in the search results.

{
  actor {
    entitySearch(query: "domain = 'INFRA' and tags.aws.awsRegion = 'us-east-1'") {
      results {
        entities {
          name
        }
      }
    }
  }
}

Additionally, filtering can be done by whether a given tag is present. The following query filters entities of the domainType BROWSER-APPLICATION and have the tag clusterAgentId defined.

{
  actor {
    entitySearch(query: "domainType = 'BROWSER-APPLICATION' and tags.clusterAgentId is not null") {
      results {
        entities {
          name
        }
      }
    }
  }
}

For more information, see the NerdGraph GraphiQL tagging tutorial.

This NerdGraph query example filters entities of domainType APM-APPLICATION domain that belong to awsRegion us-east-1, and returns their name in the search results. Then aggregates results to get the total number of entities grouped by New Relic account id.

{
  actor {
    entitySearch(query: "domainType = 'APM-APPLICATION'") {
      facetedCounts(facets: {facetCriterion: {facet: ACCOUNT_ID}}) {
        counts {
          count
          facet
        }
      }
    }
  }
}

Additionally, aggregation can be done by tags too; the following query filters entities of domainType APM-APPLICATION domain that belong to awsRegion us-east-1, then aggregates results to get the total number of entities grouped by Agent language.

{
  actor {
    entitySearch(query: "domainType = 'APM-APPLICATION' and tags.aws.awsRegion = 'us-east-1'") {
      facetedCounts(facets: {facetCriterion: {tag: "language"}}) {
        counts {
          count
          facet
        }
      }
    }
  }
}

For more information, see the NerdGraph GraphiQL tagging tutorial.

The NerdGraph GraphiQL explorer paginates results from an entity search.

If your search criteria yields more than the API limit of 200 entities in a single response, 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
        }
      }
    }
  }
}

The NerdGraph GraphiQL explorer allows to filter entities with alertable is true|false to show when an entity has property alertable. See entity-defnitions

You can filter by any of the above attributes. Additionally, you can use tags for filtering too.

Alertable is a entity-type configuration, that's why is not present in the results.

{
  actor {
    entitySearch(query: "alertable is true") {
      results {
        entities {
          name
        }
      }
    }
  }
}

You can combine with other filters as well in the query:

{
  actor {
    entitySearch(query: "domain='APP' and alertable is false") {
      results( {
        entities {
          name
        }
      }
    }
  }
}

Delete entities

You can manually delete any entity in your account by using the NerdGraph API. To do so, run this query with the entity's GUID in the NerdGraph GraphiQL explorer:

mutation {
  entityDelete(guids: ["EntityGuid"]) {
    deletedEntities
    failures
  }
}

Important

Currently, you can only remove the following entity types using the Nerdgraph API: APM-APPLICATION, EXT-SERVICE, and REF-REPOSITORY.

You may see a deleted entity in your UI if a New Relic agent reindexes it again.

Important

Entity definition

Requirements

Search for entities

Caution

Tip

Search with `queryBuilder`

Search with freeform `query`

Fetch entities by GUID

Example queries

Get entity data using queryBuilder

Get data for infrastructure integration entities in search results

Get alert information on alertable entities in search results

Get summary data on APM entities in search results

Get data specific to each entity type in search results

Get all tags for each entity in search results

Use tags to filter entity results

Aggregate results by an attribute or a tag

Get the nextCursor for paginated search results

Get alertable entities

Delete entities

Important

NerdGraph tutorial: View entity data

Important

Entity definition

Requirements

Search for entities

Caution

Tip

Search with queryBuilder

Search with freeform query

Fetch entities by GUID

Example queries

Get data for infrastructure integration entities in search results

Get alert information on alertable entities in search results

Get summary data on APM entities in search results

Get data specific to each entity type in search results

Get all tags for each entity in search results

Use tags to filter entity results

Aggregate results by an attribute or a tag

Get the nextCursor for paginated search results

Get alertable entities

Delete entities

Important

Search with `queryBuilder`

Search with freeform `query`