• /
  • Log in
  • Free account

Learn about New Relic entities

New Relic observability is built around the concept of entities. In this doc, you'll learn how we define entities, what you can do with them, and how you can create your own entities or groupings of entities.

What's an entity?

From a New Relic perspective, entity is purposefully a broad concept. An entity is anything that a) reports data to New Relic or that contains data that we have access to, and b) is something we've identified with a unique entity ID. For most entities, the ID is indicated by the attribute entityGuid.

An entity can be any fundamental data-reporting component, like an application, a host, or a database service, but it can also refer to larger groupings of those components. For example, to monitor a data center, you could aggregate those hosts in New Relic to be a workload (a custom grouping of entities). That workload is, itself, also an entity.

Also very important is the relationships between entities. Our behind-the-scenes relationship-mapping helps us understand how entities are connected, how they affect each other. And this allows us to give you the power to configure how any data you're bringing in is related to existing entities, or how it's related to other entities.

Our focus on entities and their relationships is important because our goal is to give you practical information about your business-important entities, and not give you an unhelpfully huge stream of data from a huge list of monitored things. With more insight at the entity level, you can better monitor and troubleshoot complex, modern systems.

Find and explore entities and entity data

Tip

You can create new entity types for monitoring any data source. Learn more about entity synthesis.

Some tips for finding and understanding entity data:

  • To find an entity's entityGuid and entityName and other metadata: from any list of monitored entities in the New Relic Explorer, click an entity's icon, and click See metadata and tags.
  • For most entities, its GUID is reported as the attribute entityGuid. For workloads, it's workloadGuid. You can run NRQL queries to find entities by their GUID.
  • To see connections between entities, you have several options:
  • To group entities together, see Group entities.
  • Customize entity definitions and relationships.
  • To learn technical details about entity types, see our GitHub repo. In an entity type's definition file, you'll see information like:
    • The domain: for example, APM, or Infra.
    • Its type: for example, Application or AWSECSCONTAINERINSTANCE.
    • Default tags.
    • The entityExpirationTime: how long data from that entity lasts in the UI, which is different from database data retention.

Group and organize entities

You can place entities into groups that reflect business-important relationships in your organization. For example, you might group all entities related to a specific team or department, or related to a specific service. Or you might group multiple hosts together to reflect their grouping in a data center.

To group your entities, see:

Customize entity data with entity synthesis

If you have telemetry from any source that's not supported by New Relic out of the box, you can propose a mapping for it. Once approved, any telemetry received by New Relic that matches your definition file will be synthesized into an entity.

To learn more:

  • For reserved attributes and how entity relationships are defined, keep reading this doc.
  • For how to do the work of modifying existing entity types or creating new ones, see our GitHub repo on entity synthesis.

Reserved attributes for synthesized entities

These attributes are meant to be synthesized from the telemetry we receive. Do not set them unless you're aware of the implications and consequences.

Attribute

Description

entity.guid

Generally, you should not set this attribute field on your telemetry data. New Relic may add this field to ingested data to store a unique identifier for the entity associated with the data point. If telemetry arrives with the entity.guid attribute already present, then New Relic will not change the value. However, it may cause undefined behavior such as missing entities in the UI, or telemetry not associating with the expected entities.

One use case for passing this attribute is to associate ingested telemetry with an entity already created by New Relic. When the entity.guid attribute is sent, the value will override New Relic’s entity identification system (such as entity synthesis definitions) and instead will use the attribute as the data.

entity.name

This attribute shouldn't be put on ingested telemetry data unless you're trying to override the entity name that would have been selected by New Relic’s entity identification system. While New Relic won't change the value if it's already present on the data, New Relic may add the attribute to your data. Therefore invalid or unexpected values may cause undefined behavior such as missing entities in the UI, or telemetry not associating with the expected entities.

If this field is present on ingested telemetry, its value will be used to name the entity associated with the data point. This name will be used instead of the name selected by New Relic’s entity identification system (for example, entity synthesis definitions). Note that many entities use the name as part of their identification, so changing this field may result in the generation of a new entity.

entity.type

This attribute shouldn't be put on ingested telemetry data except for certain legacy cases where it's required to distinguish entity types. Passing this field may interfere with entity detection, particularly if unrecognized values are sent in this field.

While New Relic won't change the value if already present on the data, the field is not guaranteed to provide unambiguous filtering of telemetry at query-time. Existing entity definitions already have overlapping values, and we recommend avoiding entity.type in favor of other fields for filtering telemetry queries.

This field is used by New Relic, meaning that invalid or unexpected values may cause undefined behavior such as missing entities in the UI, or telemetry not associating with the expected entities.

To learn how to do the work of modifying existing entity types or creating new ones, see our GitHub repo on entity synthesis.

Connections between entities are automatically created by New Relic based on what we can infer from your telemetry. For example, when two services that communicate using HTTP are instrumented with New Relic, we infer a "calls/called-by" relationship between them.

When viewing a specific entity in either the New Relic Explorer, Navigator, or Lookout, you can see its Related entities in the entity's mini overview. This gives a visualization of the various entities connected directly to the current entity. You can quickly view important metrics for these related entities and navigate from one entity to another, through all the connected parts of your stack.

Tip

Learn more about how entities are related with our NerdGraph API.

When relationships are not automatically detected, you can manually create them using the "Add/edit related entities" link in Related entities.

Important

Currently, you can only manually create calls/called-by relationships between service entities.

Tip

To manage manual relationships, you need to have modify and delete capabilities on entity relationships. If you don’t see the edit relationships button, contact your account admin.

Which relationships are created?

These are the relationships created between entities:

Create relationships manually

You can create additional relationships using NerdGraph, our GraphQL API.

Relationships can be created or replaced 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: "{SourceEntityGuid}"
targetEntityGuid: "{TargetEntityGuid}"
type: BUILT_FROM
) {
errors {
message
type
}
}
}

Delete relationships using the mutation entityRelationshipUserDefinedDelete. source and target are mandatory, whereas type isn't. If the mutation its executed without any type, all the relationships between the two entities will be removed.

mutation {
entityRelationshipUserDefinedDelete(
sourceEntityGuid: "{SourceEntityGuid}"
targetEntityGuid: "{TargetEntityGuid}"
type: BUILT_FROM
) {
errors {
message
type
}
}
}

Find information about fetching relationships in the relationships API tutorial.

Some considerations

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

Relationship types provide additional information about how two entities are related. The supported relationship types are:

Create issueEdit page
Copyright © 2022 New Relic Inc.