REST API calls for infrastructure alerts

Use the infrastructure REST API to add, update, delete, and list alerting conditions. You can also manage individual alerting conditions using the infrastructure monitoring UI.

REST API calls for infrastructure alerts are not available in the API Explorer.

Why use the API	Examples
Consistency	Define the same set of conditions for every cluster without having to set up identical conditions in the Infrastructure monitoring UI each time. Manage multiple conditions quickly, without having to update them one by one using the UI.
Flexibility	Create conditions for an arbitrary group of hosts. Disable or delete conditions for hosts taken offline anytime. Create a condition with exclusionary filtering (for instance, `environment NOT LIKE x`). For more on this, see this post on exclusion filtering. For AWS Cloud integrations, select attributes that haven't been sent up by AWS yet. Create compound alert conditions by using the `where_clause`, which allows you to specify the limits on a secondary or tertiary metric. Exceed the 500-facet limitation on NRQL alert conditions.
Reliability	Audit when a condition was last updated.

Requirements

In order to use the Infrastructure REST API, you need:

A New Relic account. Don't have one? Sign up for free!. No credit card required.
An API key
The alerting condition's related policy_id from New Relic, available via GET list of conditions or via the alerts REST API
The condition id, available via GET list of conditions, or via the condition's URL in the Infrastructure monitoring UI

Tip

If your account hosts data in the EU data center, make sure you are using the proper API endpoints for EU region accounts.

Using infrastructure API calls

Here are some basic cURL commands and their responses for Infrastructure alert conditions. Depending on the type of condition, the DATA information you provide in the call will vary for POST (add) and PUT (update) calls.

Definitions of each attribute used in the data blocks can be found in the Definitions section.

GET infrastructure conditions

You can either GET a list of infrastructure conditions or GET a specific infrastructure condition. Here are a few tips for listing infrastructure conditions.

For pagination, use limit (records per page) and offset (how many records to skip) parameters. Default is 50 records per page, and offset starts at 0 (skip no records).
To scope the results to a specific policy, use policy_id.

Tip

If you want to use the GET response as a template for your PUT or POST input, be sure to remove the created_at_epoch_millis, updated_at_epoch_millis and id information.

GET a list of infrastructure conditions

curl -v -X GET --header "Api-Key: $API_KEY" "https://infra-api.newrelic.com/v2/alerts/conditions?policy_id=111111"

Response showing 2 of the 3 conditions for the example policy (formatted for readability and truncated):

HTTP/1.1 200 OK
Content-Length: 622
Content-Type: application/json

{
   "data":[
      {
         "type":"infra_process_running",
         "name":"Java is running",
         "enabled":true,
         "where_clause":"(`hostname` LIKE '%cassandra%')",
         "id":13890,
         "created_at_epoch_millis":1490996713872,
         "updated_at_epoch_millis":1490996713872,
         "policy_id":111111,
         "comparison":"equal",
         "critical_threshold":{
            "value":0,
            "duration_minutes":6
         },
         "process_where_clause":"(`commandName` = 'java')"
      },
      {
         "created_at_epoch_millis": 1501704525462,
         "critical_threshold": {
             "duration_minutes": 5
         },
         "enabled": true,
         "filter": {
            "and": [
                {
                     "like": {
                         "fullHostname": "Production_1"
                     }
                 }
             ]
         },
         "id": 448036,
         "name": "PROD - Host Machine's Agent Not Responding ....",
         "policy_id": 98485,
         "type": "infra_host_not_reporting",
         "updated_at_epoch_millis": 1504879191220
      }
     . . . 
   ],
   "meta":{
      "limit":50,
      "offset":0,
      "total":3
   },
   "links":{}
}

To get a list of the 10 Infrastructure conditions beyond the 50 limit:

curl -v -X GET --header "Api-Key: $API_KEY" "https://infra-api.newrelic.com/v2/alerts/conditions?policy_id=111111&offset=50&list=10"

GET a specific infrastructure condition

To get information about a single Infrastructure condition:

curl -v -X GET --header "Api-Key: $API_KEY" "https://infra-api.newrelic.com/v2/alerts/conditions/condition-id"

Response (formatted for readability):

HTTP/1.1 200 OK
Content-Length: 246
Content-Type: application/json

{
   "data":{
      "type":"infra_host_not_reporting",
      "name":"demo condition",
      "enabled":false,
      "id":13887,
      "created_at_epoch_millis":1490981583580,
      "updated_at_epoch_millis":1490981583580,
      "policy_id":23635,
      "critical_threshold":{
         "duration_minutes":100
      }
   }
}

Create (POST) an infrastructure condition

Important

Do not include an "id": when adding a new condition (POST). It will be generated when the condition is created.

