Entity Synthesis

What is an entity, and why synthesize data into an entity?

An entity is anything that a) reports data to New Relic or contains related data that one has access to, and b) telemetry stamped with a unique entity ID. A focus on entities is important because New Relic’s goal is to not only provide practical observability context about business-centric objects, but also to easily organize them into logical systems. With more insight at the entity level, better monitoring and troubleshooting complex, modern systems become easier.

As telemetry flows into the New Relic data pipeline, there’s an attempt to classify a data source type and stamp that incoming telemetry with distinct ids (called guids), which in turn allows for easier classification of data ingested. New Relic has a standard set of entity types that are used to categorize data into what are known as entities; for example, APM, infrastructure, browser, and mobile. 

But what happens when telemetry is sent outside of standard agents, such as when using Flex, ingest APIs, or via OpenTelemetry? This is where entity synthesis comes into play.

Entity synthesis is a configuration-based process that dynamically generates entity guids, based on unique criteria contained within incoming telemetry. Advantages of mapping telemetry data to an entity include:

• Quick access to telemetry via curated experiences, including entity explorer, workloads, service levels, and all other entity-specific platform features.
• A standard view that can be used to compare signals from multiple instances of the same entity.
• A standard set of summary/golden metrics that represent key performance indicators (KPIs) of a given entity type.
• Entities can be tagged with multiple key-value pairs for easy filtering and grouping.
• Alert state definitions provide an intuitive view into the health of entities, based on alert conditions configured.

Example telemetry (raw form)     

The screen capture below shows raw, custom event data where the eventType is event, which is derived from fetching, parsing, and inserting data via the Event API.

This data doesn’t have any entity guids stamped yet, so it’s considered unsynthesized and isn’t yet categorized into an entity type. The unique nodeUid attribute above though can be used as the primary identifier for generating a guid. We’ll provide more information on this later in this blog post.

The same data can easily be visualized in a custom dashboard. Below is an example of the same custom event being graphed into a pie chart, targeting a key dimension—state—which may be a useful golden metric within this telemetry to visualize and/or alert on.

We recommend that you add any useful context to data whenever you can. By creating an entity, you can align this sort of data to a specific entity type, and ultimately classify the data, so that it can be more quickly recognized and associated with other entities or telemetry within New Relic.

To help you with defining entity definitions, New Relic has created a public repository for defining custom entity types and where many of the New Relic built definitions for common tools like APM or infrastructure reside:

https://github.com/newrelic/entity-definitions

The following steps will help you turn any raw telemetry (that is, data ingested into New Relic that’s not classified or stamped with an entity guid) into entities.

Synthesizing telemetry, step by step

Step 1: Clone and branch the public repository

Clone or fork this repository: https://github.com/newrelic/entity-definitions/entity-types, and then create a branch. In this repo, there are hundreds of other existing entity definitions. We recommend that you take a look at those existing definitions as references to get a better understanding when creating an entity definition for the first time. The documentation here also provides in-depth information about the four required files necessary to define an entity: definition.yml, dashboard.json, golden_metrics.yml, and summary_metrics.yml.

Step 2: Define synthesis rules (definition.yml)

Using the ext-solarwinds_server entity type as an example, the screen capture below shows the definition.yml file (left) and what the resultant experience is in the New Relic entity explorer (right).

The definition.yml file defines the entity type, along with rules that constitute how unique entities should be generated. Data flowing into New Relic is checked against these “match rules” and if incoming telemetry matches, it’s automatically associated, creating a unique guid for each set of matching data. In the example above, the unique identifier (npm.nodeName) is the sole identifier to generate a unique entity guid against. Further, the conditions stanza defines two filter conditions specifying the base eventType where the telemetry resides (partial string match on solarwinds_), and a specific attribute used to filter the telemetry down further (npm.Category). In other words, the following NRQL equivalent showcases how guids are generated by the criteria specified:

SELECT uniques(npm.nodeId) FROM solarwinds_* where npm.Category = 2

Also, note the “other Entities” category that we placed this entity type into. Any entity type that’s not native to the New Relic platform will get placed into this category.

Other notable configurations within the definition file:

• Tags: These are key-value pairs that exist within the telemetry, that can be stamped onto each unique entity as tags.
• entityExpirationTime: A timeout that expires the entity from the UI, if no data appears in that time frame defined.
• Alertable: If the entities generated will allow for alerts to be attached to it, and thus change its status.

Lifecycle: If your entity stops reporting data, how long should the New Relic platform keep the entity present? The default is eight days and can be adjusted per entity type.

Step 3: Define golden metrics (golden_metrics.yml)

This file is used to define what metrics are exhibited on the summary view for each unique entity (when clicked on) and queries that define them. These are typically top indicators for a given entity to track overall health and performance.

golden_metrics.yml example

Step 4: Define summary metrics (summary_metrics.yml) 

Using the same previous entity type as an example, here the summary_metrics.yml file defines which key metrics we want to appear in the List view of Entity Explorer. Similar to golden metrics, these are important KPIs that are the most useful to see in a snapshot view and are typically defined 1-1 with the golden metrics. Any telemetry that exists within a data set can be configured as a summary metric.

Summary_metrics.yml example

Summary View example

This view is perfect for quickly comparing the instances of your entity type against one another. The view also provides alert status, which quickly allows for identifying problematic nodes. As noted in the Introduction, once the New Relic platform recognizes any data as an entity type and at least one alert has been created against that entity, the alert status for that entity is visualized in various places of the UI, as shown in the example above.

Step 5: Define summary dashboard (dashboard.json)

Finally, a drill down dashboard is defined, which depicts any key metrics that are useful for tracking performance and overall health for a given entity type. Typically, we recommend that you create these dashboards ahead of time (under Dashboards), and then export them into a JSON format, and then scrub the JSON to remove hardcoded account IDs and other account-specific data. A sanitization tool is included within the entity-definitions repo to easily do this. Please see the example below as a reference.

dashboard.json example

Entity dashboard view example

The json schema for the dashboard.json file is exactly the same as the standard New Relic dashboard schema. This is where a standard dashboard with critical signals for a given entity is defined. This view also provides the alert status of the entity, activity stream (alert activity), and any related entities (for example, upstream/downstream services).

Step 6: Check in branch and create a pull request

Once all four files are validated/completed, you can commit the branch, push it, and create a pull request so that it can be merged into the main branch (or submit a PR against your fork). The typical turnaround time for review and merge is one to two weeks.

Conclusion

You can turn any data that’s ingested into New Relic—even if it’s not classified or stamped with an entity guid—into entities. Synthesizing raw telemetry has many advantages, including:

• The framework for creating custom entities is straightforward to use due to its configuration-based nature.
• Any telemetry, including events or metrics, sent to New Relic can be synthesized into entities for better curated experiences.
• Synthesized data (entities) promotes an overall better experience for viewing and alerting on key telemetry.
• Ability to tie multiple entities associate together and correlate their states in time. 

When you have more insight at the entity level, you can more easily monitor and troubleshoot your system.