Alert custom violation descriptions

For some types of conditions, you can define a custom violation description that passes useful information downstream for better violation responses or for use by other systems. You can create a custom violation description in the UI or with NRQL.


The custom violation description feature is available for:

  • NRQL alert conditions
  • Infrastructure monitoring alert conditions

The custom violation description field has a maximum character size of 4000.

What is a custom violation description?

For some types of conditions, you can create a custom violation description that passes information about a condition and its violations downstream. Using a description, you can:

  • Capture the reason for the condition
  • Define the signal being monitored
  • Define next steps
  • Add metadata to downstream systems

The Custom violation description field allows you to use a general template structure that, when a violation is generated, substitutes the generic sections with specific values. For example, let's say you used this in a description:

This is my condition name : {{conditionName}}
The hostname is : {{tag.fullHostname}}

A violation resulting from this condition would fill in the details and you'd receive a notification like this:

This is my condition name : My Great Alert Condition
The hostname is :

Create a custom violation description

Screen capture of the alerts condition description field used to pass useful, custom information along.
In the top nav, click Alerts & AI, click Alert policies, (select a policy), then (select a condition): Click + Add custom violation description to open the field.

For a condition, you can create a custom violation description using this field.

Custom violation description template example

Here's a custom violation description template example:

this is my condition name : {{conditionName}}
The hostname is : {{tag.fullHostname}}
Owning Team: {{tag.label.owning_team}}
Product: {{tag.label.product}}
ec2VpcId: {{}}
Service name : {{tag.label.Name}}
AWS Region : {{}}
AWS Availability Zone: {{}}
Department : {{tag.label.department}}
Environment: {{tag.label.environment}}
Cluster: {{tag.clusterName}}
Cluster Role: {{tag.clusterRole}}
EC2 Instance Type: {{tag.instanceType}}
EC2 InstanceID: {{}}
EC2 AmiId: {{}}
EC2 Root Device Type: {{}}

Here's how that data might appear in a notification:

New Relic alert violation description

How to use attributes

The attributes you can use in a custom violation description are a subset of attributes attached to the violation event. Here are some details about the available attributes and how to use them:

  • Violation event attributes: For any of the standard attributes available for use in a custom violation description, use the format {{AN_ATTRIBUTE}}. For example:
    The target name is : {{targetName}}
  • Tag attributes: For tags, you would use the format {{tag.TAG_NAME}}. There are two types of tags:
    • Entity-related tags: For Infrastructure conditions only. You can find available entity-related tags by going to the New Relic One entity explorer and looking under a service's Metadata and tags, or by viewing violation details. Here's an example of using tags in a custom violation description:
      The AWS region is : {{}}
      Responsible team : {{tag.label.owning_team}}
    • Facet clause tags: For NRQL conditions only. If a NRQL condition uses a FACET clause, you can use tag formatting to use those values in your custom violation description. For example, if the NRQL query included FACET hostName, cluster, you could then use this:
      The host is : {{tag.hostName}}
      The cluster is : {{tag.cluster}}

Please note that tag names cannot include a whitespace. The expanded values can include a whitespace, but not the names of the tags themselves.

Create a custom violation description with NRQL

You can create a custom violation description using a NRQL alert condition by creating a mutation with a description.

Here's an empty mutation template:

    mutation {
     alertsNrqlConditionStaticUpdate(accountId: YOUR_ACCOUNT_ID, id: "YOUR_CONDITION_ID", condition: {description: ""}) {

Here's an example mutation with a custom violation description:

    mutation {
     alertsNrqlConditionStaticUpdate(accountId: 123456, id: "123456", condition: {description: "timestamp : {{timestamp}} \n accountId : {{accountId}} \n type : {{type}} \n event : {{event}} \n description : {{description}} \n policyId : {{policyId}} \n policyName: {{policyName}} \n conditionName : {{conditionName}} \n conditionId : {{conditionId}} \n product : {{product}} \n conditionType : {{conditionType}} \n RunbookUrl : {{runbookUrl}} \n nrqlQuery : {{nrqlQuery}} \n nrqlEventType : {{nrqlEventType}} \n targetID : {{targetId}} \n targetName : {{targetName}} \n commandLine : {{tag.commandLine}} \n entityGuid : {{tag.entityGuid}} \n entityName : {{tag.entityName}} \n fullHostname : {{tag.fullHostname}} \n instanceType : {{tag.instanceType}} \n processDisplayName : {{tag.processDisplayName}}"}) {

Mentioning users or notifying channel in Slack

When creating a description that you know will be sent to Slack, you may wish to @mention a user or generate a channel-wide notification (e.g. @here or @channel). To achieve this, simply include the User ID or a channel-wide notification in the description surrounded by < and > characters.

Here's an example for mentioning a user:

Attention <@LewCirne>

Here's an example for generating a channel-wide notification:

Attention <!channel>

Note that the Slack convention for channel-wide notifications in Incoming Webhooks is to use a ! prefix instead of @

e.g. !here or !channel

For more help

Recommendations for learning more:

If you need more help, check out these support and learning resources: