Alerts conditions API field names

The REST API endpoints allow you to create conditions for your policies. This glossary contains the names and descriptions of each of the fields that you can use to define or update a condition.

Required and optional fields

The API includes four types of New Relic Alerts conditions:

  • APM
  • External services
  • Synthetic monitoring
  • 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.

aggregation_window

Streaming alerts gathers data together into specific amounts of time before running the function in the NRQL query. These windows of time are customizable.

The default is 1 minute. The maximum is 15 minutes.

Data points are collected together based their timestamps and reported as a batch. The customizable aggregation window provides greater flexibility and fewer false violations when alerting on irregular or less frequent data points.

In the UI, under Advanced signal settings, this is the Aggregation window field.

close_violations_on_expiration

When true, this closes all currently open violations when no signal is heard within the expiration_duration time.

The default is False.

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:

  • Conditions
  • 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:

  • Conditions
  • External service conditions
  • Synthetic monitoring conditions
  • 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, 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:

  • Conditions
  • External service conditions
  • Plugin conditions
evaluation_offset

The offset is how long we wait for late data before evaluating each aggregation window. Waiting longer gives a more accurate signal but increases latency. The default is 3 minutes.

In the UI, under Advanced signal settings, this is the Offset evaluation by field.

expected_groups

This is the number of groups you expect to see at any given time. It is used in combination with the ignore_overlap option.

Used for:

  • NRQL outlier conditions
expiration_duration

How long to wait, in seconds, after the last data point is received by our platform before considering the signal as lost. This is based on the time when data arrives and not on data timestamps. The default is null. Add a value to enable loss of signal detection.

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:

  • External service conditions
fill_option

For sporadic data, you can avoid false alerts by filling the gaps (empty windows) with synthetic data. The default is None.

The other values are Last known value and Custom static value.

In the UI, under Advanced signal settings, this is the Fill data gaps with field.

fill_value

This is the value used by the fill_option custom value. The default is 0.

ignore_overlap

If disabled, this looks for a convergence (or overlapping) of groups. If the condition is looking for two or more groups, and the returned values can't be separated into that number of distinct groups, then that will also produce a violation. This type of overlap event is represented on a chart by group bands touching.

Used for:

  • NRQL outlier 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 a notification.

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
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
browser_metric_baseline
  • page_view_throughput
  • average_response_time
  • ajax_response_time
  • ajax_application_time
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
apm_app_metric_baseline
  • external_service_transaction_time
  • error_count
  • database_transaction_time
  • throughput_web
  • response_time_web
  • non_web_transaction_time
  • web_transaction_database_time
  • non_web_transaction_database_time
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:

  • Plugin conditions
monitor_id

This is the GUID of the Synthetic monitoring to alert on.

Used for:

  • Synthetic monitoring conditions
name

This condition title will allow to you identify it in the UI.

Follow the guidelines for making this descriptive but short.

Used for:

  • Conditions
  • External service conditions
  • Synthetic monitoring conditions
  • Plugin conditions
nrql[query]

This is the NRQL query that alerts monitors as part of a NRQL condition.

Used for:

  • NRQL conditions
nrql[since_value]

This is the timeframe (in minutes) in which to evaluate the specified NRQL query. since_value must be between 1 and 20.

Used for:

  • NRQL conditions
open_violation_on_expiration

When true, this opens a loss of signal violation when no signal within the expiration_duration time.

The default is False.

plugin[guid]

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

Used for:

  • Plugin conditions
plugin[id]

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

Used for:

  • Plugin conditions
runbook_url

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

Used for:

  • Conditions
  • External service conditions
  • Synthetic monitoring conditions
  • 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 in the UI.

Used for:

  • Conditions
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 in the UI. It must be one of the following strings:

  • above
  • below
  • equal

Used for:

  • Conditions
  • External service conditions
  • 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:

  • Conditions
  • External service conditions
  • 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:

  • Conditions
  • External service conditions
  • 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:

  • Conditions
  • External service conditions
  • 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 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_app_metric_baseline APM application metric will trigger an alert (using a baseline threshold).
apm_kt_metric APM key transaction metric will trigger an alert.
browser_metric Browser metric will trigger an alert.
browser_metric_baseline Browser metric will trigger an alert (using a baseline threshold).
mobile_metric

Mobile metric will trigger an alert.

Used for:

  • 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:

  • 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:

  • Conditions
  • External service conditions
  • Synthetic monitoring conditions
  • 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:

  • 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:

  • 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_time_limit_seconds

Use to automatically close instance-based violations after the number of seconds specified. Must be one of these values:

  • 3600
  • 7200
  • 14400
  • 28800
  • 43200
  • 86400

Used for:

  • Location conditions
  • NRQL conditions
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 for:

  • apm_app_metric (with condition_scope set to instance)
  • apm_jvm_metric

For more help

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