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 tofalse
)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
andCustom 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 is0
. - 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
- all (corresponding to
- 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
(withcondition_scope
set toinstance
)apm_jvm_metric