You can use ourNerdGraph API to addtags to your data to help improve data organization and findability.

Overview

This doc explains how to use our NerdGraph API to add and manage tags. Note that this is only one way to add tags. For other methods, seeHow tags are added. For how to automate tags using our CLI tool, see ourdeveloper site.

Read tags for an entity

To construct these queries and see responses:

1. Go to the NerdGraph GraphiQL explorer atapi.newrelic.com/graphiql.
2. UseentitySearch() to find the entity and then fetch its tags.
3. Use NerdGraph's tag API to read the existing tags and their values.

In this example, our entity is a browser app calledCookie Checkout:

{
actor{
entitySearch(query:"name like 'Cookie Checkout'"){
results{
entities{
tags{
key
values
}
}
}
}
}
}

The actual values vary depending on your data. Use theNew Relic GraphiQL explorer to experiment with queries.

Add tags for an entity

To add new tags for an entity:

1. Go to the NerdGraph GraphiQL explorer atapi.newrelic.com/graphiql.
2. UseentitySearch() to locate the GUID for the entity you want to tag.
3. Use thetaggingAddTagsToEntity mutation to add a tag with a value to the entity.
4. ForAPM agents, a restart is required after adding a new tag.

In this example, we have a browser application calledCookie Checkout owned by a UI team. We want to add ateam tag with aui value to this instance. Once the tag is added, we can filter by the tagteam:ui and find theCookie Checkout app in the New Relic UI.

mutation{
taggingAddTagsToEntity(
guid:"ENTITY_GUID"
tags:{key:"team",values:["ui"]}
){
errors{
message
}
}
}

Remove a tag from an entity

To delete a tag and all of its associated values from an entity:

1. Go to the NerdGraph GraphiQL explorer atapi.newrelic.com/graphiql.
2. UseentitySearch() to locate the GUID for the entity with the tag you want to remove.
3. Use thetaggingDeleteTagFromEntity mutation.
4. ForAPM agents, a restart is required after changing tags.

The following example mutation removes theteam tag from an entity:

mutation{
taggingDeleteTagFromEntity(guid:"ENTITY_GUID",tagKeys:["team"]){
errors{
message
}
}
}

Delete specific tag values for an entity

Instead of deleting an entire tag and all of its values, you can delete a single tag value.

1. Go to the NerdGraph GraphiQL explorer atapi.newrelic.com/graphiql.
2. UseentitySearch() to locate the GUID for the entity with the tag you want to remove.
3. Use thetaggingDeleteTagValuesFromEntity mutation.

The following example mutation deletes theui value from thetag key:

mutation{
taggingDeleteTagValuesFromEntity(
guid:"ENTITY_GUID"
tagValues:[{key:"team",value:"ui"}]
){
errors{
message
}
}
}

BecausetagValues is an array, you can delete multiple specific values from a single entity in one mutation.

Replace all tag values for an entity

To replace the entity’s entire set of tags with the provided tag set:

1. Go to the NerdGraph GraphiQL explorer atapi.newrelic.com/graphiql.
2. UseentitySearch() to locate the GUID for the entity with the tag you want to remove.
3. Use thetaggingReplaceTagsOnEntity mutation.

In this example, theCookie Checkout browser application was transferred from theui team to thecookie-dev team. You can replace the tag values forteam with the following mutation:

mutation{
taggingReplaceTagsOnEntity(
guid:"ENTITY_GUID"
tags:{key:"team",values:["cookie-dev"]}
){
errors{
message
}
}
}