Skip to content

Check type reference

This page is the reference of all check types Vesana knows — sorted by who runs them.

Every check runs in exactly one of three modes: passive (collector in the customer network), agent (agent on the target machine) or active (the Vesana server checks itself — the active collector, called "Active-Checker" in the UI). A network check returns the same result everywhere — only the executor changes. A passive check on a host without a collector is automatically moved to active mode instead of staying unexecutable.

Each check type has exactly one set of fields — "Add check", the profile editor and "Edit check" show the same fields. What is not listed there is not read by the execution either. The Target field only appears for types that read it (HTTP checks bring their own target as a URL).

Server checks stay outside

Checks the Vesana server runs itself cannot reach server-internal addresses (loopback, Docker networks, the server's own interface addresses) — unless the check was saved by a super admin. A target in the server network is rejected when the check is saved, not only when it runs. A dedicated collector in the customer network checks its own network without restriction (from v1.9.437). Details: Active collector.

How a check forms its status

Every type judges in one of four ways. This decides whether the Threshold Warning/Critical fields can be used at all:

Verdict Meaning Threshold fields
Thresholds The check delivers a number; Warning/Critical decide. visible, effective
Judges itself The check knows its status (port open/closed, service active/inactive). There is no usable number. hidden — they would have no effect
Judges itself + measured value Command and script checks: the check sets the status itself and delivers a number. Thresholds additionally apply to the measured value and can only sharpen the status, never soften it. visible; locked with a reason as long as the script delivers no numeric value
Own limits in the configuration SSL certificate (days until expiry) and internet line (percent of the booked rate) carry their limits in type-specific fields. locked — the generic thresholds would produce permanent CRITICAL here

In the check view and in the configuration, the verdict is one sentence in the "Threshold verdict" block, right next to what is measured: 71 % ≥ 50 % ⇒ WARNING · Warning from 50 % · Critical from 80 % — from profile "Generic Linux Server". The check message carries the same reasoning whenever the threshold explains the status — even when the agent or collector already set the status itself.

Network checks

Catalog cleanup (v1.9.449)

Some types no longer appear under "Single checks" but keep running for existing checks and stay editable: vsphere (legacy, replaced by api_script), snmp_storage (created by the device scan; snmp with a reference OID does the same by hand), snmp_disk_status/snmp_disk_temp (hard-coded Synology OIDs — the "Synology NAS" profile from the Vesana library reads disks via walk) and ssh_command (identical to ssh_custom).

Run via the collector (passive) or the active collector (active). No agent needed.

ping — Ping

ICMP ping to the device: reachability and response time (ms). Each run sends three packets: no reply at all is CRITICAL; if only some are lost, the check is WARNING with the loss in percent. The message always names the target and n/m replies, the details show min/avg/max and loss. The measured value is the response time; thresholds Warning 100 ms / Critical 500 ms (default). Also runs in agent mode — the agent then pings the Target (agent mode only) field (target) from the machine.

port — Port check

Checks whether a TCP port is reachable. Field Port (port). Judges itself.

Field Expectation (expect): Port must be reachable (default, open = OK) or Port must be closed — an open port is then CRITICAL. For services that are deliberately switched off (e.g. SSH on a NAS): the closed port is the intended state there, not the exception.

http — HTTP/HTTPS

Calls a URL (url) and checks the status code. The measured value is the response time (ms), thresholds 1000 / 5000 ms (default). {host} in the URL is replaced by the device address.

The message always states what was checked: GET https://example.com → HTTP 200 in 12 ms (expected 2xx/3xx). The expectation is configurable (since v1.9.449):

Field Effect
Expected status code (expected_status) Empty: 2xx/3xx are OK, 4xx WARNING, 5xx CRITICAL. Set (200, 200-299, 2xx, 200,204, 401, any): only the listed codes are OK, everything else CRITICAL. A page that rejects anonymous visitors with 403 is checked with 403.
Response must contain (content_match, regex) If the pattern is missing from the body the check is CRITICAL — even on HTTP 200 (“something answers” is not “the application works”).
Method (method) GET (default) or HEAD (no body, no content check).
Do not follow redirects (no_redirects) The 3xx response itself counts; otherwise up to 10 redirects are followed.
Skip TLS verification (tls_skip_verify), Timeout (timeout, default 10 s) for self-signed device UIs and slow endpoints.

The check details show URL, final URL after redirects, status code, expectation, response time, Server and Content-Type headers, size, the certificate's remaining validity for HTTPS and the result of the content check.

http_json — HTTP API (JSON/text)

Calls a URL and extracts one scalar value from the response. Usually comes via device profiles with a pre-filled configuration (e.g. Sonos, OPNsense) and is not selectable in the free catalog; it can be edited like any other check.

Field Key Meaning
URL url {host} is replaced by the device address, {host_hostname} by its hostname
Method method GET (default) or POST
Authentication auth empty (default) or device_api — logs in with the username + password from the host's device API access via HTTP Basic (e.g. OPNsense, TrueNAS, UniFi: key + secret instead of a token header). If no account is stored on the device, the check reports UNKNOWN instead of a 401 that looks like a device outage
Value path (JSON) value_path path to the measured value (notation below)
Value pattern (regex) value_regex alternative to the JSON path for text/XML responses; the first capture group is the value
Aggregate multiple matches value_regex_aggregate first match (default), number of matches, sum, maximum, minimum, average
Divisor path (JSON) divisor_path value ÷ this value — e.g. used ÷ total
Scale factor value_scale factor applied to the value
Unit · Label unit · label display
Response must contain content_match if the text is missing from the response, the check is CRITICAL — verifies that the expected device really answers
Skip TLS verification tls_skip_verify for self-signed internal endpoints
Request body body POST only

Credentials such as an API token or the device API account belong to the host, not the check. They are only sent to the device's own address (IP, DNS name, {host}); if the URL points to another target, the check reports UNKNOWN with a reason instead of sending the credentials there. They are not carried along on a redirect to another server either.

If the device answers with an error (HTTP 400 and above), the message states what the device says about it (status line or message/error/detail from the JSON body), not just the code. Responses over 1 MiB are cut off; the check then reports UNKNOWN in plain text instead of a wrong value.

Scalar values only

A numeric hit becomes the measured value (graph, thresholds); a text hit lands in the message and can be judged via a comparison with an expected value. Objects and lists are not supported — except as a count (#, see below).

Aggregating multiple matches — what sets \"number of matches\" apart

Number of matches counts how often the pattern occurs in the response — with no match the measured value is 0, not UNKNOWN: "no match" is the statement here (e.g. how many services report "running":0). Sum / maximum / minimum / average instead evaluate the NUMBERS found and need at least one — no numeric match stays UNKNOWN.

value_path notation

Not full JSONPath, but a small, predictable subset:

Notation Meaning
a.b field in an object
a.0 / a[0] list element (negative indices count from the end)
a[k=v] filter a list: only elements whose field k equals v
a[k!=v] the same, negated
a[k^v] field k is text and starts with v
a[k!^v] the same, negated
a# count of elements (or length of object/text)

Filters can be chained; they then all apply at once (AND). This turns a list into countable values:

data[type=qemu][status=running]#                            # running VMs
data[type=vzdump][saved=1][status!=OK][status!^WARNINGS]#   # failed backups

Prefix instead of equality when the text contains a number

Proxmox writes OK, an error text or WARNINGS: 3 into status — with the count in the text. Such a value cannot be matched by equality; [status^WARNINGS] matches it regardless of the number.

ssl_certificate — SSL certificate

Checks a TLS certificate and monitors its expiry. Runs passive, active or via the agent. Default interval 6 hours.

Field Key Default Meaning
Hostname / domain hostname – name the certificate is issued for — connected and verified (SNI). Empty = DNS name or IP of the device
Port port 443
Connection target (optional) connect_to – only if the connection should go to a different address; verification still uses the hostname
WARNING below remaining days warn_days 30
CRITICAL below remaining days crit_days 14
Allow self-signed certificates allow_self_signed off no alarm for self-signed certificates or name/chain mismatches; expiry is still monitored
OCSP revocation check check_ocsp off additionally ask the issuer whether the certificate was revoked
Timeout (seconds) timeout – under "Advanced"

The limits live in the day fields

The measured value is the remaining lifetime in days. The generic threshold fields are locked for this type — values set via API, bulk edit or profile import do not reach the execution either. They used to produce permanent CRITICAL.

internet_line — Internet line (speed test)

Down-/upload against the booked bandwidth, ping under load, packet loss, public IP. Own page: Monitoring internet lines. Here too, the limits (WARNING/CRITICAL below % of target) live in their own fields; the generic thresholds are locked.

vsphere — VMware ESXi (API) (legacy)

Reads an ESXi host via the vSphere API — CPU, memory, datastores, VMs, uplinks, hardware health; needs no shell access, an account with the "Read-only" role is enough. Stays in place for existing ESXi profiles and keeps running. For Fullest datastore, a datastore with an entry under Custom limits per datastore (Name:warn:crit, % and decimal comma allowed) is judged by those limits, all others by the check's thresholds; an entry without a readable limit does not exempt the datastore — the general limits apply and the message names the entry. A rejected login is not retried for 15 → 30 → 60 minutes, as with SSH. New ESXi checks use api_script (see below) instead — the same route via the API, but as a script in the library rather than a hard-wired Go type, so the body can be read and adjusted.

api_script — Script (API)

An editable script from the script library that the collector runs locally and that logs in to a device API itself — for devices with an API but no (usable) shell. This is how the profiles for ESXi, Proxmox VE and Proxmox Backup Server work. Typical example: ESXi — a monitoring account with the "Read-only" role may log in via the API but not into the shell (ESXi access rights hang on the role, not on a "shell access" checkbox). ssh_script is out (the body would run ON the target device, which doesn't grant that shell); agent_script is out because the device cannot carry an agent (appliance). api_script closes the gap: the collector runs the body itself, and the body talks to the device API on its own.

The body reaches the API itself over HTTP(S) (SOAP on ESXi); target and credentials arrive as environment variables:

Environment variable Source
VESANA_TARGET address of the device
VESANA_API_USER / VESANA_API_PASSWORD the host's device API account; without one, the host's SSH credentials are used as a fallback. Both only go to the device's own address — if a different target is set on the check, the check reports UNKNOWN with a reason
VESANA_API_PORT field API port (port, default 443)
VESANA_API_INSECURE field Skip TLS verification (tls_skip_verify) — for appliances with a self-signed certificate (ESXi out of the box)

On top of that come the script's configurable values as VESANA_<NAME>. Otherwise the script sees none of the collector's environment; its output is limited to 1 MiB. Evaluation and value extraction follow the same contract as the command/script checks — see Evaluation of command and script checks. Default interval 5 min.

ESXi via the vSphere API: one script measures one metric per check (CPU, memory, fullest datastore, inaccessible datastores, running/not running VMs, uptime, connection state/maintenance mode, uplinks without link, hardware sensors, overall health, reboot required). The matching settings only appear for their metric: exclude VMs, datastores, uplinks or sensors, uptime in days or hours, maintenance mode as OK/WARNING/CRITICAL, skip small datastores and Per-datastore limits (NAME:warn:crit). A datastore with its own limits is judged by them; the measured value is the fullest datastore without own limits, and the message additionally names the fullest one overall with its limits.

SNMP checks

What the value MEANS lives in one place

snmp, snmp_oid and snmp_string have an Interpretation block in their configuration: mapping a state value (value → label → status), converting a metric (factor, offset, unit, display) and evaluating a text — with preview and OID catalog. The fields listed below are the technical underpinning of it. Operation, examples and symptoms: SNMP interpretation.

Prerequisite: host with an IP address and SNMP credentials. All SNMP types have the field Community (override) (community) under "Advanced" — only fill it in if exactly this check needs a different community than the device.

snmp, snmp_oid and snmp_string additionally have the field Value display (value_format) — converts the raw numeric value for the MESSAGE only; the measured value itself (and therefore the thresholds) stays unchanged:

Value Meaning
Number as measured (default) no conversion
Duration from timeticks duration_ticks — timeticks (1/100 s, e.g. sysUpTime) become seconds; "17993930" becomes "2d 1h 58m". The legacy notation unit: ticks keeps working
Duration from seconds duration_s — value stays in seconds, message shown as a duration
Bytes, human-readable (KB/MB/GB) bytes — value stays in bytes (thresholds apply in bytes)
SI prefix on the unit si — k/M/G/T in front of the unit, 1000000000 bit/s becomes "1.0 Gbit/s"

Every walked row visible under \"Details\"

SNMP checks that query a table column (snmp with walk_oid, snmp_row_watch) show every row with its label and value under "Details" in the status panel (up to 50, with the count of remaining rows shown above that). For maximum/minimum aggregation, the row that decided the status is marked.

snmp — SNMP query

Query a single OID or a whole table column and condense it to one numeric value. Thresholds decide.

Field Key Meaning
OID oid a single OID
Fallback OID fallback_oid if the OID above answers "not present" (noSuchObject/noSuchInstance/endOfMibView), the check reads this OID instead — the message/details then name the fallback OID as the source. Single OID only, not for a table walk. Details: SNMP interpretation.
Table column (walk OID) walk_oid read a whole column instead of one OID and condense it to one value
Aggregation aggregate maximum (default), minimum, average, sum, row count
Unit · Scale factor · Offset unit · scale · offset display, or e.g. 0.001 for mW → W; offset applies AFTER the scale factor (Kelvin → °C: −273.15). In a table walk the offset applies per row for maximum/minimum/average, not for sum; with percent (reference OID/column) and "row count" scale factor, offset and display have no effect at all — the editor hides them and says why
Value display value_format see above — for a table walk, not with "row count" aggregation and not when a reference column (percent) is set

Under "Advanced" the rest of the walk contract that makes the good device profiles. The fields that only apply to a table column appear once a walk OID is entered:

Field Key Meaning
Reference column (walk OID) · Reference OID (single) total_walk_oid · total_oid second quantity as reference — the value then becomes percent (value ÷ reference × 100)
Invert reference (free instead of used) invert computes 100 − percent, for columns that report the free share
Skip rows up to this value skip_below for tables that report −1 or 0 when a sensor is absent
Name column (OID) label_column_oid plain-text names of the rows — prerequisite for filtering and labelling
Exclude names (contains) label_exclude rows whose name contains one of the terms are dropped
Monitor only this name label_match watch exactly this row; if it is missing, that is CRITICAL, not UNKNOWN
Merge rows with the same name distinct_label

snmp_string — SNMP text

Read an OID as text and check it against an expected value. Judges itself; if the text is a plain number, it is additionally kept as the measured value (thresholds then apply as well). If a custom regex pattern takes too long, the check reports UNKNOWN in plain text instead of a wrong verdict.

Field Key Meaning
OID oid
Expected value match_value
Treat expected value as regex is_regex without the checkbox the text must match exactly
CRITICAL when it matches fail_if_match inverts the logic: match = failure
Status per value / Label per value value_map / value_labels numeric value → status resp. → plain text for the message; a value with no mapping gets Status without mapping (unmapped_status, default WARNING), never a silent OK
Unit · Scale factor · Offset · Value display unit · scale · offset · value_format for numeric values — display as above

Evaluating bitmasks

For OCTET-STRING bitmasks (e.g. hrPrinterDetectedErrorState) the check carries plain text and severity per set bit: Bitmask: bit → text (bit_labels), Bitmask: bit → severity (bit_severity, WARNING or CRITICAL per bit) and Bitmask: message with no bit set (bits_ok_message). The three fields sit under "Advanced" and can be edited in the form; once bit_labels is set, the check judges by the bits instead of text or mapping. Existing checks without a bitmask behave unchanged.

snmp_oid — SNMP state / single value (OID)

Created by the SNMP sensor picker (discovery walk → "Adopt as check"). Carries the Fallback OID field (fallback_oid, see above) like snmp. Branches on the Value type (value_type):

  • gauge (default): numeric value, thresholds apply as with snmp. Field Value display (value_format, see above) converts the message.
  • status: the value is a category — OK values / WARNING values / CRITICAL values (ok_values/warn_values/crit_values) determine the status, an unlisted value gets Status without mapping (unmapped_status, default WARNING). The threshold fields are locked in this mode (the measured value is only the code of the state). Individual values can only be OK, WARNING or CRITICAL here; UNKNOWN is only available via Status without mapping.

The number → text mapping (value_labels) is maintained in the Interpretation block, see SNMP interpretation.

snmp_storage — SNMP storage (hrStorage) (no longer in the catalog)

Created by the sensor picker: usage of a volume in percent from three OIDs (OID used / OID total size / OID block size — oid_used/oid_size/oid_unit). Thresholds 80 / 90 % (default), interval 5 min.

snmp_interface — SNMP interface status

Operational state of an interface (ifOperStatus) via the Interface index (if_index). Judges itself; comes via profiles and the sensor picker.

snmp_table — SNMP table dump

Reads a whole SNMP table as a snapshot (device snapshot) — the basis for the port map, NAS disk bay, UPS and firewall panels. Field Snapshot type (snapshot_type). Comes via profiles.

snmp_table_state — Worst state of a table

Reads a status column (walk_oid) and reports the worst entry based on Values meaning OK/WARNING/CRITICAL. Under "Advanced": name column, Name filter (name_filter, with Filter effect include/exclude) Skip row indexes (ignore_indexes) and Number → text (state_labels, labels for the message and the detail table). Comes via profiles. Under "Details" ALL entries of the table are listed, not just the ones with a problem.

snmp_row_watch — SNMP row watcher

CRITICAL when a named entry disappears from an SNMP table — typically a SonicWall VPN tunnel. Default OIDs are pre-filled; you only enter the Name of the entry (label_match, e.g. the VPN policy name). Comes via device profiles.

snmp_bandwidth — Interface utilization (bandwidth)

How full is a link? Utilization of an interface as a rate (change of the counters per second) in percent of the speed or in Mbit/s, plus errors and discards per minute. The interface is chosen by its name, never by its number. Thresholds decide. Usage and error messages: Bandwidth and counters.

Field Key Meaning
Interfaces interface_mode name (default) = one interface · all = all, the busiest counts
Interface interface name as the device reports it — the field offers the known names
Name from match_column ifName (default), ifDescr, ifAlias — which column carries the name
Metric metric utilization (default), errors or discards (per minute)
Direction direction max (default, the higher counts), in, out
Unit unit_mode percent (default) or mbit
Reference bandwidth (Mbit/s) reference_mbit instead of the port speed, e.g. the booked bandwidth of an internet line
Exclude interfaces · Include without link · Include virtual label_exclude · include_down · include_virtual only with all

The first value arrives after one interval (a rate needs two measurements). Runs only on a collector or the Active-Checker — without one the check says so in plain text.

snmp_counter — SNMP counter as a rate

Any counter (Counter32/Counter64) as change per second — a single OID or a table column (walk_oid) with aggregation (aggregate: max/min/avg/sum), name column, exclusions and label_match like snmp. Factor (scale) applies to the per-second rate (60 = per minute), Unit (unit) empty = /s. Thresholds decide. Details: Bandwidth and counters.

snmp_disk_status / snmp_disk_temp — Disks (SNMP) (no longer in the catalog)

Status or temperatures of all disks via SNMP walk (Synology). Status judges itself; temperature with thresholds 45 / 55 °C (default).

SSH checks

The collector logs in to the device via SSH and runs a command. SSH credentials are maintained on the host; every SSH check has the fields SSH user / SSH password / SSH port / SSH target (override) under "Advanced" — only fill them in if exactly this check should log in differently (e.g. via a jump target in the same network). The device's credentials never go to a different target; the password for it belongs on the check.

Server key: on first contact Vesana remembers the SSH server key. A check with a different target gets its own entry for it (target + port) instead of overwriting the device's. If the key changes later, the check reports SSH_HOST_KEY_MISMATCH and the status panel shows the card "SSH key has changed" with the old and new fingerprint; "Accept new key" (permission hosts.edit, with identity confirmation, recorded in the audit log) accepts exactly the reported fingerprint.

Rejected credentials and unreachable devices

If the SSH credentials are rejected, the collector remembers this per device and attempts no further login for 15 → 30 → 60 minutes — previously several failed attempts ran per check and interval, which devices treat as an attack (account lockout, blocklist). Affected checks stay Unknown with plain text (user, target, end of the pause); changed credentials, an immediate check or, for collector checks, the "Retry login now" button in the status panel lift the pause at once. If the device is not reachable via SSH at all (connection refused/timeout), the check is Critical, not Unknown (from v1.9.437).

ssh_cpu, ssh_mem, ssh_disk — CPU, RAM, disk (SSH)

Standard commands for Linux devices without an agent. Thresholds 80 / 95 % (CPU, RAM) or 80 / 90 % (disk). ssh_disk has the field Mountpoint (mount, default /).

Not for ESXi

ESXi only allows accounts with the "Admin" role into the shell — a read-only monitoring account would need admin rights just to get in. For ESXi, use api_script (see the "Script (API)" section above): the same metrics via the vSphere API, with a read-only account.

ssh_process, ssh_service — Process, service (SSH)

Checks whether a Process name (process) is running or a systemd Service name (service) is active. Judge themselves. If the device has no usable pgrep (ESXi, BusyBox), ssh_process reports UNKNOWN in plain text instead of "not running".

ssh_custom, ssh_command — Custom command, command with evaluation (SSH) (ssh_command no longer in the catalog)

Run a custom Command (command) via SSH. Only standard output is evaluated — to check error output, redirect it with 2>&1; with empty output, the error output appears in the UNKNOWN message. Output is limited to 1 MiB, the message to 8192 characters. Both read the same evaluation contract (below: Evaluation of command and script checks).

ssh_script — Script (SSH)

Run a script from the script library via SSH — centrally managed, with configurable values. Evaluated according to the output format declared on the script, exactly as on the agent; Python scripts run with the Python interpreter, shell scripts fall back to sh when the device has no bash (ESXi, appliances).

Agent checks

Prerequisite: agent installed and host agent-managed. The rich types (disks, services, process, eventlog, containers) have their own guided editors with suggestions from the host inventory.

agent_cpu, agent_memory — CPU, RAM

Usage in %, thresholds 80 / 95 (default).

CPU usage is the average over the whole check interval (difference of the CPU counters between two runs, on Windows from the raw performance counters), not a snapshot. The first run after an agent start therefore delivers no value yet. If you set limits before v1.9.452: the values have been noticeably lower since then, so the limits are worth a look.

agent_disk — Disks

Monitor all partitions automatically; limits as percent or as free space in GB, per-drive overrides, excluded drives. A single unreadable volume does not pull the check to UNKNOWN — the status comes from the readable drives, the unreadable one is named in the message. Interval 5 min.

agent_service — Service

Service name (service, systemd unit or Windows service). OK when active, otherwise CRITICAL.

agent_services_auto — Services (automatic)

All services with startup type "Automatic" — every one not running is CRITICAL. Exclusions (also with wildcards) match name and display name.

agent_process — Process

Is a process running (minimum/maximum count)?

agent_network, agent_disk_io, agent_temperature — Network throughput, disk load, temperature

The agent does not measure these three separately: Vesana derives them from the system overview the agent already sends every 30 s for the Telemetry tab. The tab and the check therefore show the same number, and they work with every agent without an update. The quickest way to create one is monitor in the Telemetry tab — preset to exactly the interface, disk or sensor of that row.

Type Field Value
Network throughput Interface (interface, empty = all physical ones combined), Direction (direction: busier · received · sent · both combined) Mbit/s; received and sent as additional values in the history
Disk load Disk (device, empty = all), Metric (metric: utilization in % or read + write in MB/s) % or MB/s; warning from 90 % (default)
Temperature Sensor (sensor, empty = the hottest; disks are named “disk <name>”) °C

Without thresholds of its own, the temperature check is judged by the maximum the sensor reports (WARNING from 85 % of it, CRITICAL at the maximum); thresholds you set can only make it stricter. Virtual interfaces (Docker bridges, veth, libvirt) do not count towards “all” — their traffic is already in the physical card. The interval applies: a 60 s check takes every second overview, a status change goes through immediately. Right after an agent start the first value is missing (rates need two measurements).

agent_eventlog — Eventlog

Filter and count the Windows event log or the Linux journal (journald) — log, level, time window (default 30 min), event IDs (Windows only), sources or systemd units, plus exclusions by event ID and source and a pattern for the message text. An exclusion removes only the affected event. The measured value is the number of entries in the window; thresholds 1 / 5 (default), interval 5 min. Sample hits are shown in the instance time zone.

agent_containers — Containers (Docker)

Monitor all Docker containers automatically (status, health, CPU/RAM/network) via the Docker socket, Linux only; Docker socket (override) (socket) only for rootless Docker. Interval 2 min. The measured value is the number of problem containers. Details: Host detail → Docker.

Setting Effect
Severity per problem type unhealthy · stopped despite restart policy · crash loop · required container stopped/missing — each off, WARNING or CRITICAL (default CRITICAL)
Crash loop sensitivity restarts within the time window (default 3 in 15 min)
Ignore one-off containers a container that exited with code 0 is not a problem
All must be running every container that is not running counts, even without a restart policy
Check for newer images at most every 6 h the agent asks the registry whether a newer image exists for the tag (display only, on by default)
Exceptions single containers (also for one problem type only), whole Compose projects, or the Docker label vesana.ignore=true on the container
Threshold Warning/Critical limits on the number of problem containers

Without thresholds, the worst severity of the problems found decides. Once a threshold is set, the count decides; the severities then only determine what counts (severity off does not count). Earlier "Warn from"/"Crit from" values were moved into the threshold fields by the update.

agent_custom — Custom command

Run a Command (command) on the machine. OK pattern (ok_pattern, default .) — if it matches the output, the check is OK; CRITICAL pattern (crit_pattern) takes precedence.

agent_script — Script

Run a script from the script library. Alternatively a local path on the machine or an inline script directly on the check — both with interpreter and output format on the check. Interval 5 min (default).

Nagios plugin

plugin_local — Plugin (Nagios)

Run a Nagios-compatible plugin via the active collector. Comes via the script library (interpreter "plugin_local"); details: Nagios migration.

Evaluation of command and script checks

ssh_custom, ssh_command, ssh_script, api_script, agent_custom, agent_script and plugin_local judge themselves and deliver a measured value. For the SSH and API types you set the evaluation in plain language — no regex knowledge required:

When is this check OK?

Choice Meaning
The script decides via its exit code: 0 = OK, 1 = WARNING, 2 = CRITICAL, 3 = UNKNOWN. The usual way.
Based on the output Reads as a sentence: The output must / must not · be exactly / contain · active. If the expectation does not hold (or the failure pattern matches), the check reports CRITICAL. The generated pattern is shown openly.
Own pattern for experts: a regex (match_regex) plus "When the pattern matches: the check is OK / CRITICAL" (fail_if_match). An existing pattern that cannot be expressed as a plain-language rule stays here unchanged.

Which number from the output is the measured value? — The first number in the output (default), The number at the start of the output, The number after a specific text or an own pattern with a capture group (extract_value); plus Unit of the value (value_unit). If the check finds no number, it stays valid — it just has no value, and the threshold fields are locked with a reason.

What applies:

  • When the output decides the status, the message says why: 0 · pattern "^0$" matches instead of a bare 0. Multi-line outputs are condensed to one line for this.
  • Empty output stays UNKNOWN — without output no result can be justified.
  • Library scripts are evaluated via SSH and on the agent according to the output format declared on the script (Nagios, text, JSON); with Nagios the measured value is the first perfdata metric.
  • Besides the measured value, a script can deliver multiple series (Nagios perfdata or JSON series) and a free details object — the series appear individually selectable in the history graph, the details when clicking the check. Details: Monitoring scripts.

Twelve bundled checks could never turn red

Until v1.9.358 the collector did not read the evaluation rule of SSH script checks; commands ending in || echo 0 always reported OK — affected were, among others, "Nginx service running", "Postgres service running", "WAN reachability (ICMP)" and "DNS recursion test". Since the update the rules apply. After updating, take a look at the error overview: what is red now was already broken before. Fields without effect were removed or renamed in the process ("Mount point" on Disk (SSH) silently measured /; "Process name"/"Service name" on the SSH checks; the expiry limits on the SSL certificate) — stored values keep working automatically.

Thresholds

Numeric checks usually do not evaluate themselves — the server compares the incoming value against Warning/Critical and sets the status.

  • Direction: high = bad (default) or low = bad — e.g. for free disk space, UPS battery charge and runtime remaining, or uptime since the last restart. It can be switched on the profile and on the individual check of a device. The uptime checks of the Vesana library profiles carry low = bad: a limit in hours reports an unexpected restart. UPS checks for battery charge and runtime adopted from the device scan alert when the value drops.
  • Numbers only: nan/inf are rejected when saving.
  • Empty means inherited. On the host check the field only shows an own value for this device; the profile value stands next to it as a placeholder. What you leave empty follows along when the profile is updated. Only what you really change is pinned to the device — this applies to thresholds as to all other fields.
  • Takes effect with the next result, at the latest after five minutes (server cache) — the agent or collector does not need to reload anything. The server checks every incoming result against the currently valid limits, but only escalating: a hard failure (port closed, HTTP 500) is never downgraded by a harmless numeric value.
  • For script checks the limits apply in addition to the script's verdict and can only sharpen it. Limits belong on the check, not in the script — a number value on the script is meant for time windows, minimum counts and ports (Configurable values).
  • Confirmations: a first failure initially goes to PROBING — the worker repeats the confirmation as often as configured under "Advanced" (default 1× / 10 s) before treating the failure as confirmed. Details: State model.

"Check now" & intervals

"Check now" triggers a single check immediately, independent of the interval — handy when testing a new configuration. The button only exists for checks run by the Active-Checker (check_mode='active'): it measures synchronously and shows the result right away; long-running checks such as the speed test report "running" and fill in the result later. It requires the permission "Reschedule checks" (Operator and Admin have it, Viewer does not). Checks whose status comes from the check logic (interface/port status) keep it; a hard failure (e.g. HTTP 500) stays even with response-time thresholds.

The server never runs agent or collector checks itself — an agent check doesn't exist on the server at all, and a target in the customer network is unreachable from it. Instead, a freshly created check gets a job sent to the agent or collector (picked up within roughly 60 s) and stays on PENDING ("Waiting for data", blue) until the first real result arrives — not an error, just "no data yet".

The interval can be chosen between 10 seconds and 7 days; the check type cannot be changed after creation.

Common fields (all check types)

Field Meaning
Interval (s) how often (10 s ≤ x ≤ 7 days)
Confirmations · Confirmation interval (s) number and spacing of confirmation attempts in the PROBING state ("Advanced")
Threshold Warning / Critical numeric limits — only usable where they apply
Value type profile check only: gauge / counter / status / info / duration — determines how the history displays the values; alerting is independent of it
Display in history Automatic (default), Curve, Status band or Both — display only, set on the profile check with an override on the device; uptime as a curve shows a restart as a drop to zero
Info mode on a device's check: statistics only — the check measures and records, never alerts and does not count as a problem
Use as reachability hint if this check fails, the device counts as unreachable; follow-up alerts are suppressed (normally the ping takes this role)

Which check type for which problem

Problem Recommendation
Is the device reachable? ping
Is the website up? http
Is Apache running? agent_service (with agent) or ssh_service (without)
CPU load? agent_cpu
Disk filling up? agent_disk
Events in journald/eventlog? agent_eventlog
Switch port status? device profile with port map (snmp_table)
UPS battery charge or runtime remaining? snmp/snmp_oid with an OID from the UPS MIB (the device scan proposes them), direction low = bad
VPN tunnel monitored? snmp_row_watch (via a matching device profile)
A single value from a REST API? http_json with value_path
Proxmox VE / Proxmox Backup Server? api_script via the device profile
Backup successful yesterday? agent_script / ssh_script with a script from the library
Own logic? agent_custom / ssh_custom
Monitor an ESXi host (no shell access)? api_script with a vSphere API script (read-only account)
How full is a link / port right now? snmp_bandwidth
Errors or discarded packets on a port? snmp_bandwidth with metric errors/discards
Any other counter (packets, requests) per second? snmp_counter
Bandwidth of the internet line? internet_line (speed test) or snmp_bandwidth with a reference bandwidth (load at the router)

Next