To add an infrastructure condition, use this basic cURL command:

curl -X POST 'https://infra-api.newrelic.com/v2/alerts/conditions' -H 'Api-Key:$API_KEY' -i -H 'Content-Type: application/json' -d '{"data":{DATA object details}}'

Include details in the DATA object (-d \ section) for the type of infrastructure condition you are adding:

Process running conditions API data
Metric conditions API data
Host not reporting conditions API data

Update (PUT) an infrastructure condition

You only need to include the fields that need to be changed when updating an infrastructure condition. The API keeps the existing values for any missing fields.

Important

If you want to change the condition type, do not use PUT. Instead, delete the existing condition, then add (POST) a new condition with the new condition type and all fields.

To update an infrastructure condition, use this basic cURL command. To indicate which condition is to be updated, be sure to include the "id": .

Include details in the DATA object (-d \ section) for the type of infrastructure condition you are updating:

Process running conditions API data
Metric conditions API data
Host not reporting conditions API data

Remove (DELETE) an infrastructure condition

To delete an infrastructure condition, use this basic cURL command:

curl -v -X DELETE --header "Api-Key: $API_KEY" "https://infra-api.newrelic.com/v2/alerts/conditions/condition_id"

Types of conditions

A process running condition alerts you when the number of processes is above, below, or equal to the threshold you define. To add (POST) or update (PUT) a process running condition, use your API key, and refer to the definitions to customize your values in the API call.

For example:

curl -X POST 'https://infra-api.newrelic.com/v2/alerts/conditions' -H 'Api-Key:$API_KEY' -i -H 'Content-Type: application/json' -d
'{
   "data":{
      "type":"infra_process_running",
      "name":"Java is running",
      "enabled":true,
      "where_clause":"(hostname LIKE '\''%cassandra%'\'')",
      "policy_id":policy_id,
      "comparison":"equal",
      "critical_threshold":{
         "value":0,
         "duration_minutes":6
      },
      "process_where_clause":"(commandName = '\''java'\'')"
   }
}'

Important

Note the extra single quotes escaping the single quote around the where_clause and process_where_clause

A metric condition alerts you when the metric of your choice is above, below, or equal to the threshold you define. This includes:

System metrics
Process metrics
Network metrics
Storage metrics
Cloud integration metrics
To add (POST) or update (PUT) a metric condition, use your API key, and refer to the definitions to customize your values in the API call.
If you are adding or updating a cloud integration alert condition:
For the event_type field, enter the event type generated by your selected cloud integration service (for example, ComputeSample for the AWS EC2 integration).
If you are setting up an alert condition on a cloud integration service that requires a provider value (for example, AWS RDS uses DatastoreSample with a provider value of RdsDbInstance or RdsDbCluster), you will need to add the "integration_provider" field and use the value that is appropriate for the service your alert condition is targeting (for example, "integration_provider":"RdsDbInstance").

For the select_value field, build the metric name by using the following syntax, where provider is a standard prefix string:

provider.metric.aggregation_type

metric: Use the metric name as described in the New Relic documentation for your integration.
aggregation_type: Use Sum, Average, Minimum, or Maximum. Refer to the original documentation by the integration's cloud provider to see which statistic aggregations are available for each metric.

For example:

curl -X POST 'https://infra-api.newrelic.com/v2/alerts/conditions' -H 'Api-Key:$API_KEY' -i -H 'Content-Type: application/json' -d
'{
   "data":{
      "type":"infra_metric",
      "name":"Disk Space Condition",
      "enabled":true,
      "where_clause":"(hostname LIKE '\''%cassandra%'\'')",
      "policy_id":policy_id,
      "event_type":"StorageSample",
      "select_value":"diskFreePercent",
      "comparison":"below",
      "critical_threshold":{
         "value":10,
         "duration_minutes":1,
         "time_function":"any"
      },
      "warning_threshold":{
         "value":30,
         "duration_minutes":2,
         "time_function":"any"
      }
   }
}'

Important

Note the extra single quotes escaping the single quote around the where_clause

A host not reporting condition alerts you when a host stops reporting. To add (POST) or update (PUT) a host not reporting condition, use your API key, and refer to the definitions to customize your values in the API call.

The no_trigger_on field is optional. When set to ["shutdown"] this enables the Don't trigger alerts for hosts that perform a clean shutdown infrastructure condition option.

For example:

curl -X POST 'https://infra-api.newrelic.com/v2/alerts/conditions' -H 'Api-Key:$API_KEY' -i -H 'Content-Type: application/json' -d
'{
   "data":{
      "type":"infra_host_not_reporting",
      "name":"Cassandra Host Reporting Condition",
      "enabled":true,
      "where_clause":"(hostname LIKE '\''%cassandra%'\'')",
      "policy_id":policy_id,
      "critical_threshold":{
         "duration_minutes":12,
         "no_trigger_on": ["shutdown"]
      }
   }
}'

