Monitors

Proactively monitor your data in OpenSearch with features available in Alerting and Anomaly Detection. For example, you can pair Anomaly Detection with Alerting to ensure that you’re notified as soon as an anomaly is detected. You can do this by setting up a detector to automatically detect outliers in your streaming data and monitors to alert you through notifications when data exceeds certain thresholds.

Monitor types

The Alerting plugin provides the following monitor types:

  1. per query: Runs a query and generates alert notifications based on the matching criteria. See Per query monitors for information about creating and using this monitor type.
  2. per bucket: Runs a query that evaluates trigger criteria based on aggregated values in the dataset. See Per bucket monitors for information about creating and using this monitor type.
  3. per cluster metrics: Runs API requests on the cluster to monitor its health. See Per cluster metrics monitors for information about creating and using this monitor type.
  4. per document: Runs a query (or multiple queries combined by a tag) that returns individual documents that match the alert notification trigger condition. See Per document monitors for information about creating and using this monitor type.
  5. composite monitor: Runs multiple monitors in a single workflow and generates a single alert based on multiple trigger conditions. See Composite monitors for information about creating and using this monitor type.

The maximum number of monitors you can create is 1,000. You can change the default maximum number of alerts for your cluster by updating the plugins.alerting.monitor.max_monitors setting using the cluster settings API.

Monitor variables

The following table lists the variables available for customizing your monitors.

VariableData typeDescription
ctx.monitorObjectIncludes ctx.monitor.name, ctx.monitor.type, ctx.monitor.enabled, ctx.monitor.enabled_time, ctx.monitor.schedule, ctx.monitor.inputs, triggers and ctx.monitor.last_update_time.
ctx.monitor.userObjectIncludes information about the user who created the monitor. Includes ctx.monitor.user.backend_roles and ctx.monitor.user.roles, which are arrays that contain the backend roles and roles assigned to the user. See alerting security for more information.
ctx.monitor.enabledBooleanWhether the monitor is enabled.
ctx.monitor.enabled_timeMillisecondsUnix epoch time of when the monitor was last enabled.
ctx.monitor.scheduleObjectContains a schedule of how often or when the monitor should run.
ctx.monitor.schedule.period.intervalIntegerThe interval at which the monitor runs.
ctx.monitor.schedule.period.unitStringThe interval’s unit of time.
ctx.monitor.inputsArrayAn array that contains the indexes and definition used to create the monitor.
ctx.monitor.inputs.search.indicesArrayAn array that contains the indexes the monitor observes.
ctx.monitor.inputs.search.queryN/AThe definition used to define the monitor.

The following table lists other variables you can use with your monitors.

VariableData typeDescription
ctx.resultsArrayAn array with one element, for example, ctx.results[0]. Contains the query results. This variable is empty if the trigger was unable to retrieve results. See ctx.error.
ctx.last_update_timeMillisecondsUnix epoch time of when the monitor was last updated.
ctx.periodStartStringUnix timestamp for the beginning of the period during which the alert triggered. For example, if a monitor runs every 10 minutes, a period might begin at 10:40 and end at 10:50.
ctx.periodEndStringThe end of the period during which the alert triggered.
ctx.errorStringThe error message if the trigger was unable to retrieve results or unable to evaluate the trigger, typically due to a compile error or null pointer exception. Null otherwise.
ctx.alertObjectThe current, active alert (if it exists). Includes ctx.alert.id, ctx.alert.version, and ctx.alert.isAcknowledged. Null if no alert is active. Only available with query-level monitors.
ctx.dedupedAlertsObjectAlerts that have already been triggered. OpenSearch keeps the existing alert to prevent the plugin from creating endless amounts of the same alerts. Only available with bucket-level monitors.
ctx.newAlertsObjectNewly created alerts. Only available with bucket-level monitors.
ctx.completedAlertsObjectAlerts that are no longer ongoing. Only available with bucket-level monitors.
bucket_keysStringComma-separated list of the monitor’s bucket key values. Available only for ctx.dedupedAlerts, ctx.newAlerts, and ctx.completedAlerts. Accessed through ctx.dedupedAlerts[0].bucket_keys.
parent_bucket_pathStringThe parent bucket path of the bucket that triggered the alert. Accessed through ctx.dedupedAlerts[0].parent_bucket_path.