Rspamd plugin

Monitors an Rspamd spam filtering server: health, message volume, spam/ham classification, actions taken and scan performance.

Plugin file: agent360/plugins/rspamd.py

Requirements

Rspamd running on the same server, with the controller worker enabled (default port 11334).
The rspamc client installed (package rspamd / rspamd-client depending on the distribution).
The user running the agent must be able to reach the controller.

How it works

The plugin runs rspamc (without a shell) against the local controller and parses its JSON output (stat and uptime commands). No raw rspamc output or error text is ever sent to the monitoring backend; failures are reported as short generic messages (for example rspamc timed out).

Configuration

Add a section to the agent config (e.g. /etc/agent360-custom.ini):

[rspamd]
enabled = yes
; binary = /usr/bin/rspamc
; host = localhost:11334
; timeout = 10

Option	Default	Description
`enabled`	–	Set to `yes` to enable the plugin.
`binary`	auto-detected	Absolute path to `rspamc`. If unset, `rspamc` is searched only in `/usr/bin`, `/usr/local/bin`, `/bin`, `/usr/sbin`, `/usr/local/sbin`, `/sbin` – never in `PATH` (the agent usually runs as root).
`host`	rspamc default (`localhost:11334`)	Controller address passed to `rspamc -h`. Only `localhost`, `127.0.0.1` or `[::1]`, with an optional port, are accepted.
`timeout`	`10`	Seconds to wait for each `rspamc` call. The process is killed on timeout.

Authentication

By default rspamc connects to localhost:11334, which Rspamd trusts without a password. Nothing else is needed.
If the controller is password protected, put the read-only controller password in rspamc.conf, readable only by the user running the agent.
Do not add addresses to the controller's secure_ip just for this plugin.
Do not pass the password on the command line – it would be visible in the process list.
Remote controllers are not supported: the controller speaks plain HTTP, so a password would cross the network unencrypted.

Metrics

Metrics are returned as nested groups.

`meta`

Metric	Description
`version`	Rspamd version (`unknown` if not reported).

`health`

Metric	Description
`available`	`1` when the plugin ran.
`auth_ok`	`1` if the controller accepted the request.
`read_only`	`1` if the controller is in read-only mode.
`uptime_seconds`	Rspamd uptime.
`stat_ok`	`1` if the `stat` call succeeded.
`uptime_ok`	`1` if the `uptime` call succeeded.

`messages`

Metric	Description
`scanned`, `learned`	Counters since Rspamd start.
`spam_count`, `ham_count`	Counters since Rspamd start.
`spam_ratio_pct`	Percentage of scanned messages that were spam.
`scanned_per_second`, `learned_per_second`, `spam_count_per_second`, `ham_count_per_second`	Rates derived from the counters.

`actions`

Metric	Description
`reject_count`, `soft_reject_count`, `greylist_count`, `add_header_count`, `rewrite_subject_count`, `no_action_count`	Counters since Rspamd start.
`reject_ratio_pct`, `greylist_ratio_pct`	Percentage of scanned messages rejected / greylisted.
`<counter>_per_second`	Rate for each of the six counters above.

`performance`

Metric	Description
`scan_time_avg_sec`	Average of the recent scan times reported by Rspamd.
`scan_time_last_sec`	Most recent scan time.

Rates and ratios

Counters are lifetime values since Rspamd started.
*_per_second values are computed from the difference to the previous run, using cached values from the previous call. The first call reports 0 rates.
*_ratio_pct values are calculated over the interval since the previous call. On the first call, or if no messages were scanned in the interval, they fall back to lifetime ratios from the counters.

Failure behavior

If rspamc cannot be found, run, or times out, or returns invalid JSON, the plugin reports an error message.
If only the stat call fails, just meta and health are reported (stat_ok = 0). Cached counter samples and their timestamp are preserved, so rates recover correctly on the next successful call.
nan/inf values emitted by some rspamc versions are treated as null.

Running manually

python agent360/plugins/rspamd.py

Prints the collected metrics as JSON; useful to verify configuration before enabling the plugin.

Compatibility

Works with Python 2 and Python 3.