Alerts conditions API field names

The New Relic Alerts API endpoints allow you to create conditions for your alert policies. This glossary contains the names and descriptions of each of the fields that may be used to define or update a condition.

Required and optional fields

The API includes four types of New Relic Alerts conditions:

  • APM
  • External services
  • Synthetics
  • Plugins

All of the fields used with a specific condition type are required except for these optional fields:

  • enabled (defaults to false)
  • runbook_url
  • user_defined

Field definitions

Not every field listed in this glossary is required for every condition type. The condition type for which a field must be used is listed in each description.

condition_scope

This field allows you to scope a condition to either a JVM instance or to a whole application. This may be one of the strings:

  • instance
  • application

Used for:

  • Alerts conditions
  • Alerts entity conditions

For instance-based and JVM health metrics, see also violation_close_timer.

enabled

This is the status of your alert condition and is optional. The default is false.

This field may be used to enable or disable a condition for maintenance or testing periods.

Used for:

  • Alerts conditions
  • Alerts external service conditions
  • Alerts Synthetics conditions
  • Alerts Plugin conditions
entities

This is an array of entity IDs identifying the objects which will be monitored with your condition. These may be application IDs, browser IDs, server IDs, plugin IDs, key transaction IDs, external service IDs, etc.

These are entered as a series of comma separated integers if there is more than one.

Used for:

  • Alerts conditions
  • Alerts external service conditions
  • Alerts Plugin conditions
external_service_url

This is the URL of the external service to be monitored. This string must not include the protocol. For example, use example.com, not https://example.com.

Used for:

  • Alerts external service conditions
metric

The metric field is used for three alert categories. The exact parameters available for use depend on the setting in the type field. These are listed below according to their alert type field.

Alerts plugin conditions

For Plugin conditions this is the metric, which has been defined in a plugin, that will be used to trigger an alert.

Alerts conditions

The value specified in the type field controls which of the parameters may be specified. The type field and corresponding available parameter names are listed in the following table. Only one may be specified.

type Parameter
apm_app_metric
  • apdex
  • error_percentage
  • response_time_web
  • response_time_background
  • throughput_web
  • throughput_background
  • user_defined
apm_kt_metric
  • apdex
  • error_percentage
  • error_count
  • response_time
  • throughput
servers_metric
  • cpu_percentage
  • disk_io_percentage
  • memory_percentage
  • fullest_disk_percentage
  • load_average_one_minute
  • user_defined
browser_metric
  • end_user_apdex
  • total_page_load
  • page_rendering
  • web_application
  • network
  • dom_processing
  • request_queuing
  • ajax_response_time
  • page_views_with_js_errors
  • page_view_throughput
  • ajax_throughput
  • user_defined
mobile_metric
  • database
  • images
  • json, network
  • view_loading
  • network_error_percentage
  • status_error_percentage
  • user_defined
Alerts external service conditions

The value specified in the type field controls which of the parameters may be specified. The type field and corresponding available parameter names are listed in the following table. Only one may be specified.

type Parameter
apm_external_service
  • apdex
  • error_percentage
  • response_time_web
  • response_time_background
  • throughput_web
  • throughput_background
  • user_defined
mobile_external_service
  • response_time_average
  • response_time_minimum
  • response_time_maximum
  • throughput
  • network_failure_percentage
  • http_status_error_percentage
metric_description

This is a title for the metric which is displayed in notifications.

Make this descriptive and unique so the reader will understand the nature of plugin metric being used to trigger an alert.

Used for:

  • Alerts Plugin conditions
monitor_id

This is the GUID of the Synthetics monitor to alert on.

Used for:

  • Alerts Synthetics conditions
name

This is a title for your condition and will allow to you identify it in the New Relics Alerts UI.

Follow the guidelines for making this descriptive but short.

Used for:

  • Alerts conditions
  • Alerts external service conditions
  • Alerts Synthetics conditions
  • Alerts Plugin conditions
nrql[query]

This is the NRQL query that New Relic Alerts monitors as part of a NRQL condition.

Used for:

  • Alerts Nrql conditions
nrql[since_value]

This is the timeframe (in minutes) in which to evaluate the specified NRQL query. It may be set to one of the following:

  • 1
  • 2
  • 3
  • 4
  • 5

Used for:

  • Alerts Nrql conditions
plugin[guid]

