NerdGraph tagging API tutorial

New Relic One provides unified access to all the entities you monitor with New Relic. Tags are used to organize and group all your entities in a way that's useful for troubleshooting and understanding your environment. To add, delete, or modify your tags, use the NerdGraph GraphiQL explorer. NerdGraph allows you to tag your entities with a key and an associated list of values.

Read tags for an entity

To construct these queries and see responses:

1. Go to the NerdGraph GraphiQL explorer at https://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 https://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.

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 One 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 https://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.

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 https://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 all the existing values for a tag with new ones:

1. Go to the NerdGraph GraphiQL explorer at https://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
            }
        }
}

For more help