---
title: Learn about New Relic entities
source: https://docs.newrelic.com/docs/new-relic-solutions/new-relic-one/core-concepts/what-entity-new-relic
---

New Relic observability is built around the concept of **entities**. This doc explains how we define entities, what you can do with them, and how you can create your own entities or groupings of entities.

> #### 💡 TIP
>
> Want an introductory tour of the New Relic platform? See [Get to know the platform](https://docs.newrelic.com/docs/new-relic-solutions/new-relic-one/introduction-new-relic-platform).

## What's an entity? [#what-is-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](https://docs.newrelic.com/docs/using-new-relic/welcome-new-relic/get-started/glossary/#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](https://docs.newrelic.com/docs/new-relic-one/use-new-relic-one/get-started/introduction-new-relic-one) (a custom grouping of entities). That workload is, itself, also an entity. We give you the ability to [create your own entities](#entity-synthesis).

Also very important is the [relationships between entities](#related-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**, as opposed to giving you an unhelpfully huge stream of data from a huge list of monitored services and systems. With more insight at the entity level, you can better monitor and troubleshoot complex, modern systems.

![New Relic entity list view](https://docs.newrelic.com/images/platform_screenshot-crop_entities-view.webp "New Relic entity list view")

**[one.newrelic.com](https://one.newrelic.com)**: When you open New Relic, you land on the **All entities** page, which gives you an overview of your monitored entities. From this page, you can view metadata for an entity, or click an entity to see performance details.

## Filter and explore your entities [#filter-entities]

The entity filter bar is available on many New Relic UI pages, including the main entity list view, APM, the browser monitoring UI, the infrastructure UI, and more. To learn how to use the filter bar to explore entities and save helpful filters, see [Entity filter](https://docs.newrelic.com/docs/new-relic-solutions/new-relic-one/core-concepts/search-filter-entities).

## Learn about entities [#find]

To find an entity's GUID and other metadata in the UI: from any [list of entities](https://docs.newrelic.com/docs/new-relic-solutions/new-relic-one/core-concepts/new-relic-explorer-view-performance-across-apps-services-hosts#find), click an entity's  icon, and click **See metadata & tags**.

Every entity has a New Relic-specific ID number, which is reported as the attribute `entityGuid`. You can run [NRQL queries](https://docs.newrelic.com/docs/query-your-data/nrql-new-relic-query-language/get-started/introduction-nrql-new-relics-query-language) of entities using their GUID.

### Learn about relationships between entities [#relationships]

Here are some options for understanding relationships between monitored entities:

-   When viewing an entity in the UI, use the [**Related entities** UI](#related-entities).
-   Use [service maps](https://docs.newrelic.com/docs/service-maps-dependencies-new-relic-one) to see a visual representation of the connections.
-   Use [distributed tracing](https://docs.newrelic.com/docs/distributed-tracing-new-relic-one) to see how entities call each other in transactions.
-   Use [our NerdGraph API](https://docs.newrelic.com/docs/apis/nerdgraph/examples/nerdgraph-relationships-api-tutorial) to view relationship info.

### Learn technical details about entities [#technical-details]

To learn technical details about entity types, see our [GitHub repo for our entity types](https://github.com/newrelic/entity-definitions/tree/main). For example, for the details about APM-monitored entities, see [APM application](https://github.com/newrelic/entity-definitions/tree/main/entity-types/apm-application).

Each entity contains several files that govern how it reports data. For example, the `golden_metrics` file contains information about its most important metrics, which are usually highlighted in our UI experiences. Here's [the `golden_metrics.yml` file for APM-monitored entities](https://github.com/newrelic/entity-definitions/blob/main/entity-types/apm-application/golden_metrics.yml).

An entity's `definition` file contains information like:

-   The `domain`: for example, `APM`, or `Infra`.
-   Its `type`: for example, `Application` or `AWSECSCONTAINERINSTANCE`.
-   Default [tags](https://docs.newrelic.com/docs/new-relic-one/use-new-relic-one/core-concepts/use-tags-help-organize-find-your-data).
-   The `entityExpirationTime`: for more on this, see [Entity expiration](#expiration).

### Entity expiration [#expiration]

Different entity types have different time-to-live periods, determined by the `entityExpirationTime` set in the `definition` file for each [entity type](https://github.com/newrelic/entity-definitions/tree/main/entity-types). This expiration time governs how long the record for that entity exists in New Relic after the entity stops reporting data.

New Relic monitors a huge number of entities, and many of those entities are short-lived (for example, Kubernetes containers). For these reasons it's necessary to regularly delete entity records that have stopped reporting data.

This expiration time relates to the record of the entity itself and is **not** related to [telemetry data](https://docs.newrelic.com/docs/data-apis/understand-data/new-relic-data-types). Put another way: the telemetry data reported by your monitored entities is findable in NRDB and available via NRQL, dependent on its [data retention settings](https://docs.newrelic.com/docs/telemetry-data-platform/manage-data/manage-data-retention). But the record of the entity itself, once it expires, will no longer exist in New Relic.

The options for entity expiration time are these:

-   `FOUR_HOURS`
-   `DAILY` (24 hours)
-   `EIGHT_DAYS`: Default value applied if no deadline is defined in the `definition` file.
-   `QUARTERLY` (3 months)
-   `MANUAL`: This setting applies only for entities whose creation and deletion are manually controlled (for example, workloads and dashboards).

## Group and organize entities [#group]

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:

-   [Tag entities](https://docs.newrelic.com/docs/new-relic-one/use-new-relic-one/core-concepts/tagging-use-tags-organize-group-what-you-monitor).
-   [Create workloads](https://docs.newrelic.com/docs/new-relic-solutions/new-relic-one/workloads/workloads-isolate-resolve-alert-events-faster), which allow you to group business-important sets of entities.
-   [Create entities and customize entity data](#entity-synthesis)

## Create and manage your own entities with entity synthesis [#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](https://github.com/newrelic/entity-definitions#entity-definitions).

### Reserved attributes for synthesized entities [#reserved-attributes]

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 that we already monitor. When the `entity.guid` attribute is sent, the value will override our 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 our entity identification system. While we won't change the value if it's already present on the data, we 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 our entity identification system (for example, [entity synthesis definitions](https://github.com/newrelic/entity-definitions#entity-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](https://github.com/newrelic/entity-definitions#entity-definitions).

## Uninstrumented entities [#uninstrumented-entities]

Using your telemetry, we can detect entities that are not being instrumented right now but are used by your application. For example, one of your instrumented entities may be calling an Amazon RDS database which is not currently instrumented by New Relic, so we cannot provide any tooling like monitoring or alerting for it.

In that case, we create a so-called "uninstrumented entity" together with the relationship with the instrumented one. It is displayed in the [service map](https://docs.newrelic.com/docs/new-relic-solutions/new-relic-one/ui-data/service-maps/introduction-service-maps) for the instrumented entity. We provide clear instructions to instrument it, displayed with just clicking over the entity.

## Entity relationships [#related-entities]

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 an entity in the [entity explorer](https://docs.newrelic.com/docs/new-relic-solutions/new-relic-one/core-concepts/new-relic-explorer-view-performance-across-apps-services-hosts#find), Navigator, and Lookout views, you can see its **Related entities** in the right pane. 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 how to dig deeper into entity relationships [with our NerdGraph API](https://docs.newrelic.com/docs/apis/nerdgraph/examples/nerdgraph-entities-api-tutorial).

### Types of entity relationships [#types]

Entities can be related to each other in various ways. The collapser below lists the supported entity relationships. Once you understand the possible relationships, take a look at the list of [automatically created relationships](#relationship-created) or consider whether you want to [create custom entity relationships](#create-custom-relationship).

**Relationship types**

| Type          | Description                                                                                                                                                   |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `BUILT_FROM`  | The target entity contains the code for the source entity.                                                                                                    |
| `CALLS`       | The relationship between one service or application calling another. Used to display upstream and downstream services.                                        |
| `CONNECTS_TO` | The source entity has a connection to the target entity.                                                                                                      |
| `CONSUMES`    | The source entity consumes messages from a target Kafka topic or other queue system.                                                                          |
| `CONTAINS`    | The relationship and hierarchical use cases common to modern and cloud infrastructure. For example, this could indicate that the `HOST` contains a container. |
| `HOSTS`       | The relationship between an application or process and the system it runs on.                                                                                 |
| `IS`          | The relationship between an entity captured as a separate entity by another telemetry data source and the one you're currently viewing.                       |
| `MANAGES`     | The source entity manages the target that represents a subsystem of the source.                                                                               |
| `MEASURES`    | The source entity is used to measure the target entity.                                                                                                       |
| `PRODUCES`    | The source entity produces messages to a target Kafka topic or other queue system.                                                                            |
| `SERVES`      | The relationship between a backend application and the browser application it returns in the response.                                                        |

### Which relationships are automatically created? [#relationship-created]

Automatic relationships are created based on the telemetry that's being reported by the entities. These relationships have a Time To Live (TTL). This means that they will be automatically deleted if the metrics used to create the relationship are not reported in a given period of time. The default TTL for a relationship is 75 minutes. The TTL can vary from 10 minutes up to 3 days depending on the relationship type.

These are the relationships between entities that we create automatically:

**Source: New Relic agent**

| Relationship source                             | Relationship type | Relationship target                             | Why is the relationship created?                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| ----------------------------------------------- | ----------------- | ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Application instrumented with a New Relic agent | CALLS             | Application instrumented with a New Relic agent | Relationships between applications monitored by New Relic agents are reported using the `DurationByCaller` metric. The callee reports the metric. For example, the metric `DurationByCaller/Mobile/100/1234/HTTP/all` indicates that the caller is `APPLICATION 1234` for account 100.                                                                                                                                                                                                                                 |
| Application instrumented with a New Relic agent | CALLS             | Service instrumented with a New Relic agent     | An application (caller) that calls a service (callee) monitored by New Relic creates a relationship that's reported by the caller using the `ExternalApp` metric. For example, the metric `ExternalApp/dirac.vips.net/100#1234/all` indicates that the callee is `APPLICATION 1234` for account 100. The metric is reported if the callee successfully responds to the caller.                                                                                                                                         |
| Service instrumented with a New Relic agent     | CALLS             | Service instrumented with a New Relic agent     | When a New Relic agent detects that a service (caller) calls another service (callee) instrumented by New Relic, the callee reports the  metric `ClientApplication`. For example, the metric `ClientApplication/100#1234/all` indicates that the caller is `APPLICATION 1234` for account 100.                                                                                                                                                                                                                         |
| Service instrumented with a New Relic agent     | CALLS             | A datastore instance                            | When an application calls a datastore instance it creates a relationship reported with the `DatastoreInstance` metric. For example, the metric `Datastore/instance/MySQL/172.16.16.3/3306` indicates the datastore instance is vendor: MySQL, host: 172.16.16.3, port: 3306. This metric also supports the legacy datastore instance format `Datastore/instance/MySQL/172.16.16.3:3306`. Currently we cannot determine whether the datastore instance is instrumented by New Relic and has an entity associated to it. |
| APM agent                                       | SERVES            | Browser agent                                   | This relationship is created when an APM agent [injects](https://docs.newrelic.com/docs/browser/browser-monitoring/installation/install-browser-monitoring-agent/#select-apm-app) the browser agent into a page.                                                                                                                                                                                                                                                                                                       |
| Workload entity                                 | CONTAINS          | Any entity                                      | When a workload is created or updated, relationships for each of the entities that belong to the workload are created. Because some workloads are “dynamic” (defined by tags), relationships are re-created every 5 minutes. This way entities can join or leave the workload.                                                                                                                                                                                                                                         |

**Source: Infrastructure**

| Relationship source | Relationship type | Relationship target | Why is the relationship created?                                                                                                  |
| ------------------- | ----------------- | ------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| Infrastructure host | HOSTS             | Application         | This relationship is created when an application is running in one or more hosts, and the infra agent is running in those hosts.  |
| Infrastructure host | HOSTS             | Container           | This relationship is created when containers are running in one or more hosts, and the host is instrumented with the infra agent. |

**Source: Synthetic monitor**

| Relationship source | Relationship type | Relationship target | Why is the relationship created?                                                                                                                                                                                                                                                              |
| ------------------- | ----------------- | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Synthetic monitor   | CALLS             | Browser agent       | This relationship is created when a synthetics monitor checks a page instrumented with the browser agent.                                                                                                                                                                                     |
| Synthetic monitor   | CALLS             | APM application     | Agent events that contain the attribute `nr.syntheticsMonitorId` have been described as synthetics monitors (the source) interacting with an APM application (the target). If the header exists and the APM application Id exists, a relationship is created between the monitor and the app. |

**Source: Kubernetes**

| Relationship source | Relationship type | Relationship target | Why is the relationship created?                                                                                                                      |
| ------------------- | ----------------- | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| Cluster             | CONTAINS          | Pod                 | This relationship is created when a pod is created in a cluster instrumented with the New Relic Kubernetes integration.                               |
| Cluster             | CONTAINS          | Deployment          | This relationship is created when a deployment is created in a cluster instrumented with the New Relic Kubernetes integration.                        |
| Cluster             | CONTAINS          | DaemonSet           | This relationship is created when a DaemonSet is created in a cluster instrumented with the New Relic Kubernetes integration.                         |
| Cluster             | CONTAINS          | StatefulSet         | This relationship is created when a StatefulSet is created in a cluster instrumented with the New Relic Kubernetes integration.                       |
| Cluster             | CONTAINS          | Host                | This relationship is created when a host that's part of a cluster is instrumented with the New Relic Kubernetes integration.                          |
| Deployment          | CONTAINS          | Pod                 | This relationship is created when a deployment creates a pod in a cluster instrumented with the New Relic Kubernetes integration.                     |
| DaemonSet           | CONTAINS          | Pod                 | This relationship is created when a DaemonSet creates a pod in a cluster instrumented with the New Relic Kubernetes integration.                      |
| StatefulSet         | CONTAINS          | Pod                 | This relationship is created when a StatefulSet creates a pod in a cluster instrumented with the New Relic Kubernetes integration.                    |
| Pod                 | CONTAINS          | Container           | This relationship is created when a pod creates a container in a cluster instrumented with the New Relic Kubernetes integration.                      |
| Host                | HOSTS             | Pod                 | This relationship is created when a pod is running in a host that's part of a cluster instrumented with the New Relic Kubernetes integration.         |
| Container           | HOSTS             | Application         | This relationship is created when an application is running in docker, and the hosts where docker is running are instrumented by the the infra agent. |

**External services**

| Relationship source                                     | Relationship type | Relationship target | Why is the relationship created?                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| ------------------------------------------------------- | ----------------- | ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| External service                                        | CALLS             | External service    | When the relationship is created, the external service reports a span with its name on the `service.name` attribute and the name of the service that initiates the call in the `parent.service.name` attribute.                                                                                                                                                                                                                                                                                    |
| Application                                             | IS                | External service    | A relationship between an application and an external service is created so that users can navigate between them using the related entities component.                                                                                                                                                                                                                                                                                                                                             |
| Browser application instrumented with a New Relic agent | CALLS             | External service    | A browser application reports an `Ajax/HostTransaction` metric when calling an external service (URL). Example metric: `Ajax/HostTransaction/api.segment.io:443/CallbackTime'`                                                                                                                                                                                                                                                                                                                     |
| Cluster                                                 | CONTAINS          | External service    | When the relationship is created, the external service reports a span with the attribute `k8s.cluster.name`, the name of the cluster. The cluster must be instrumented with the New Relic Kubernetes integration and the cluster name set for the integration must match the one reported in the span.                                                                                                                                                                                             |
| Pod                                                     | HOSTS             | External service    | When the relationship is created, the external service reports a span with the following attributes: - `service.name`: The name of the service. - `k8s.cluster.name`: The name of the cluster. - `k8s.pod.name`: The name of the pod that’s running the service. - `k8s.namespace.name`: The namespace where the pod was created. The cluster must be instrumented with the New Relic Kubernetes integration and the cluster name set for the integration must match the one reported in the span. |

### Handling Legacy Externals and Uninstrumented Entities Exceptions in Entity Relationships

-   If a service is invoked intermittently, with intervals exceeding 10 minutes between calls, the DFM, external services user interface, and trace details may display it as a legacy external entity. This could lead to duplication of an already instrumented service. This is the current behavior for all external calls.

-   If a service is accessed through multiple hostnames but tracing is not enabled for each instance, all maps will depict both an instrumented and an uninstrumented service for the corresponding child application. To resolve this, ensure that tracing is activated for all instances.

### Create custom entity relationships [#create-custom-relationship]

When relationships are not automatically detected, you can manually create them using our [NerdGraph API](https://docs.newrelic.com/docs/apis/nerdgraph/examples/nerdgraph-entities-api-tutorial/#manual-relationships), or you can do it in the New Relic UI with the **Add/edit related entities** link in **Related entities**. 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.