NerdGraph tutorial: View and add tags

You can use our NerdGraph API to add tags 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, see How tags are added. For how to automate tags using our CLI tool, see our developer site.

Read tags for an entity

To construct these queries and see responses:

1. Go to the NerdGraph GraphiQL explorer at api.newrelic.com/graphiql.
2. Use entitySearch() 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 called Cookie Checkout:

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

The actual values vary depending on your data. Use the New 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 at api.newrelic.com/graphiql.
2. Use entitySearch() to locate the GUID for the entity you want to tag.
3. Use the taggingAddTagsToEntity mutation to add a tag with a value to the entity.
4. For APM agents, a restart is required after adding a new tag.

In this example, we have a browser application called Cookie Checkout owned by a UI team. We want to add a team tag with a ui value to this instance. Once the tag is added, we can filter by the tag team:ui and find the Cookie 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 at api.newrelic.com/graphiql.
2. Use entitySearch() to locate the GUID for the entity with the tag you want to remove.
3. Use the taggingDeleteTagFromEntity mutation.
4. For APM agents, a restart is required after changing tags.

The following example mutation removes the team 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 at api.newrelic.com/graphiql.
2. Use entitySearch() to locate the GUID for the entity with the tag you want to remove.
3. Use the taggingDeleteTagValuesFromEntity mutation.

The following example mutation deletes the ui value from the tag key:

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

Because tagValues 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 at api.newrelic.com/graphiql.
2. Use entitySearch() to locate the GUID for the entity with the tag you want to remove.
3. Use the taggingReplaceTagsOnEntity mutation.

In this example, the Cookie Checkout browser application was transferred from the ui team to the cookie-dev team. You can replace the tag values for team with the following mutation:

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