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 |
|
Flexibility |
|
Reliability |
|
Requirements
In order to use the Infrastructure REST API, you need:
- 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
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) andoffset
(how many records to skip) parameters. Default is 50 records per page, andoffset
starts at 0 (skip no records). - To scope the results to a specific policy, use
policy_id
.
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"
- Example GET a list of conditions
-
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":{ "next":"infra-api.newrelic.com/v2/alerts/conditions?limit=1\u0026offset=50\u0026policy_id=111111" } }
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"
- Example GET a specific condition
-
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
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.
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":
.
- Example update (PUT) a condition
-
curl -X PUT 'https://infra-api.newrelic.com/v2/alerts/conditions/condition-id' -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 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
- Process running conditions API data
-
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.
- Example condition types
-
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'\'')" } }'
Note the extra single quotes escaping the single quote around the
where_clause
andprocess_where_clause
- Metric conditions API data
-
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 aprovider
value ofRdsDbInstance
orRdsDbCluster
), 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, whereprovider
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
: UseSum
,Average
,Minimum
, orMaximum
. Refer to the original documentation by the integration's cloud provider to see which statistic aggregations are available for each metric.
- Example
-
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" } } }'
Note the extra single quotes escaping the single quote around the
where_clause
- Host not reporting condition
-
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.
- Example
-
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 } } }'
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 |
---|---|
|
Condition type: The value used to define the threshold; for example, |
|
Condition type: all This object identifies the threshold value before opening a violation.
The keys of this object depend on the condition type. Condition type: "critical_threshold":{ "value":<number>, "duration_minutes":<integer>, "time_function":"any" or "all" }, Condition type: "critical_threshold":{ "value":<integer>, "duration_minutes":<integer>, }, Condition type: "critical_threshold":{ "duration_minutes":<integer>, },
|
|
Condition type: all Whether the condition is turned on or off; |
|
Condition type: The metric event; for example, system metrics, process metrics, storage metrics, or network metrics. This automatically populates for infrastructure integrations; for example, |
|
Condition type: all If the condition was made in the UI, {and: [{is: {ec2InstanceType: "m3.medium"}}]} Recommendation: Use |
|
Condition type: all The condition ID located in the URL.
|
|
Condition type: For alerts on integrations, use DatastoreSample event type can be used with an integration_provider value of either RdsDbInstance for DB instances, or RdsDbCluster for Aurora DB clusters. |
|
Condition type: all The infrastructure alerting condition's name; for example: "[test] process running" |
|
Condition type: all The unique ID for the alert policy's account ID associated with the condition; for example, |
|
Condition type: 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'\''" |
|
Condition type: The runbook URL to display in notifications. |
|
Condition type: The attribute name to identify the metric being targeted; for example, |
|
Condition type: all The type of infrastructure alert condition: |
|
Condition type: all The Violation time limit setting, expressed as hours. Possible values are For new conditions, if a value is not provided, the following default values are used:
|
|
Condition type: all If applicable, this identifies any infrastructure host filters used; for example: "(`hostname` LIKE '\''%cassandra%'\'')", |