This is the GUID of the plugin for which the trigger is being defined.

Used for:

  • Alerts Plugin conditions
plugin[id]

This is the ID of the plugin for which the trigger is being defined.

Used for:

  • Alerts Plugin conditions
runbook_url

The runbook URL to display in notifications. This field is optional.

Used for:

  • Alerts conditions
  • Alerts external service conditions
  • Alerts Synthetics conditions
  • Alerts Plugin conditions
terms[duration]

This is the time (in minutes) for the condition to persist before triggering an event. It corresponds to the duration set when adding a threshold to an alert in the UI. It may be set to one of the following:

  • 5
  • 10
  • 15
  • 30
  • 60
  • 120

Used for:

  • Alerts conditions
  • Alerts external service conditions
  • Alerts Plugin conditions

When used for a NRQL condition, the options are:

  • 1
  • 2
  • 3
  • 4
  • 5
  • 10
  • 15
  • 30
  • 60
  • 120

terms[operator]

This determines what comparison will be used between the value_function and the terms[threshold] value to trigger an event. It corresponds to the operation selected when adding a threshold to an alert in the UI. It must be one of the following strings:

  • above
  • below
  • equal

Used for:

  • Alerts conditions
  • Alerts external service conditions
  • Alerts Plugin conditions
terms[priority]

This corresponds to the severity level selected when setting the threshold values for the condition in the UI. This must be one of the following strings:

  • critical
  • warning

Used for:

  • Alerts conditions
  • Alerts external service conditions
  • Alerts Plugin conditions
terms[threshold]

This is the threshold that the value_function must be compared to using the terms[operator] for an event to be triggered. It corresponds to the numeric value specified in the UI when adding the threshold values.

This is a numeric value and must be 0 (zero) or greater.

Used for:

  • Alerts conditions
  • Alerts external service conditions
  • Alerts Plugin conditions
terms[time_function]

This corresponds to the settings made in the UI when adding the threshold values. The choices are:

  • all (corresponding to for at least in the UI)
  • any (corresponding to at least once in in the UI)

Used for:

  • Alerts conditions
  • Alerts external service conditions
  • Alerts Plugin conditions
type

This defines the type of metric that will be used for the alert. Allowable content for the metric field depends on the type value chosen.

There are two New Relic product categories :

Alerts conditions

For this category, type is set to one of the following strings indicating the type of alerts condition.

type Use
apm_app_metric APM application metric will trigger an alert.
apm_kt_metric APM key transaction metric will trigger an alert.
servers_metric Server monitor metric will trigger an alert.
browser_metric Browser metric will trigger an alert.
mobile_metric

Mobile metric will trigger an alert.

Used for:

  • Alerts conditions
Alerts external service conditions

For this category, type is set to one of the following strings indicating the type of external service condition.

type Use
apm_external_service APM external metric will trigger an alert.
mobile_external_service Mobile external metric will trigger an alert.

Used for:

  • Alerts external service conditions
user_defined[metric] (optional)

This is the name of a user defined custom metric to be used to determine if an event should be triggered.

The user_defined[value_function] associated with the metric is compared with the terms[threshold] value when evaluating if an incident should be triggered. The comparison is performed using the operator defined by terms[operator].

Used for:

  • Alerts conditions
  • Alerts external service conditions
  • Alerts Synthetics conditions
  • Alerts Plugin conditions
user_defined[value_function] (optional)

This is the numeric value obtained from the custom metric specified by user_defined[metric].

It is compared with the terms[threshold] value when evaluating if an incident should be triggered. The comparison is performed using the operator defined by terms[operator].

One of these value functions must be specified:

  • average
  • min
  • max
  • total
  • sample_size

Used for:

  • Alerts conditions
value_function

This is the value function used from the plugin metric. This may be one of the strings:

  • min
  • max
  • average
  • sample_size
  • total
  • percent

Used for:

  • Alerts Plugin conditions

When used for a NRQL condition, the options are:

  • single_value (condition is evaluated based on each query's returned value)
  • sum (condition is evaluated based on the sum of each query's returned values over the specified duration)
violation_close_timer

Use to automatically close instance-based violations, including JVM health metric violations, after the number of hours specified. Must be one of these values:

  • 1
  • 2
  • 4
  • 8
  • 12
  • 24

Used only for Alerts conditions.

For more help

Additional documentation resources include

Recommendations for learning more: