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