Creating custom monitors

Click on the New monitor button in the top-right corner of the page to create a new monitor from scratch.

Defining general information

Use the General tab to define the new monitor.

Type

Custom monitors offer one detection mode. The Metric threshold type compares the value of the NQL query-defined metric to a threshold defined by the user. For example, a monitor triggers an alert when 20% of devices running a binary experienced a crash.

Name

Provide a meaningful name for the monitor. The system uses this name to send notifications and visualize monitors on the Alerts overview page.

NQL ID

The system generates a unique identifier automatically from the monitor’s name. You can only modify the NQL ID during the monitor creation process using the following characters a-z, 0-9, _. You cannot edit this field once you have created the monitor. Use the NQL ID to query this monitor using NQL.

You cannot create a monitor with an NQL ID that was used by a deleted monitor until there are no events in the system still associated with the deleted monitor (30 days max).

Priority

Set the priority level. The default level is medium.

Defining an NQL query

Use an NQL query to define metrics to monitor. NQL facilitates the selection of one or multiple metrics, helps specify the scope with the where clause and defines the right granularity for the alert context using time aggregation and the by keyword for grouping. Use the Show in Investigations button to view the results of your NQL query in the Investigations module.

The NQL query must follow several rules to support monitors:

The NQL query for monitors must include a computed or aggregated metric, which means every query requires a compute or summarize clause to be compatible with a monitor.

devices
| with device_performance.system_crashes during past 7d 
| compute 
  total_number_of_system_crashes = number_of_system_crashes.sum()

execution.crashes during past 24h
| summarize total_number_of_crashes = count()

Optionally, include more than one computed or aggregated metric in your query to set multiple conditions for the alert to be triggered.

execution.crashes during past 24h
| summarize 
  total_number_of_crashes = count(), 
  devices_with_crashes = device.count()

Use at least one metric to set a threshold for monitoring conditions. Create an additional metric if your original query does not include one.

Not compatible with monitors:

devices
| with antiviruses
| where is_up_to_date == no

Compatible with monitors:

devices
| with antiviruses
| where is_up_to_date == no
| compute device_count = count()

Do not add conditions to evaluated metrics at the NQL level. Instead, use the Trigger condition section to define the condition.

Incorrect monitor NQL query:

execution.crashes during past 24h
| summarize total_number_of_crashes = count()
| where total_number_of_crashes >= 10

Correct monitor NQL query with conditions:

execution.crashes during past 24h
| summarize total_number_of_crashes = count()

Use the where clause to narrow the scope of your monitor to specific locations, applications and other categories.

execution.crashes during past 24h
| where binary.name == "excel.exe"
| summarize total_number_of_crashes = count()

Use summarize... by to define the right granularity for the alert context. In the following example, a single alert will be triggered per binary name.

execution.crashes during past 24h
| summarize total_number_of_crashes = count() by binary.name

Refer to the Detecting issues impacting multiple devices and Detecting issues impacting a single device or user documentation to learn more about defining the NQL query.

Defining Trigger conditions

Define the condition that triggers an alert. Use each metric computed in the NQL query to narrow down the condition.

Defining Scheduling frequency

The time interval determines how often the system evaluates the trigger condition. The possible values are 15 min, 1 hour, 3 hours, 6 hours, 12 hours, 24 hours, 48 hours and 7 days.

The scheduling frequency options depend on the during past value used in the NQL query.

When the during past value is 15min or 1h, the scheduling frequency can take any value possible from 15 min to 7 days.

If the during past value is higher than 1h, the minimum scheduling frequency is at least the during past value divided by 2. If the result does not exist in the possible values, the next highest value is available.

See the following examples:

The 'during past' value Minimum frequency Comment

The 'during past' value	Minimum frequency	Comment
24h	12 hours	24 divided by 2
48h	24 hours	48 divided by 2
72h	48 hours	The minimum frequency should be 72 divided by 2. As 36 hours does not exist in the drop-down menu of possible frequencies, the lowest frequency possible is 48 hours.
7d	7 days	With a `during past` value of `7d`, the minimum frequency is 7 days by default. Exceptionally, the minimum frequency of `1d` can be applied when one of the following conditions is met: The monitor query is based on event `device_performance.*` collections. Event-based query targets a smaller group of devices: `\| where device.<property> <up-to-20 values>` If the monitor query is: `<object> \| include <collection> during past 7d \| where device.<property> <up-to-20 values>` The minimum frequency is still 7d.

24h

12 hours

24 divided by 2

48h

24 hours

48 divided by 2

72h

48 hours

The minimum frequency should be 72 divided by 2. As 36 hours does not exist in the drop-down menu of possible frequencies, the lowest frequency possible is 48 hours.

7 days

With a during past value of 7d, the minimum frequency is 7 days by default. Exceptionally, the minimum frequency of 1d can be applied when one of the following conditions is met:

The monitor query is based on event device_performance.* collections.
Event-based query targets a smaller group of devices: | where device.<property> <up-to-20 values>

If the monitor query is:

<object> 
| include <collection> during past 7d
| where device.<property> <up-to-20 values>

The minimum frequency is still 7d.

Importing a custom monitor

One way to create monitors is by importing them from a previously exported configuration file.

The system does not allow the import of a monitor with the same NQL ID as a deleted monitor if there are events in the system still associated with that deleted monitor. Alert events are kept in the platform for 30 days maximum.

If the NQL ID is already used in deleted monitor with existing alerts message appears during the import of the monitor, please modify the export file to create a new NQL ID.