Centreon Rust SNMP collection

Type: object

Declarative definition of a check executed by the centreon-plugin-rust-snmp binary (see rust-plugins/).

A collection describes three stages, run in order:

  1. collect — the SNMP queries to perform against the target;
  2. compute — the metrics (and optional aggregations) derived from the collected values, with their thresholds;
  3. output — how the resulting status and metrics are rendered as a Monitoring Plugins compatible message.

The file is passed to the binary with --json / -j.

No Additional Properties

root $schema
Type: string

Public URL pointing to the specification of this schema, so editors can provide completion and inline documentation. It is read by editors only: the plugin ignores it, and a validator must be given the schema explicitly.

Use the published URL rather than a relative path
Example:

"https://centreon.github.io/centreon-plugins/rs-collections/snmp/v0/rs-collection.schema.json"

root format_version
Type: const

Version of the collection format this file targets. The plugin refuses a collection whose version it does not support, instead of failing on an unexpected key.

The format is versioned independently of the plugin package: only a change breaking existing collections increments it. Version 0 is the beta format and carries no stability guarantee — it may break until the first stable release, which will be version 1.

Specific value: 0

root collect

Collection stage

Type: object

SNMP queries executed before any metric is computed.

 No Additional Properties

root collect snmp
Type: array

Queries to run. All Get queries are batched into a single GetBulk request; each Walk query is a separate subtree traversal.

 No Additional Items

Each item of this array must be:

root collect snmp SNMP query

SNMP query

Type: object

One SNMP query retrieving either a single value (Get) or more (Walk). Each value are made available under a macro namespace for the compute stage.

 No Additional Properties

root collect snmp SNMP query name
Type: string

Macro name under which the collected value is exposed to expressions.

Without labels, the value is referenced as {name}: a scalar for a Get query, a vector (one entry per row) for a Walk.
With labels, one macro per label is created instead, named {name.<label>}.

Must be at least 1 characters long


Examples:

"hrSystemUptime"

"storage"

"memory_used"

root collect snmp SNMP query oid
Type: string

OID to query, in numeric dotted form. A leading dot is accepted and ignored.

For a Get query this must be a leaf OID (index included, usually ending in .0); for a Walk it is the root of the subtree to traverse.

Must match regular expression: ^\.?[0-9]+(\.[0-9]+)*$
Examples:

"1.3.6.1.2.1.1.1.0"

".1.3.6.1.2.1.25.1.1.0"

"1.3.6.1.2.1.25.2.3.1"

root collect snmp SNMP query query

Kind of SNMP operation. Values are case sensitive.

root collect snmp SNMP query query anyOf Retrieve a single leaf OID value.

Retrieve a single leaf OID value.

Type: const
Specific value: "Get"
root collect snmp SNMP query query anyOf Traverse the subtree under `oid` with repeated GetBulk requests.

Traverse the subtree under `oid` with repeated GetBulk requests.

Type: const
Specific value: "Walk"

Must be one of:

  • "Get"
  • "Walk"

root collect snmp SNMP query labels
Type: object

Splits a Walk over a table into one named macro per column. Only meaningful with "query": "Walk".

Each key is the column part of the OID — the walked OID minus its trailing row index — matched as a suffix, so both ".2" and "2" select column 2. Each value is the label appended to the query name, giving the macro {<name>.<label>}.

Example: walking 1.3.6.1.2.1.25.2.3.1 under the name storage with {".3": "description", ".6": "used"} yields the vectors {storage.description} and {storage.used}, aligned row by row.


Example:

{
    ".3": "description",
    ".5": "size",
    ".6": "used"
}

Each additional property must conform to the following schema

root collect snmp SNMP query labels additionalProperties
Type: string

Label appended to the query name to build the macro name.

Must be at least 1 characters long

root compute

Compute stage

Type: object

Metrics derived from the collected values.

 No Additional Properties

root compute metrics
Type: array

Metrics that are computed based on data from the collect section (ie uses only macros from this section). May be empty when the check only reports aggregations or a plain status message.

Each metric is exposed to the aggregation pass as {metrics.<name>}.

 No Additional Items

Each item of this array must be:

root compute metrics Metric

Metric

Type: object

A value to compute, compare against thresholds and report as perfdata.

 No Additional Properties

root compute metrics Metric name
Type: string

Metric name, reported in the perfdata and used to reference the result as {metrics.<name>} or {aggregations.<name>}.

For a metric that exist for multiple instances (with Walk queries), the perfdata is named '<instance>#<name>', the instance's name being specified under the prefix attribute.

Must be at least 1 characters long


Examples:

"storage.usage.bytes"

"system.uptime.seconds"

root compute metrics Metric value
Type: string

Expression producing the metric value. A scalar expression yields one perfdata; a vector expression (a Walk macro, or an arithmetic combination of vectors) yields one perfdata per row.

Syntax: numbers, + - * /, parentheses, macros in braces ({storage.used}), and the functions Average(...), Min(...) and Max(...), which reduce a vector macro to a scalar.

Must be at least 1 characters long


Examples:

"{storage.used} * {storage.allocation_units}"

"100 * {storage.used} / {storage.size}"

"Average({metrics.cpu.utilization.percentage})"

root compute metrics Metric prefix
Type: string