Important

Note the extra single quotes escaping the single quote around the where_clause

Definitions

When formatting your cURL commands, use these values as needed. These are listed in alphabetical order, not the order they appear in your API calls.

Field	Definition
`comparison` (enum)	Condition type: `infra_metric`, `infra_process_running` The value used to define the threshold; for example, `"["above", "below", "equal"]`.
`critical_threshold` and `warning_threshold`	Condition type: all This object identifies the threshold value before opening a violation. The `critical_threshold` is required. The `warning_threshold` is optional and may only be used with `infra_metric` conditions. The keys of this object depend on the condition type. Condition type: `infra_metric` format: `"critical_threshold":{ "value":<number>, "duration_minutes":<integer>, "time_function":"any" or "all" },` Condition type: `infra_process_running` format: `"critical_threshold":{ "value":<integer>, "duration_minutes":<integer>, },` Condition type: `infra_host_not_reporting` format: `"critical_threshold":{ "duration_minutes":<integer>, },`
`enabled` (boolean)	Condition type: all Whether the condition is turned on or off; `true` or `false`.
`event_type` (string)	Condition type: `infra_metric` The metric event; for example, system metrics, process metrics, storage metrics, or network metrics. This automatically populates for infrastructure integrations; for example, `StorageSample` or `SystemSample`.
`filter` (string)	Condition type: all If the condition was made in the UI, `filter` appears instead of `where_clause`; for example: `{and: [{is: {ec2InstanceType: "m3.medium"}}]}` Recommendation: Use `where_clause` when creating a new condition.
`id` (integer)	Condition type: all The condition ID located in the URL. GET: This value appears in the GET response. PUT: Include this value in the `DATA` section. POST: Do not include this in the `DATA` section. DELETE: Include this value in the `-X DELETE` call.
`integration_provider` (string)	Condition type: `infra_metric` For alerts on integrations, use `integration_provider` instead of `event_type`. To see valid values: From the New Relic documentation for your cloud service, check the Find and use data section. Example: In the AWS RDS monitoring integration documentation, you can see that the `DatastoreSample` event type can be used with an `integration_provider` value of either `RdsDbInstance` for DB instances, or `RdsDbCluster` for Aurora DB clusters.
`name` (string)	Condition type: all The infrastructure alerting condition's name; for example: `"[test] process running"`
`policy_id` (integer)	Condition type: all The unique ID for the alert policy's account ID associated with the condition; for example, `1234567890`. This is not the policy's global ID.
`process_where_clause` (string)	Condition type: `infra_process_running` Any filters applied to processes, specifically in process running alert conditions. This parameter is mandatory for those types of alert conditions. For example: `"commandName = '\''java'\''"`
`runbook_url` (string)	Condition type: `all` The runbook URL to display in notifications.
`select_value` (string)	Condition type: `infra_metric` The attribute name to identify the metric being targeted; for example, `"cpuPercent"`, `"diskFreePercent"`, `"memoryResidentSizeBytes", or "memoryFreeBytes/memoryTotalBytes*100"`. This automatically populates for Infrastructure Integrations; for example, `diskFreePercent`.
`type` (enum)	Condition type: all The type of infrastructure alert condition: `"infra_process_running"`, `"infra_metric"`, or `"infra_host_not_reporting"`.
`violation_close_timer` (integer)	Condition type: all The Violation time limit setting, expressed as hours. Possible values are `0`, `1`, `2`, `4`, `8`,`12`, `24`, `48`, `72`. This determines how much time will pass before a violation is automatically closed. For new conditions, if a value is not provided, the following default values are used: All conditions: `24 hours` When updating existing conditions, if a value is provided, it overrides the existing value, but does not affect already opened violations.
`where_clause` (string)	Condition type: all If applicable, this identifies any infrastructure host filters used; for example: "(`hostname` LIKE '\''%cassandra%'\'')",

REST API calls for infrastructure alerts

Requirements

Tip

Using infrastructure API calls

GET infrastructure conditions

Tip

GET a list of infrastructure conditions

Example GET a list of conditions

GET a specific infrastructure condition

Example GET a specific condition

Create (POST) an infrastructure condition

Important

Update (PUT) an infrastructure condition

Important

Example update (PUT) a condition

Remove (DELETE) an infrastructure condition

Types of conditions

Process running conditions API data

Example condition types

Important

Metric conditions API data

Example

Important

Host not reporting condition

Example

Important

Definitions

`value`

`duration_minutes`

`time_function`