You can manage alerts conditions using our GraphQL NerdGraph API. Here are some conditions queries and mutations you can develop in our NerdGraph API explorer.
See the NerdGraph introduction for help getting started with NerdGraph API explorer.
This document covers the following:
- Steps to create a NRQL condition
- NRQL static condition
- NRQL baseline condition
- NRQL outlier condition
- Update a condition
- Update mutations
- List and filter NRQL conditions
- Singular NRQL condition queries
- Create a description
- Delete conditions
Steps to create a NRQL condition
Follow these steps:
-
Decide which condition type you want to create (see NRQL Condition threshold types).
-
Find your relevant
policyID
by doing one of the following:- Use the NerdGraph policies API.
- Go to one.newrelic.com, in the top nav click Alerts & AI, then click Policies. Choose a policy. Find the ID under the policy name.
-
Provide the appropriate mutation for your NRQL condition type and the relevant values.
The NerdGraph GraphiQL explorer is the best place to find up-to-date documentation about the per-field specifics of the NerdGraph NRQL Conditions API. For example, questions like "What does the valueFunction
field accept?" are best answered with the inline NerdGraph documentation.
NRQL static condition
Here's an example of creating a static condition:
mutation { alertsNrqlConditionStaticCreate(accountId: YOUR_ACCOUNT_ID, policyId: YOUR_POLICY_ID, condition: { name: "Low Host Count - Catastrophic" enabled: true nrql: { query: "SELECT uniqueCount(host) from Transaction where appName='my-app-name'" } signal: { aggregationWindow: 60 evaluationOffset: 3 } terms: { threshold: 2 thresholdOccurrences: AT_LEAST_ONCE thresholdDuration: 600 operator: BELOW priority: CRITICAL } valueFunction: SINGLE_VALUE violationTimeLimitSeconds: 86400 }) { id name } }
NRQL baseline condition
Here's an example of creating a baseline condition:
mutation { alertsNrqlConditionBaselineCreate(accountId: YOUR_ACCOUNT_ID, policyId: YOUR_POLICY_ID, condition: { name: "Baseline Condition" enabled: true baselineDirection: UPPER_ONLY nrql: { query: "SELECT average(duration) FROM Transaction" } signal: { aggregationWindow: 60 evaluationOffset: 3 } terms: { threshold: 13 thresholdDuration: 180 thresholdOccurrences: ALL operator: ABOVE priority: CRITICAL } violationTimeLimitSeconds: 86400 }) { id name baselineDirection } }
NRQL outlier condition
Here's an example of creating an outlier condition:
mutation { alertsNrqlConditionOutlierCreate(accountId: YOUR_ACCOUNT_ID, policyId: YOUR_POLICY_ID, condition: { name: "Outlier Condition" enabled: true expectedGroups: 4 openViolationOnGroupOverlap: false nrql: { query: "SELECT average(duration) FROM Transaction FACET httpResponseCode" } signal: { aggregationWindow: 60 evaluationOffset: 3 } terms: { threshold: 1 thresholdDuration: 300 thresholdOccurrences: ALL operator: ABOVE priority: CRITICAL } violationTimeLimitSeconds: 86400 }) { id name expectedGroups openViolationOnGroupOverlap } }
Update a condition
Complete the following:
-
Determine the type of your existing condition by requesting the type field in a
nrqlConditionsSearch
query like this:{ actor { account(id: YOUR_ACCOUNT_ID) { alerts { nrqlConditionsSearch { nrqlConditions { id type } } } } } }
The
type
returned is what you use for your update mutation. For example, if the type returned isSTATIC
, usealertsNrqlConditionStaticUpdate
. If the type returned isBASELINE
, usealertsNrqlConditionBaselineUpdate
. If the type returned isOUTLIER
, usealertsNrqlConditionOutlierUpdate
. - Provide the
id
of your condition to your relevant condition type mutation. Note that you can only update conditions of the relevant type.
Only provide update mutations for the fields you want to update. Fields you don't provide in the update are not touched.
Update mutations
Only fields that you provide in the update are changed. In the following example, baselineDirection
returns unchanged, but name
is updated.
mutation { alertsNrqlConditionBaselineUpdate(id: YOUR_CONDITION_ID, accountId: YOUR_ACCOUNT_ID, condition: { name: "Your updated name" }) { id name baselineDirection } }
List and filter NRQL conditions
To list or filter your NRQL conditions, use the nrqlConditionsSearch
query in NerdGraph.
- Use cursor pagination
-
The basic of list functionality for NRQL conditions allows you to paginate through your NRQL conditions as well as request the total count of conditions per account.
The
nrqlConditionsSearch
query utilizes cursor pagination to paginate through resources. The idea behind cursor pagination is that the client will request a cursor in a programmatic loop until the cursor comes back empty.An initial list response will look something like this:
{ actor { account(id: YOUR_ACCOUNT_ID) { alerts { nrqlConditionsSearch { nextCursor nrqlConditions { id name type } totalCount } } } } }
This example returns a JSON response like this:
{ "data": { "actor": { "account": { "alerts": { "nrqlConditionsSearch": { "nextCursor": "WOwfJ4+TWm9QTFeKMGyg+w==:QqkI8S4+Wwnpno6z+uk8kQ==", "nrqlConditions": [ { "id": "4432", "name": "Baseline Condition", "type": "BASELINE" }, { "id": "443", "name": "A static condition", "type": "STATIC" }, // more conditions here in reality ], "totalCount": 435 } } } } }, }
In order to paginate through conditions in the response, have the client request the cursor to be returned until the
nextCursor
returns from the response asnull
:{ actor { account(id: YOUR_ACCOUNT_ID) { alerts { nrqlConditionsSearch(cursor: "WOwfJ4+TWm9QTFeKMGyg+w==:QqkI8S4+Wwnpno6z+uk8kQ==", ) { nextCursor nrqlConditions { id name type } totalCount } } } } }
- Request type-specific fields
-
Certain fields are only available on specific NRQL condition types. The main reason that mutations are split between the different condition types is because they have minor differences between the fields they accept.
For example,
valueFunction
is only relevant for static NRQL conditions andbaselineDirection
is only relevant on baseline NRQL conditions.But if these fields are only available on these certain condition types, how do we return them in a list of all of our condition types? The answer is a GraphQL convention known as inline fragments. Inline fragments allow you to access the data on a specific type of NRQL condition:
{ actor { account(id: YOUR_ACCOUNT_ID) { alerts { nrqlConditionsSearch { nrqlConditions { id name type ...on AlertsNrqlStaticCondition { valueFunction } ...on AlertsNrqlBaselineCondition { baselineDirection } ...on AlertsNrqlOutlierCondition { expectedGroups } } } } } } }
In the previous example query, we are asking GraphQL to do the hard work for us to determine which NRQL conditions are the correct type.
So, when the returned type is a static condition, it will return the
valueFunction
in the object. When the returned type is a baseline condition, it will returnbaselineDirection
instead, and when the type is an outlier condition, it will returnexpectedGroups
. Here is an example response:{ "data": { "actor": { "account": { "alerts": { "nrqlConditionsSearch": { "nrqlConditions": [ { "baselineDirection": "UPPER_ONLY", "id": "342", "name": "My baseline condition", "type": "BASELINE" }, { "id": "553", "name": "My static condition", "type": "STATIC", "valueFunction": "SINGLE_VALUE" }, { "expectedGroups": 4, "id": "802", "name": "My outlier condition", "type": "OUTLIER" } ] } } } } } }
- Filter NRQL conditions
-
You can filter NRQL conditions with the
searchCriteria
argument of thenrqlConditionsSearch
query:Here's an example of filtering NRQL conditions with matching by name. This query returns NRQL conditions that match the provided name. Note that this match is case insensitive.
{ actor { account(id: YOUR_ACCOUNT_ID) { alerts { nrqlConditionsSearch(searchCriteria: { name: "Baseline Condition" }) { nrqlConditions { id name type } } } } } }
Singular NRQL condition queries
You can use the NRQL condition API to query for a singular condition. Run the nrqlCondition
query in the alerts namespace.
Similar to type specific fields on the nrqlConditionSearch
query, you can also use these inline fragments to request fields that are restricted to a NRQL condition type.
{ actor { account(id: YOUR_ACCOUNT_ID) { alerts { nrqlCondition(id: YOUR_CONDITION_ID) { id name ...on AlertsNrqlStaticCondition { valueFunction } } } } } }
Update the description
This will walk you through the procedure to create a description for a NRQL alert condition.
1. Get all the conditions for a policy:
{ actor { account(id: YOUR_ACCOUNT_ID) { alerts { nrqlConditions(policyId: YOUR_POLICY_ID) { nextCursor results { id name description enabled nrql { query } signal { aggregationWindow evaluationOffset } policyId runbookUrl terms { duration operator priority timeFunction threshold } type violationTimeLimitSeconds } } } } } }
2. Get the details for a single condition:
{ actor { account(id: YOUR_ACCOUNT_ID) { alerts { nrqlCondition(id: "YOUR_CONDITION_ID") { description id enabled name nrql { query } signal { aggregationWindow evaluationOffset } policyId runbookUrl terms { operator priority threshold thresholdDuration thresholdOccurrences } type violationTimeLimitSeconds } } } } }
3. Create a mutation with the description.
Here's an empty mutation template:
mutation { alertsNrqlConditionStaticUpdate(accountId: YOUR_ACCOUNT_ID, id: "YOUR_CONDITION_ID", condition: {description: ""}) { description } }
Here's an example mutation with an included example 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}}"}) { description } }
Delete conditions
You can use the alertsConditionDelete
mutation to delete any type of condition. You can only request the id
field on a delete mutation; for example:
mutation { alertsConditionDelete(accountId: YOUR_ACCOUNT_ID, id: YOUR_CONDITION_ID) { id } }