
= Step 5: Set up a Threshold
:description: Step 5 of {page-component-title} setup: set up and test a threshold, create and expression-based threshold, and threshold settings.

A threshold defines limits against the network performance metrics (CPU load, bandwidth, disk space, and so on) of a managed entity to trigger an xref:deep-dive/events/introduction.adoc[event] (record) when a datasource value goes above or below the specified limit.
The threshold types are as follows:

* *High:* Equals or exceeds the threshold value, and re-arms when it equals or drops below the re-arm value (for example, bandwidth use exceeds the specified limit).
* *Low:* Equals or drops below the threshold value and re-arms when it equals or comes back up above the re-arm value (for example, available disk space falls under the specified value).
* *Absolute change:* Changes by the specified amount (for example, on a fiber-optic link, a change in loss of anything greater than 3 dB is a problem regardless of what the original or final value is).
* *Relative change:* Changes by a specified percentage (for example, available disk space changes by more than 5% from the last poll).

These thresholds can be basic (tested against a single value) or expression-based (evaluated against multiple values in an expression).
This Quick Start guide shows how to create both kinds of threshold.

[[threshold-basic]]
== Create a basic threshold

This procedure describes how to create a basic threshold for a single, system-wide variable: the number of logged-in users.
This threshold tells {page-component-title} to create an event when the number of logged-in users on the device exceeds two, and re-arm when it falls below two.

. Click menu:Administration[Configure OpenNMS] in the side menu.
. Under Performance Measurement, click *Configure Thresholds*.
A list of preconfigured threshold groups appears.
+
For information on how to create a threshold group, see xref:deep-dive/thresholds/thresh-group.adoc[] in the Deep Dive section.

. Click *Edit* beside the `netsnmp` group.
. Click *Create New Threshold* at the bottom of the Basic Thresholds area.
. Set the following parameters and click *Save*:
+
[caption=]
.Basic threshold configuration settings
[cols="1,3,1"]
|===
| Field | Description   | Input value

| Type
| Triggers an event when the datasource value equals or exceeds the threshold value, and re-arms when it equals or drops below the re-arm value.
| high

| Datasource
| Name of the datasource that you want to threshold against. +
For this tutorial, we have provided the datasource for logged-in users.
For information on how to determine a metric's datasource, see <<deep-dive/thresholds/datasource.adoc#datasource-determine, Determine the datasource>> in the Deep Dive section.
| hrSystemNumUsers

| Datasource label
| Optional text label.
| _Leave blank._

| Value
| The value above which you want to trigger an event.
In this case, we want to trigger an event when the number of logged-in users exceeds two.
| 2

| Re-arm
| The value below which we want the system to re-arm.
In this case, we want to re-arm the system when the number of logged-in users falls below two.
| 2

| Trigger
| The number of consecutive times that the threshold value can occur before the system triggers an event.
Since our default polling period is 5 minutes, a value of 3 means {page-component-title} will create a threshold event if there are more than two users logged in for 15 minutes.
| 3

| Description
| Optional text to describe your threshold.
| Two users

| Triggered UEI
| A custom unique event identifier (UEI) sent into the events system when the threshold is triggered. +
Defining a custom UEI for each threshold makes it easier to xref:deep-dive/notifications/introduction.adoc[create notifications].
If left blank, it defaults to the standard thresholding UEIs.
| _Leave blank._

| Re-armed UEI
| A custom unique event identifier (UEI) sent into the events system when the threshold is re-armed.
| _Leave blank._
|===

== Test the threshold

To test the threshold that you just created, follow these steps:

. SSH to the monitored node and log in to it using two different user accounts.
. In the main menu, choose menu:Monitoring[Events].
. You should see an event that indicates that your threshold triggered when more than one user logged in.
. Log one user out of the node.
The Events List page should indicate that the system has re-armed.

== Expression-based thresholds

By default, {page-component-title} includes two expression-based thresholds.
This section explains the threshold for CPU use, where {page-component-title} will create an event when the five-minute CPU load average metric equals or exceeds 70% for two consecutive measurement intervals.

Expression-based thresholds are useful when you need to threshold on a percentage, not the actual value of the data collected.

NOTE: Expression-based thresholds work only if the datasources in question are in the same directory.

To view the CPU usage threshold, follow these steps:

. Click the *gear* symbol in the top-right of the screen.
. Under Performance Measurement, click *Configure Thresholds*.
. Click *Edit* beside the `netsnmp` group.
. In the Expression-Based Thresholds area, view the first threshold (with the description "Trigger an alert when five ...").

The following table describes the parameters and their suggested configurations:

[caption=]
.Basic expression-based threshold configuration settings
[cols="1,3,2"]
|===
| Parameter | Description   | Value

| Type
| Triggers an event when the datasource value equals or exceeds the threshold value, and re-arms when it equals or drops below the re-arm value.
| high

| Expression
| Divides the five-minute CPU load average by 100 (to obtain the effective load average^1^), which is then divided by the number of CPUs.
The resulting value is multiplied by 100 to calculate a percentage.
| ((loadavg5 / 100) / CpuNumCpus) * 100

| Datasource type
| The type of datasource from which you are collecting data.
| node

| Datasource label
| Optional text label.
| _Leave blank._

| Expression label
| Optional concise text label the describes the expression.
| Load Average Above 70% 

| Value
| Threshold value.
Triggers an event when the five-minute CPU load average equals or exceeds the defined value.
| 70

| Re-arm
| Re-arm value.
Re-arms the system when the five-minute CPU load average equals or drops below the defined value.
| 50

| Trigger
| The number of consecutive times that the threshold value can occur before the system triggers an event.
In this case, it triggers an event when the five-minute CPU load average goes above 70% for two consecutive polling periods.
| 2

| Description
| Optional text to describe your threshold.
| Trigger an alert when the five-minute CPU load average metric reaches or goes above 70% for two consecutive measurement intervals.

| Triggered UEI
| A custom unique event identifier (UEI) sent into the events system when the threshold is triggered. +
Defining a custom UEI for each threshold makes it easier to xref:deep-dive/notifications/introduction.adoc[create notifications].
If left blank, it defaults to the standard thresholding UEIs.
| _Leave blank._

| Re-armed UEI
| A custom unique event identifier (UEI) that is sent into the events system when the threshold is re-armed.
| _Leave blank._
|===

. SNMP does not report in decimals, which is why the expression divides the `loadavg5` by 100.

== Beyond Quick Start

Refer to xref:deep-dive/thresholds/thresholding.adoc[] in the Deep Dive section for more information on thresholding, including the following:

* <<deep-dive/thresholds/datasource.adoc#ga-threshold-metadata, Using metadata in a threshold>>.
* <<deep-dive/thresholds/thresh-group.adoc#threshold-group, Creating a threshold group>>.
* <<deep-dive/thresholds/troubleshoot.adoc#troubleshoot-thresholds, Troubleshooting and managing thresholds>>.
* <<deep-dive/thresholds/datasource.adoc#thresholding-response-times, Thresholding on response times from polled services>>.
