GraphQL 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. Adding, deleting, or modifying your tags is done through the GraphQL API. The GraphQL API allows you to tag your entities with a key and an associated list of values.

For more on querying entities, see Use New Relic GraphQL API to query entities.

To construct these queries and see responses, you can use the New Relic GraphQL Explorer.

Read tags for an entity

Use the tag API to read the existing tags and their values. Use entitySearch() to find the entity and then fetch its tags. 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 GraphQL Explorer to experiment with queries.

Add tags for an entity

Use the API to add new tags for an entity. To add a tag:

  1. Locate the GUID for the entity you want to tag. You can fetch the GUID using entitySearch().

  2. 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

You can delete a tag and all of its associated values from an entity.

To remove a tag:

  1. Locate the GUID for the entity you want to remove the tag from. You can fetch the GUID using entitySearch().

  2. 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.

To delete tag values:

  1. Locate the GUID for the entity you want to remove the tag from. You can fetch the GUID using entitySearch().

  2. 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

You can replace all the existing values for a tag with new ones.

To replace all tag values:

  1. Locate the GUID for the entity you want to remove the tag from. You can fetch the GUID using entitySearch().

  2. 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

Recommendations for learning more: