End of life notice: Synthetics labels and Synthetics/APM group by tag


Synthetics and APM are moving to New Relic One to provide a single platform for observability of your complex software systems. To do this we are unifying the tools you use to tag (or label) your services, applications, and monitors.

What is Happening?

Changes will be made in two different waves over the next couple of months:

After July 8th Synthetics labels and the Synthetics label API endpoint will be replaced by tags and the tags API.

  • We are replacing Synthetics labels with a new tag service that is incorporated into the New Relic One platform.
  • Tags allow you to report and visually segment data using NRQL queries.
  • New Relic One has additional features looking across all New Relic products that allow things to be grouped using tags.

One time migration (now until July 8th, 2020): Synthetics labels to tags migration
The Synthetics monitor listing page now displays an option to trigger a one time label to tag migration when toggling to display/hide labels.

  • Upon completing this migration all Synthetics labels will be migrated to tags (visible in New Relic One).
  • If you are using an API to manage Synthetics labels, you’ll need to update your service to call the Tags service moving forward (see FAQ for more details on this change).
  • Labels will continue to be displayed on the monitor listed pages, but will be read only.
  • Any updates you make in New Relic ONE or via the tag API will not be reflected in Synthetics.

Automated labels to tags migration (beginning week of July 8th, 2020): We will be migrating all remaining labels to tags beginning the week of July 8th. We expected this to take up to 2 weeks to migrate all accounts.

  • If you have already migrated your labels to tags, you will not be impacted by this change.
  • After an account has been migrated, the Synthetics labels API will no longer be available to manage labels. Tags can be managed using the tag API moving forward.

After July 20, 2020: The use of labels in the Synthetics and APM web user interfaces will be replaced by tags. Conceptually, labels and tags are very similar, but tags are available throughout the New Relic One platform, while labels have been available only for certain experiences.

“Rollups” (group by tag) on APM app listing page and Synthetics monitors listing page will be retired.

  • New entity listing experiences will allow you to search across accounts for APM apps and Synthetics monitors.
  • The Workloads concept can be used to create groups of entities by tag, including applications, services, and monitors (see more in the FAQ section below).


Synthetics will be adopting tags as we migrate to the New Relic One platform. Tags offer a versatile way to identify entities across the New Relic One platform. Many features leverage tags to automatically group entities showing the status of a group of entities (ex: Workloads can group APM, Browser, and Synthetics entities by tag).

What do I need to do?

No changes will be required to use the new Synthetics and APM entity listing pages. The new experiences will be available to you after July 20.

To recreate the rollups that are being retired, you can begin using Workloads today. Check in the FAQ whether Workloads suit your use case for rollups.

Migrate your Synthetics labels to tags

  • Synthetics administrators have the option to perform a one time ‘labels to tags’ migration. This can be done by logging into Synthetics and selecting the ‘show labels’ toggle. Upon completing the migration, labels will still be visible as ‘read only’ on the monitor listing pages.
  • To make changes to tags via API you’ll need to use the New Relic One tags service.
  • This can be done by updating API calls that currently use the Synthetics labels API to use the tags API moving forward.
  • See details on how to migrate below


How do I migrate my Synthetics labels to tags?

Login to the Synthetics monitor listing page and click the “Migrate your Synthetics monitor labels to New Relic One tags!” link:

Accept the labels to tag migration agreement

The job will take a couple of minutes to complete the migration from labels to tags. Upon completion the monitor listing page will reload. From this point forward labels will be read-only.

Update APIs that call the Synthetics label service. Moving forward these will need to call the New Relic One Tag service (doc).

Will the APM labels API continue to work?

Yes, you can continue to use the APM labels endpoint, but we encourage you to start planning to migrate to the tags endpoint. In the future we will be relying solely on the tags API to manage your tags across everything in New Relic One.

Learn more about the tags API in our documentation.

How can New Relic Workloads help me visualize groups of applications and monitors?

New Relic One Workloads gives you the ability to group and monitor entities based on a team or a set of responsibilities, from front-end to back-end services, across your entire stack. You can use workloads to group together applications, infrastructure, monitors and dashboards that are important to your specific team or project, so you can better browse and isolate the most relevant data for your services.