Template naming the instances to use as a prefix for the perfdata names (cf. the name attribute). Usually based on a macros from the labels section in the definition of a Walk collect section.

The --filter-in and --filter-out command-line arguments will filter by matching this interpolated string to include or exclude elements.

This attribute is only interpolated for a metric coming out of a Walk. When it comes from a Get or an aggregation, the string is used as defined in the name attribute.

When omitted, instances are numbered from 0.


Examples:

"{storage.description}"

"{inodes.path}"

root compute metrics Metric uom
Type: string Default: ""

Unit of measurement linked to the current perfdata, as defined by the Monitoring Plugins guidelines. Empty by default (dimensionless).
Examples:

""

"%"

"B"

"s"

"ms"

"c"

root compute metrics Metric min
Type: number

Static lower bound reported in the perfdata. Ignored when min_expr is set.

root compute metrics Metric min_expr
Type: string

Expression computing the lower bound reported in the perfdata. Takes precedence over min.

Same definition as value

root compute metrics Metric max
Type: number

Static upper bound reported in the perfdata. Ignored when max_expr is set.

root compute metrics Metric max_expr
Type: string

Expression computing the upper bound reported in the perfdata. Takes precedence over max.

Must be at least 1 characters long


Example:

"{storage.size} * {storage.allocation_units}"

root compute metrics Metric threshold-suffix
Type: string

Exposes the metric on the command line as --warning-<suffix> and --critical-<suffix>; those options override the warning and critical fields below. Metrics without a suffix cannot be thresholded from the command line.

The suffixes of a collection are listed by --list-counters.

Must be at least 1 characters long


Examples:

"usage"

"prct"

"seconds"

root compute metrics Metric warning
Type: string

Alert range in Monitoring Plugins threshold format (https://nagios-plugins.org/doc/guidelines.html#THRESHOLDFORMAT):

  • n — alert if value < 0 or value > n (equivalent to 0:n)
  • n: — alert if value < n
  • ~:n — alert if value > n, no lower bound
  • n:m — alert if value is outside the range
  • @n:m — inverted: alert if value is inside the range
Must match regular expression: ^\s*@?\s*(?:(?:~|[-+]?[0-9]+(?:\.[0-9]+)?(?:[eE][-+]?[0-9]+)?)\s*:\s*(?:[-+]?[0-9]+(?:\.[0-9]+)?(?:[eE][-+]?[0-9]+)?)?|[-+]?[0-9]+(?:\.[0-9]+)?(?:[eE][-+]?[0-9]+)?)\s*$
Examples:

"80"

"10:20"

"~:90"

"5:"

"@0:10"

root compute metrics Metric critical
Type: string

Alert range in Monitoring Plugins threshold format (https://nagios-plugins.org/doc/guidelines.html#THRESHOLDFORMAT):

  • n — alert if value < 0 or value > n (equivalent to 0:n)
  • n: — alert if value < n
  • ~:n — alert if value > n, no lower bound
  • n:m — alert if value is outside the range
  • @n:m — inverted: alert if value is inside the range
Same definition as warning

root compute aggregations
Type: array

Metrics that can be computed based on data from both collect and metrics sections (referencing them as {metrics.<name>}). A typical use is to compute an average of a per-instance metric into a global one.

Each aggregation is exposed as {aggregations.<name>}, usable in the output section.

Available aggregations are:
- Average()
- Min()
- Max()

No Additional Items

Each item of this array must be:

root compute aggregations Metric

Metric

Type: object

A value to compute, compare against thresholds and report as perfdata.

Same definition as Metric

root output

Output stage

Type: object

Status messages and separators used to render the plugin output. The whole object is optional; every field falls back to its default: a generic message in case the state is OK, the details of non-OK metrics otherwise.

Messages are templates: {metrics.<name>} and {aggregations.<name>} are replaced by the computed values.

 No Additional Properties

root output ok
Type: string Default: "OK: Everything is ok "

Message reported when every metric is within its thresholds.
Example:

"OK: Uptime: {aggregations.system.uptime.seconds}s"

root output detail_ok
Type: boolean Default: false

Append the per-instance detail of the metrics to the OK message.

root output warning
Type: string Default: "WARNING: "

Prefix of the message reported when the worst status is WARNING.

root output detail_warning
Type: boolean Default: true

Append the detail of the metrics in alert to the WARNING message.

root output critical
Type: string Default: "CRITICAL: "

Prefix of the message reported when the worst status is CRITICAL.

root output detail_critical
Type: boolean Default: true

Append the detail of the metrics in alert to the CRITICAL message.

root output unknown
Type: string Default: "UNKNOWN: "

Prefix of the message reported when the worst status is UNKNOWN.

root output detail_unknown
Type: boolean Default: true

Append the detail of the metrics in alert to the UNKNOWN message.

root output no_data
Type: string Default: "No data matching the filters"

Message reported when no metric is left once --filter-in / --filter-out have been applied. The status given by the --no-data-status command-line option (either ok, warning, critical, unknown (default) is prepended to it.
Example:

"No process matching the filters"

root output instance_separator
Type: string Default: " - "

String inserted between two instances in the detail message.

root output metric_separator
Type: string Default: ", "

String inserted between two metrics of the same instance in the detail message.