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.
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.
When true, this closes all currently open violations when no signal is heard within the expiration_duration
time.
The default is False
.
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
.
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
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
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.
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
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.
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
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.
This is the value used by the fill_option
custom value. The default is 0
.
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
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.
For Plugin conditions this is the metric, which has been defined in a plugin, that will be used to trigger a notification.
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.
| Parameter |
---|---|
apm_app_metric |
|
apm_kt_metric |
|
browser_metric |
|
browser_metric_baseline |
|
mobile_metric |
|
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.
| Parameter |
---|---|
apm_external_service |
|
apm_app_metric_baseline |
|
mobile_external_service |
|
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
This is the GUID of the Synthetic monitoring to alert on.
Used for:
- Synthetic monitoring conditions
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
This is the NRQL query that alerts monitors as part of a NRQL condition.
Used for:
- NRQL conditions
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
When true, this opens a loss of signal violation when no signal within the expiration_duration
time.
The default is False
.
This is the GUID of the plugin for which the trigger is being defined.
Used for:
- Plugin conditions
This is the ID of the plugin for which the trigger is being defined.
Used for:
- Plugin conditions
The runbook URL to display in notifications. This field is optional.
Used for:
- Conditions
- External service conditions
- Synthetic monitoring conditions
- Plugin conditions
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
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
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
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
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
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 :
For this category, type is set to one of the following strings indicating the type of alerts condition.
| 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
For this category, type is set to one of the following strings indicating the type of external service condition.
| 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
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
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
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)
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
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
For more help
If you need more help, check out these support and learning resources:
- Browse the Explorers Hub to get help from the community and join in discussions.
- Find answers on our sites and learn how to use our support portal.
- Run New Relic Diagnostics, our troubleshooting tool for Linux, Windows, and macOS.
- Review New Relic's data security and licenses documentation.