The Cacti thold plugin is designed to be a fault management system driven by Cacti's Graph information. It provides the facility to inspect data in a Cacti Graph and the underlying RRDfile, and generate alerts for management and operations personnel. It provides Email, Syslog, and SNMP Trap or Inform escalations. In addition, it also can notify personnel of Cacti Device status changes through Email, Syslog, and either SNMP Trap or Inform.
NOTE: The Thold plugin that is in GitHub is ONLY compatible with Cacti 1.0.0 and above!
To install the plugin, simply copy the plugin_thold directory to Cacti's plugins directory and rename it to simply 'thold'. Once this is complete, go to Cacti's Plugin Management section, and Install and Enable the plugin. Once this is complete, you can grant users permission to view and create Thresholds.
Once you have installed thold, you should verify that Email support is functioning in Cacti by going to Cacti's Console and under Configuration select Settings, and from there the 'Mail/Reporting/DNS'. From there, you can test your mail settings to validate that users will receive notifications via email.
After you have completed that, you should go to the 'Thresholds' Settings tab, and become familiar with its settings. From there, you can provide overall control of thold, and set defaults for things like Email bodies, weekend exemptions, alert log retention, logging, etc.
When the notification queue is enabled, transient email failures are retried up to five times with exponential backoff from one to eight minutes. The Notification Queue page shows the attempt count and next eligible retry time. After the fifth failed attempt the row becomes a terminal error so a permanent SMTP or address failure cannot retry forever.
Notification workers claim queue rows with their process ID and drain only that claim. Unfinished rows are released when a worker stops or notifications are suspended, while claims left by a hard-killed worker are recovered after its process registration disappears. A cross-platform database advisory lease prevents a second worker from taking the same slot. Because a database reconnect can drop that lease while PHP is still running, a stale process row is reclaimed immediately when an operating-system probe confirms that the old PID is gone. Unknown liveness waits for one expired worker timeout before recovery. A live PID is compared with the process registration time before a stale worker is trusted, preventing a recycled operating-system PID from blocking notification processing indefinitely.
The legacy thold_notify.php --thread=N option remains accepted for operator
compatibility but is deprecated and ignored; queue ownership and worker
serialization are automatic.
Counter, derive, and absolute rate thresholds preserve the previous value and timestamp together when a poll has no numeric sample, preventing the next rate from using mismatched interval data. A gap of more than two effective sampling intervals (the greater of the RRD step and poller interval), or the configured RRD heartbeat when available, is treated as unknown while the current sample starts a fresh baseline instead of producing a stale rate. Thresholds with an unknown rate remain eligible for the next poll, but that poll preserves the existing alert state and writes a warning instead of treating the missing sample as a restoral. Warnings are emitted only when the threshold enters the unavailable state. A backward sample clock is re-anchored without calculating a rate for that cycle, so later samples can recover normally. Expression thresholds require a numeric sibling value in the current poll and use its cached DSStats rate, with an RRD fallback, even when the sibling has no threshold row. This preserves COUNTER and DERIVE rate units without adding an rrdtool process per expression during normal operation. They fail closed when the current sibling value is unavailable. Gauge readings remain valid across such a gap.
As with much of Cacti, settings should be documented in line with the actual setting. If you find that any of these settings are ambiguous, please create a pull request with your proposed changes.
The Cacti 1.0 version of thold is designed to work with Device Templates. Therefore, when you configure a Device Template, you can add default Threshold Templates to that Device Template and when a Device in Cacti is created with that Device Template, all the required Thresholds will be created automatically. Of course, creating stand-alone Thresholds is still supported.
Also new in thold version 1.0 is the ability to create multiple Thresholds per Data Source. So, you can have a Baseline Threshold say measuring the rate of change of a file system, while at the same having a Hi/Low and Time Based thresholds to notify you of free space low type of events.
Most standalone Thresholds are created from the Graph Management interface in Cacti. This process starts with first creating a Threshold Template for the specific Graph Template in question, and then from Graph Management selecting the Graphs that you wish to apply this Template to. Then, from the Cacti Actions drop down, select 'Create Threshold from Template' and simply select your desired Threshold Template. Though this method continues to work today, we believe that with the support of associating Threshold Templates with Device Templates, that this method will become less popular over time.
When creating your first Threshold using thold, you need to be first understand the Threshold Type. They include: High / Low, Time Based, and Baseline Deviation. The High / Low are the easiest to understand. If the measured value falls either above or below the High / Low values, for the Min Trigger Duration specified in the High / Low section, it will trigger an alert. In the Time Based Threshold type, the measured value must go above or below the High / Low values so many times in the measurement window, or the 'Time Period Length'. Lastly, the Baseline Deviation provides a floating window in the 'Time reference in the past' to measure change. If the change in the measured value either goes up or down by a certain value in that time period, an alert will be triggered.
The Re-Alert Cycle is how often you wish to re-inform either via Email, Syslog, or SNMP Trap or Inform if the Threshold has not resolved itself before then.
Thold has multiple Data Manipulation types, including: Exact Value, CDEF, Percentage, and RPN Expression. The simplest form is the Exact Value data manipulation where thold simply takes the raw value collected from Cacti's Data Collector, and applies rules to it. In the case of COUNTER type data, thold will convert that to a relative value automatically. The CDEF data manipulation allows you to use some, but not all Cacti CDEF's and apply them to Graph Data. The CDEF's that work, have to leverage one or more of the special types included in Cacti's CDEF implementation like 'CURRENT_DATASOURCE' to be relative. The Percentage Data Manipulation requires you to select the 'primary' Data Source as the Numerator, and then when selecting 'Percentage', you will be able to select the Denominator of the percentage calculation. The most involved Data Manipulation is the RPN Expression type. This Data Manipulation type allows you to use RPN Expressions to determine the value to be evaluated. It can include other Data Sources in the Cacti graph in addition to the selected Data Source. It follows closely RRDtool's RPN logic, and most RRDtool RPN functions are supported.
If you plan on using the Threshold Daemon to increase the scalability of your thresholds, note that you must modify and install the thold_daemon.service file into your systemd configuration, and then start and test the service. If you fail to perform these steps, thold will appear to not work as expected.
Lastly, please note that several forks of the thold plugin are available from different sources. These forks of thold are not necessarily compatible with the current version of Cacti's thold plugin. Please be aware of this when installing thold for the first time.
The thold plugin has been in development for well over a decade with increasing functionality and stability over that time. There have been several contributors to thold over the years. Chief among them are Jimmy Conner, Larry Adams, and Andreas Braun. We hope that version 1.0 and beyond are the most stable and robust versions of thold ever published. We are always looking for new ideas. So, this won't be the last release of thold, you can rest assured of that.
Copyright (c) 2004-2026 - The Cacti Group, Inc.