• English日本語한국어
  • Log inStart now

NerdGraph tutorial: View entity data

Entities at New Relic refer to anything we monitor that generates or contains telemetry. Entities help you find the data you want to track in New Relic, and if you understand their relationships with other entities, you can get even more insights into your data. Here are a few examples of entities:

You can work with entities right in our UI (see Learn about New Relic entities), or you can follow the steps here about working with entities through our NerdGraph API. If you need help getting started with NerdGraph, see our Introduction to New Relic NerdGraph.

Important

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

Before you get started

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.

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:

  1. Use the queryBuilder argument to help you craft a query.
  2. 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 recommend that you experiment with the API using the NerdGraph explorer. It has inline documentation that will help you construct your queries and mutations.

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.

  1. Go to the NerdGraph GraphiQL explorer.
  2. 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.

  1. Go to the NerdGraph GraphiQL explorer.
  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
}
}
}
}
}
  1. 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: "ENTITY_GUID") {
name
entityType
}
}
}

This can also be written as a search query:

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

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

{
actor {
entities(guids: ["ENTITY_GUID_1", "ENTITY_GUID_2"]) {
name
entityType
}
}
}

Otherwise, use a search query:

{
actor {
entitySearch(query: "id IN ('ENTITY_GUID_1', 'ENTITY_GUID_2')") {
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.

Create or delete entity relationships

An entity may have a relationship with another entity. Some relationships are created automatically by New Relic, but you can also use mutations to create or delete custom relationships. We have some explanations below about how to do this, but if you need help understanding the various relationship types at New Relic, take a look at Entity relationships.

Before you manually create additional relationships or delete them, keep the following in mind:

  • Two entities can have multiple relationships, one for each relationship type.
  • Two entities can hold a relationship IF they belong to the same trusted account.
  • For each entity, you can manually define up to 2000 relationships. When the limit is reached, the API will return a LIMIT_EXCEEDED error.
  • Each mutation can fail if you don't have access to one of the two entities (source/target).

List relationships of an entity

You can use the relatedEntities field to see how pairs of entities interact and how they're related. This can help you troubleshoot upstream and downstream services and understand how minor issues may have larger repercussions, similar to how service maps can be used.

The following example shows how to query an entity by its specific GUID:

query {
actor {
entity(guid: "ENTITY_GUID") {
name
relatedEntities {
results {
source {
entity {
guid
name
}
}
target {
entity {
guid
name
}
}
type
}
}
}
}
}

Create or replace relationships

Create or replace entity relationships using the mutation entityRelationshipUserDefinedCreateOrReplace. As its name suggests, it allows you to create a relationship between two entities with a given type. If the relationship already exists between the two entities, it will be added again with the updated given values (the creation time and the creator user id):

mutation {
entityRelationshipUserDefinedCreateOrReplace(
sourceEntityGuid: "SOURCE_ENTITY_GUID"
targetEntityGuid: "TARGET_ENTITY_GUID"
type: BUILT_FROM
) {
errors {
message
type
}
}
}

Delete relationships

Delete entity relationships using the mutation entityRelationshipUserDefinedDelete. The source and target are mandatory, but the type isn't. If you execute the mutation without type, all the relationships between the two entities are removed.

mutation {
entityRelationshipUserDefinedDelete(
sourceEntityGuid: "SOURCE_ENTITY_GUID"
targetEntityGuid: "TARGET_ENTITY_GUID"
type: BUILT_FROM
) {
errors {
message
type
}
}
}

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: ["ENTITY_GUID_1", "ENTITY_GUID_2"]) {
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.

Copyright © 2023 New Relic Inc.

This site is protected by reCAPTCHA and the Google Privacy Policy and Terms of Service apply.