Skip to main content
Skip table of contents

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.

Tags

Create custom tags for monitors. This allows you to filter alerts using tags in the Overview dashboard and in the Webhooks integration. Currently, there is a maximum of ten tags per monitor.

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:

  1. 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.

CODE
devices
| with device_performance.system_crashes during past 7d 
| compute total_number_of_system_crashes = number_of_system_crashes.sum()
CODE
execution.crashes during past 24h
| summarize total_number_of_crashes = count()

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

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

  1. 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:

CODE
devices
| with antiviruses
| where is_up_to_date == no

Compatible with monitors:

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

  1. 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:

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

Correct monitor NQL query with conditions:

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

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

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

  1. 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.

CODE
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.

Trigger conditions

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

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:

CODE
<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.


RELATED TOPICS

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.