You can create a Workload automatically using your existing tags, and refine it manually by adding entities if need be. Any new matching entities are added dynamically. Then take advantage of the curated UI with:

  • Overview of entity health (and the global status of the workload coming soon!)
  • Specific metrics based on the need of different entity types
  • Related violations of alert conditions
  • Related dashboards
  • Connection to all the other tools available in New Relic

How do I pull in tags using NRQL instead of labels?

A NRQL against SyntheticCheck events using tags will feel quite similar to the deprecated labels syntax. All tags are prefixed in Insights events with the “tags” prefix followed by the tag key. Tags with a single value will be returned as a String. Tags with multiple values will be returned as single String delimited by the pipe character.

Tags can be utilized across SyntheticCheck events with the full power of Insights. You can use tags to filter your queries by including them in a where clause or facet metrics by a specified tag.

"event": {

"tags.exampleTag": "exampleValue|exampleValue2",

"tags.exampleTag2": "exampleValue",



For example:

select * from SyntheticCheck where tags.myTag = "myValue"


select * from SyntheticCheck where tags.MyTag like "%myValue"

How do I transition my scripts from the Synthetics API to the tag API (NerdGraph)?

Migrating from the Synthetics labels API to the tags API will require updates to the API request (the data structure is different).

  1. Review the docs to understand the current labels API vs tag API data structure.

  2. Identify which entities that you’d like to add a tag to.

  3. On New Relic ONE, monitors are defined as entities (along with APM app, Browser apps, etc). You’ll need to identify the Synthetics monitor that you want to add/delete a tag from and grab the entity GUID.

  4. To get the entity guid you can either copy it from the monitor summary page within New Relic One under the Metadata & Tags section for the monitor or you can retrieve it as the “entityId” field from the V5 monitor GET endpoint (e.g. /synthetics/api/v5/monitors/).

  5. Use the GUID to add/delete tags from the monitors.

  6. Using the tag API you will make a request to take the appropriate action on the GUIDs included in the API request.

mutation {
taggingAddTagsToEntity(guid: "NOTAREALGUIDlOVEh8TU9OSVRPUnw5ZmQwODdkMi1kYTYyLTQ4ZTktODFkMi1mYmY0ODFmNjlhMzA", tags: [{key: "testKey", values: ["testValue"]}]) {

Pro Tip: Use the New Relic One API explorer to establish the request and responses from the NerdGraph APIs.


Is the feature to add attributes to Insights data with $util.inisights affected by this change or will it continue to work?

1 Like

This will have no impact to how custom attributes are captured for Synthetics. You can continue to use $util.inisights.


Will using the NEW_RELIC_LABELS APM environment variable handle this change automatically?

Hi @harry.mitchinson I believe so yes but let me double check that for you :slight_smile:

Would be great to have an example on how to add multiple tags.

Edit - I have figured it out as per the sample below:

mutation {
taggingAddTagsToEntity(guid: "NOTAREALGUIDlOVEh8TU9OSVRPUnw5ZmQwODdkMi1kYTYyLTQ4ZTktODFkMi1mYmY0ODFmNjlhMzA", 
tags: [
    {key: "testKey", values: ["testValue"]}, 
    {key:"anotherTestKey", values:["anotherTestValue"]}
    ]) {

Glad you figured it out - thanks for sharing the G.QL Mutation :slight_smile:

1 Like

I’d also like to know if this is the case.

Because it either isn’t or I don’t know how to query for labels/tags using NRQL.

(I’m trying to SELECT ... FROM ... WHERE tags.<tag/label> = ... but nothing comes up - and it should)

Hey @flavio9

I’m not certain about APM, but I know for Synthetics that you can query tags

SELECT * FROM SyntheticCheck WHERE tags.myTagName = 'myTagValue'

Hi @rdouglas,

Did you get the chance to double check this? We are having memory issue for a nodejs app using APM. Just wanted to make sure that by any chance, this is not causing it.