What is an entity in New Relic, and how does the platform assign telemetry to one?

## What an entity is New Relic does not present a pile of records; it presents **entities**. An entity is anything the platform monitors and can name and navigate to as a thing in its own right: a service reported by an APM agent, a host reported by the infrastructure agent, a container, a queue, a database, a browser or mobile application. Each entity has an identifier — its **entity GUID** — and a type. That identity is load-bearing far beyond the UI. Things that hang off entity identity include: - The health summary and golden-signal charts you land on when you open a service. - Relationship views such as the service map, which are drawn between entities, not between records. - Alert conditions that target an entity or a group of entities. - Workloads, which bundle entities into something a team can treat as one unit. - Navigation from one signal to another for "the same thing". Records in NRDB are the raw material; entities are the index the product is organised around. ## How telemetry becomes an entity The platform holds definitions describing which attributes identify which kind of entity, and matches incoming telemetry against them. Telemetry carrying a recognised service-identifying attribute — `service.name` on open-instrumentation data, or the application name an APM agent reports — is attached to a service entity. Host-identifying attributes produce a host entity. The matched records then carry entity attributes such as `entity.guid`, `entity.name` and `entity.type`, which is why you can query by entity as well as navigate by it. Two properties of this are worth stating explicitly in an interview: 1. **It is inference, not registration.** Nobody declares a service up front. The entity exists because telemetry arrived that looked like it, and it stops being updated when that telemetry stops. 2. **Failure is silent.** Unmatched telemetry is not rejected. It lands in NRDB, NRQL finds it, and it simply never becomes an entity. ## What goes wrong when the inference fails | Symptom | Underlying cause | Where you fix it | |---|---|---| | One service appears twice, each with part of the traffic | two emitters report different identifying names | at the emitter: one agreed name per service | | Charts look right, entity page shows half the throughput | some instances name themselves differently after a deploy | in the deployment config that sets the name | | Data is queryable but the service has no entity page | no attribute matched an entity definition | set the service-identifying attribute at the source | | Alert on a service is quiet during a real incident | the condition targets one of two split identities | fix the naming, then re-target the condition | | Entity count grows every deploy | the name embeds something per-instance or per-release | remove the varying part from the identifying attribute | The split-identity case is the one that hurts most, because nothing looks broken. Both entities show plausible charts. Throughput is halved on each, so a threshold tuned on the whole service no longer fires; an error rate computed per identity can look fine on both while the aggregate is bad; and the service map draws two boxes where the architecture has one service. The opposite failure — telemetry with no identifying attribute at all — is easier to spot but confusing the first time. An engineer will say "the data is not there", run a NRQL query, and find that it very much is. The data reached the store; it never reached the catalogue. ## Diagnosing it A workable sequence when identity is suspect: 1. Query the raw records for the service and count distinct entity identifiers over a window. More than one for something you believe is one service is the split. 2. Facet the same records by the identifying attribute to see exactly which spellings are in play and which hosts or deployments produce each. 3. Check whether the affected records carry entity attributes at all — none means nothing matched a definition, rather than matching the wrong one. 4. Fix at the emitter, not in the query. A dashboard that unions two identities papers over the problem while alerting, the service map and every other entity-shaped feature stay broken. 5. Accept the discontinuity. Correcting a name creates a new identity going forward; historical records keep the old one, so a migration note is worth more than pretending the history moved. ## Owning it as a platform concern The durable lesson is that the identifying attribute is a **contract between teams**, not a per-service preference. Something must decide, centrally, how a service names itself and how that name survives a redeploy, a rename of the repository, a move between orchestrator namespaces and a switch of instrumentation. When that decision is left to each service, identity drifts, and the drift shows up as a slow decay of exactly the features people bought the platform for — the map, the workload, the alert that targets a service rather than a query. It is a modest-looking topic that quietly decides whether the catalogue reflects the architecture.