diff --git a/i18n/fr/docusaurus-plugin-content-docs-pp/current/integrations/plugin-packs/procedures/applications-protocol-modbus.md b/i18n/fr/docusaurus-plugin-content-docs-pp/current/integrations/plugin-packs/procedures/applications-protocol-modbus.md index cff90307c40d..f93176798421 100644 --- a/i18n/fr/docusaurus-plugin-content-docs-pp/current/integrations/plugin-packs/procedures/applications-protocol-modbus.md +++ b/i18n/fr/docusaurus-plugin-content-docs-pp/current/integrations/plugin-packs/procedures/applications-protocol-modbus.md @@ -24,8 +24,8 @@ Aucun service par défaut n'est créé pour ce modèle d'hôte. -| Alias | Modèle de service | Description | -|:----------------------|:-------------------------------------------------|:---------------------------------------------------| +| Alias | Modèle de service | Description | +|:----------------------|:-------------------------------------------------|:------------------------------------| | Numeric-Value-Generic | App-Protocol-Modbus-Numeric-Value-Generic-custom | Supervision de métriques via Modbus | > Les services listés ci-dessus ne sont pas créés automatiquement lorsqu'un modèle d'hôte est appliqué. Pour les utiliser, [créez un service manuellement](/docs/monitoring/basic-objects/services) et appliquez le modèle de service souhaité. @@ -155,9 +155,9 @@ yum install centreon-plugin-Applications-Protocol-Modbus -| Macro | Description | Valeur par défaut | Obligatoire | -|:-------------|:---------------------------------------------------------------------------------------------------|:------------------|:-----------:| -| CONFIG | Define the configuration of the check (can be a file or a json string directly). | | X | +| Macro | Description | Valeur par défaut | Obligatoire | +|:-------------|:-------------------------------------------------------------------------------------------------------------------------------------------------|:------------------|:-----------:| +| CONFIG | Define the configuration of the check (can be a file or a json string directly). | | X | | EXTRAOPTIONS | Any extra option you may want to add to the command (a --verbose flag for example). Toutes les options sont listées [ici](#options-disponibles). | | | > **CONFIG :** Davantage d'informations sont disponibles [ici](https://github.com/centreon/centreon-plugins/blob/master/doc/en/user/guide.rst#modbus-protocol). @@ -189,6 +189,351 @@ La commande devrait retourner un message de sortie similaire à : OK: All metrics are OK | 'metric1'=10;;;; 'metric2'=40;;;; 'metric3'=72;;;; ``` +> Le contenu du fichier JSON peut aussi être passé directement : +> `--config='{ "selection": { "metric1": { ... } } }'` + +### Structure générale du fichier JSON + +```json +{ + "selection": { ... }, + "virtualcurve": { ... }, + "command": { ... } +} +``` + +| Section | Obligatoire | Description | +|----------------|-------------|-----------------------------------------------| +| `selection` | Oui | Définit les registres Modbus à lire | +| `virtualcurve` | Non | Agrège et transforme les valeurs lues | +| `command` | Non | Personnalise le formatage global de la sortie | + + +### Section `selection` + +Chaque entrée de `selection` correspond à un registre (ou groupe de registres) Modbus à lire. +La clé est le **nom de la métrique** résultante. + +```json +{ + "selection": { + "": { + "address": , + "quantity": , + "type": "", + "display": , + "formatting": { ... } + } + } +} +``` + +#### Clés disponibles dans `selection` + +| Clé | Type | Obligatoire | Description | +|--------------|---------|-------------|---------------------------------------------------------------------------| +| `address` | entier | Oui | Adresse du registre Modbus (décimal) | +| `quantity` | entier | Oui | Nombre de registres consécutifs à lire | +| `type` | chaîne | Non | Type de registre (voir valeurs ci-dessous). Défaut : `holding` | +| `display` | booléen | Non | Afficher la valeur brute dans la sortie. Défaut : `true` | +| `formatting` | objet | Non | Personnaliser le message de sortie (voir section [Formatage](#formatage)) | + +#### Valeurs possibles pour `type` + +| Valeur | Description | +|------------|-----------------------------------------------------------| +| `holding` | Registre de maintien (lecture/écriture) — le plus courant | +| `input` | Registre d'entrée (lecture seule) | +| `coil` | Bobine (valeur binaire 0/1, lecture/écriture) | +| `discrete` | Entrée discrète (valeur binaire 0/1, lecture seule) | + +#### Exemple minimal + +```json +{ + "selection": { + "temperature": { + "address": 100, + "quantity": 1, + "type": "holding", + "display": true + } + } +} +``` + +#### Exemple avec plusieurs métriques + +```json +{ + "selection": { + "metric1": { "address": 1, "quantity": 1, "type": "holding", "display": true }, + "metric2": { "address": 2, "quantity": 1, "type": "holding", "display": true }, + "metric3": { "address": 3, "quantity": 1, "type": "holding", "display": true } + } +} +``` + +#### Lecture de plusieurs registres d'un coup (`quantity > 1`) + +Quand `quantity` est supérieur à 1, le plugin lit plusieurs registres consécutifs et les nomme automatiquement `.0`, `.1`, etc. +Cela est utile pour réduire les échanges réseau sur les liens à faible débit. + +```json +{ + "selection": { + "phases": { + "address": 1045, + "quantity": 3, + "type": "holding", + "display": false + } + } +} +``` + +> Les métriques générées seront nommées : `phases.0`, `phases.1`, `phases.2` + +### Section `virtualcurve` + +La section `virtualcurve` permet de créer des métriques dérivées à partir des valeurs lues dans `selection`. Elle est indispensable pour : +- Appliquer une mise à l'échelle (ex : diviser par 10 si l'équipement renvoie `153` pour `15.3A`) +- Agréger plusieurs registres (moyenne, somme, min, max) +- Définir des seuils d'alerte et critique +- Réaliser des calculs complexes (ex : puissance = courant × tension) + +```json +{ + "virtualcurve": { + "": { + "aggregation": "", + "pattern": "", + "custom": "", + "unit": "", + "warning": "", + "critical": "", + "formatting": { ... } + } + } +} +``` + +#### Clés disponibles dans `virtualcurve` + +| Clé | Type | Obligatoire | Description | +|---------------|---------|-------------|---------------------------------------------------------------------------------------------------------------------------| +| `aggregation` | chaîne | Oui | Méthode d'agrégation des valeurs sélectionnées | +| `pattern` | chaîne | Non | Expression régulière pour filtrer les métriques source depuis `selection`. Si absent, toutes les métriques sont utilisées | +| `custom` | chaîne | Non | Expression arithmétique appliquée à la valeur agrégée | +| `unit` | chaîne | Non | Unité de la métrique résultante (ex : `A`, `W`, `°C`) | +| `warning` | chaîne | Non | Seuil d'avertissement (format Nagios : valeur simple ou range `min:max`) | +| `critical` | chaîne | Non | Seuil critique (format Nagios : valeur simple ou range `min:max`) | +| `formatting` | objet | Non | Personnaliser le message de sortie (voir section [Formatage](#formatage)) | + +#### Valeurs possibles pour `aggregation` + +| Valeur | Description | +|--------|-------------------------------------------------| +| `avg` | Moyenne des valeurs sélectionnées | +| `sum` | Somme des valeurs sélectionnées | +| `min` | Valeur minimale parmi les valeurs sélectionnées | +| `max` | Valeur maximale parmi les valeurs sélectionnées | + +### Section `command` (formatage global) + +La section `command` permet de modifier l'affichage de toutes les métriques de la sélection globalement, et de surcharger ce comportement pour une métrique spécifique via `override`. + +```json +{ + "selection": { ... }, + "command": { + "formatting": { + "printf_msg": "My Metric '%s' value is %.2f", + "printf_var": "$self->{result_values}->{instance}, $self->{result_values}->{value}" + }, + "override": { + "metric3": { + "formatting": { + "printf_msg": "Override '%s' value is %.2f", + "printf_var": "$self->{result_values}->{instance}, $self->{result_values}->{value}" + } + } + } + } +} +``` + +### Formatage des messages de sortie {#formatage} + +L'objet `formatting` (utilisable dans `selection`, `virtualcurve` ou `command`) permet de personnaliser le texte affiché pour chaque métrique. + +| Clé | Description | +|---------------|-------------------------------------------------------------------------------| +| `printf_msg` | Format du message, syntaxe `printf` Perl (ex : `"Metric '%s' value is %.2f"`) | +| `printf_var` | Variables Perl à injecter dans le message | + +Variables disponibles dans `printf_var` : + +| Variable | Contenu | +|--------------------------------------|---------------------------------| +| `$self->{result_values}->{instance}` | Nom de la métrique | +| `$self->{result_values}->{value}` | Valeur numérique de la métrique | + +### Exemples de calculs personnalisés (`custom`) + +L'attribut `custom` accepte une expression arithmétique Perl qui sera appliquée à la valeur agrégée. +La valeur courante est implicite — l'expression commence directement par l'opérateur. + +#### Mise à l'échelle simple + +L'équipement retourne `1530` pour représenter `15.3 A` : + +```json +{ + "selection": { + "rawCurrent": { "address": 1045, "quantity": 1, "display": false } + }, + "virtualcurve": { + "currentA": { + "aggregation": "avg", + "custom": "/10", + "unit": "A", + "warning": "45", + "critical": "50" + } + } +} +``` + +#### Calcul de puissance (courant × tension) + +À partir du courant brut, calculer la puissance en kW (tension supposée 230V) : + +```json +{ + "selection": { + "rawCurrent": { "address": 1045, "quantity": 1, "display": false } + }, + "virtualcurve": { + "currentA": { + "aggregation": "avg", + "custom": "/10", + "unit": "A" + }, + "powerKW": { + "aggregation": "avg", + "custom": "/10*230/1000", + "unit": "kW", + "formatting": { + "printf_msg": "Power '%s' is %.3f kW", + "printf_var": "$self->{result_values}->{instance}, $self->{result_values}->{value}" + } + } + } +} +``` + +#### Agrégation de plusieurs registres avec `pattern` + +Lire 4 registres d'un coup et calculer deux moyennes sur des paires : + +```json +{ + "selection": { + "phases": { + "address": 1, + "quantity": 4, + "type": "holding", + "display": false + } + }, + "virtualcurve": { + "avg_phases_12": { + "pattern": "phases\\.[01]$", + "aggregation": "avg", + "unit": "V" + }, + "avg_phases_34": { + "pattern": "phases\\.[23]$", + "aggregation": "avg", + "unit": "V" + } + } +} +``` + +> Les métriques `phases.0`, `phases.1`, `phases.2`, `phases.3` sont créées automatiquement par `quantity: 4`. Le `pattern` filtre ensuite lesquelles entrent dans chaque `virtualcurve`. + +### Exemple complet — Supervision d'un générateur électrique [inspiré d'un cas de la communauté](https://thewatch.centreon.com/infra-monitoring-data-collection-6/monitor-an-electric-generator-with-modbus-376) + +Ce fichier monitore la tension batterie, le courant et la puissance d'un groupe électrogène. L'équipement renvoie des valeurs ×10 (ex : `230` = `23.0 V`). + +```json +{ + "selection": { + "batteryVoltageRaw": { "address": 1029, "quantity": 1, "type": "holding", "display": false }, + "currentPhase1Raw": { "address": 1045, "quantity": 1, "type": "holding", "display": false }, + "currentPhase2Raw": { "address": 1046, "quantity": 1, "type": "holding", "display": false }, + "currentPhase3Raw": { "address": 1047, "quantity": 1, "type": "holding", "display": false } + }, + "virtualcurve": { + "batteryVoltage": { + "aggregation": "avg", + "custom": "/10", + "unit": "V", + "warning": "22", + "critical": "20", + "formatting": { + "printf_msg": "Battery voltage '%s' is %.1f V", + "printf_var": "$self->{result_values}->{instance}, $self->{result_values}->{value}" + } + }, + "currentPhase1": { + "pattern": "currentPhase1Raw", + "aggregation": "avg", + "custom": "/10", + "unit": "A", + "warning": "45", + "critical": "50" + }, + "powerPhase1": { + "pattern": "currentPhase1Raw", + "aggregation": "avg", + "custom": "/10*230/1000", + "unit": "kW" + }, + "currentPhase2": { + "pattern": "currentPhase2Raw", + "aggregation": "avg", + "custom": "/10", + "unit": "A", + "warning": "45", + "critical": "50" + }, + "currentPhase3": { + "pattern": "currentPhase3Raw", + "aggregation": "avg", + "custom": "/10", + "unit": "A", + "warning": "45", + "critical": "50" + } + } +} +``` + +### Format des seuils (`warning` / `critical`) + +Les seuils suivent la syntaxe standard Nagios/Centreon : + +| Exemple | Signification | +|-----------|-------------------------------------------------| +| `"50"` | Alerte si valeur > 50 | +| `"0:50"` | Alerte si valeur hors de `[0, 50]` | +| `"@0:50"` | Alerte si valeur **dans** `[0, 50]` (inversé) | +| `"~:50"` | Alerte si valeur > 50 (pas de borne inférieure) | +| `"50:"` | Alerte si valeur < 50 | + ### Diagnostic des erreurs communes Rendez-vous sur la [documentation dédiée](../getting-started/how-to-guides/troubleshooting-plugins.md) diff --git a/pp/integrations/plugin-packs/procedures/applications-protocol-modbus.md b/pp/integrations/plugin-packs/procedures/applications-protocol-modbus.md index fd73d84d1ba6..7785d7d83637 100644 --- a/pp/integrations/plugin-packs/procedures/applications-protocol-modbus.md +++ b/pp/integrations/plugin-packs/procedures/applications-protocol-modbus.md @@ -23,8 +23,8 @@ No services are created by default for this host template. -| Service Alias | Service Template | Service Description | -|:----------------------|:-------------------------------------------------|:----------------------------| +| Service Alias | Service Template | Service Description | +|:----------------------|:-------------------------------------------------|:---------------------------| | Numeric-Value-Generic | App-Protocol-Modbus-Numeric-Value-Generic-custom | Monitor metrics via Modbus | > The services listed above are not created automatically when a host template is applied. To use them, [create a service manually](/docs/monitoring/basic-objects/services), then apply the service template you want. @@ -157,10 +157,10 @@ yum install centreon-plugin-Applications-Protocol-Modbus -| Macro | Description | Default value | Mandatory | -|:-------------|:---------------------------------------------------------------------------------------------------|:------------------|:-----------:| -| CONFIG | Define the configuration of the check (can be a file or a json string directly). | | X | -| EXTRAOPTIONS | Any extra option you may want to add to the command (a --verbose flag for example). All options are listed [here](#available-options). | | | +| Macro | Description | Default value | Mandatory | +|:-------------|:---------------------------------------------------------------------------------------------------------------------------------------|:--------------|:---------:| +| CONFIG | Define the configuration of the check (can be a file or a json string directly). | | X | +| EXTRAOPTIONS | Any extra option you may want to add to the command (a --verbose flag for example). All options are listed [here](#available-options). | | | > **CONFIG :** More information is available [here](https://github.com/centreon/centreon-plugins/blob/master/doc/en/user/guide.rst#modbus-protocol). @@ -189,6 +189,352 @@ The expected command output is shown below: OK: All metrics are OK | 'metric1'=10;;;; 'metric2'=40;;;; 'metric3'=72;;;; ``` +> The JSON file content can also be passed directly: +> `--config='{ "selection": { "metric1": { ... } } }'` + +### General structure of the JSON file + +```json +{ + "selection": { ... }, + "virtualcurve": { ... }, + "command": { ... } +} +``` + +| Section | Required | Description | +|----------------|----------|-----------------------------------------------| +| `selection` | Yes | Defines the Modbus registers to read | +| `virtualcurve` | No | Aggregates and transforms the read values | +| `command` | No | Customizes the global formatting of the output | + + +### Section `selection` + +Each entry in `selection` corresponds to a Modbus register (or group of registers) to read. +The key is the **name of the resulting metric**. + +```json +{ + "selection": { + "": { + "address": , + "quantity": , + "type": "", + "display": , + "formatting": { ... } + } + } +} +``` + +#### Available keys in `selection` + +| Key | Type | Required | Description | +|--------------|---------|----------|--------------------------------------------------------------------------| +| `address` | integer | Yes | Modbus register address (decimal) | +| `quantity` | integer | Yes | Number of consecutive registers to read | +| `type` | string | No | Register type (see values below). Default: `holding` | +| `display` | boolean | No | Display the raw value in the output. Default: `true` | +| `formatting` | object | No | Customize the output message (see [Formatting](#formatting) section) | + +#### Possible values for `type` + +| Value | Description | +|------------|--------------------------------------------------------------| +| `holding` | Holding register (read/write) — most common | +| `input` | Input register (read-only) | +| `coil` | Coil (binary value 0/1, read/write) | +| `discrete` | Discrete input (binary value 0/1, read-only) | + +#### Minimal example + +```json +{ + "selection": { + "temperature": { + "address": 100, + "quantity": 1, + "type": "holding", + "display": true + } + } +} +``` + +#### Example with multiple metrics + +```json +{ + "selection": { + "metric1": { "address": 1, "quantity": 1, "type": "holding", "display": true }, + "metric2": { "address": 2, "quantity": 1, "type": "holding", "display": true }, + "metric3": { "address": 3, "quantity": 1, "type": "holding", "display": true } + } +} +``` + +#### Reading multiple registers at once (`quantity > 1`) + +When `quantity` is greater than 1, the plugin reads multiple consecutive registers and names them automatically `.0`, `.1`, etc. +This is useful to reduce network exchanges on low-bandwidth links. + +```json +{ + "selection": { + "phases": { + "address": 1045, + "quantity": 3, + "type": "holding", + "display": false + } + } +} +``` + +> The generated metrics will be named: `phases.0`, `phases.1`, `phases.2` + +### Section `virtualcurve` + +The `virtualcurve` section allows you to create derived metrics from the values read in `selection`. It is essential for: +- Applying a scaling factor (e.g. dividing by 10 if the device returns `153` for `15.3A`) +- Aggregating multiple registers (average, sum, min, max) +- Defining warning and critical thresholds +- Performing complex calculations (e.g. power = current × voltage) + +```json +{ + "virtualcurve": { + "": { + "aggregation": "", + "pattern": "", + "custom": "", + "unit": "", + "warning": "", + "critical": "", + "formatting": { ... } + } + } +} +``` + +#### Available keys in `virtualcurve` + +| Key | Type | Required | Description | +|---------------|--------|----------|--------------------------------------------------------------------------------------------------------------------------------| +| `aggregation` | string | Yes | Aggregation method for the selected values | +| `pattern` | string | No | Regular expression to filter source metrics from `selection`. If absent, all metrics are used | +| `custom` | string | No | Arithmetic expression applied to the aggregated value | +| `unit` | string | No | Unit of the resulting metric (e.g. `A`, `W`, `°C`) | +| `warning` | string | No | Warning threshold (Nagios format: simple value or range `min:max`) | +| `critical` | string | No | Critical threshold (Nagios format: simple value or range `min:max`) | +| `formatting` | object | No | Customize the output message (see [Formatting](#formatting) section) | + +#### Possible values for `aggregation` + +| Value | Description | +|-------|---------------------------------------------| +| `avg` | Average of the selected values | +| `sum` | Sum of the selected values | +| `min` | Minimum value among the selected values | +| `max` | Maximum value among the selected values | + +### Section `command` (global formatting) + +The `command` section allows you to modify the display of all metrics globally, and to override this behavior for a specific metric via `override`. + +```json +{ + "selection": { ... }, + "command": { + "formatting": { + "printf_msg": "My Metric '%s' value is %.2f", + "printf_var": "$self->{result_values}->{instance}, $self->{result_values}->{value}" + }, + "override": { + "metric3": { + "formatting": { + "printf_msg": "Override '%s' value is %.2f", + "printf_var": "$self->{result_values}->{instance}, $self->{result_values}->{value}" + } + } + } + } +} +``` + +### Formatting output messages {#formatting} + +The `formatting` object (available in `selection`, `virtualcurve` or `command`) allows you to customize the text displayed for each metric. + +| Key | Description | +|--------------|---------------------------------------------------------------------------------| +| `printf_msg` | Message format, Perl `printf` syntax (e.g. `"Metric '%s' value is %.2f"`) | +| `printf_var` | Perl variables to inject into the message | + +Available variables in `printf_var`: + +| Variable | Content | +|--------------------------------------|------------------------------| +| `$self->{result_values}->{instance}` | Name of the metric | +| `$self->{result_values}->{value}` | Numeric value of the metric | + +### Examples of custom calculations (`custom`) + +The `custom` attribute accepts a Perl arithmetic expression that will be applied to the aggregated value. +The current value is implicit — the expression starts directly with the operator. + +#### Simple scaling + +The device returns `1530` to represent `15.3 A`: + +```json +{ + "selection": { + "rawCurrent": { "address": 1045, "quantity": 1, "display": false } + }, + "virtualcurve": { + "currentA": { + "aggregation": "avg", + "custom": "/10", + "unit": "A", + "warning": "45", + "critical": "50" + } + } +} +``` + +#### Power calculation (current × voltage) + +From the raw current value, calculate the power in kW (assuming 230V voltage): + +```json +{ + "selection": { + "rawCurrent": { "address": 1045, "quantity": 1, "display": false } + }, + "virtualcurve": { + "currentA": { + "aggregation": "avg", + "custom": "/10", + "unit": "A" + }, + "powerKW": { + "aggregation": "avg", + "custom": "/10*230/1000", + "unit": "kW", + "formatting": { + "printf_msg": "Power '%s' is %.3f kW", + "printf_var": "$self->{result_values}->{instance}, $self->{result_values}->{value}" + } + } + } +} +``` + +#### Aggregating multiple registers with `pattern` + +Read 4 registers at once and calculate two averages over pairs: + +```json +{ + "selection": { + "phases": { + "address": 1, + "quantity": 4, + "type": "holding", + "display": false + } + }, + "virtualcurve": { + "avg_phases_12": { + "pattern": "phases\\.[01]$", + "aggregation": "avg", + "unit": "V" + }, + "avg_phases_34": { + "pattern": "phases\\.[23]$", + "aggregation": "avg", + "unit": "V" + } + } +} +``` + +> The metrics `phases.0`, `phases.1`, `phases.2`, `phases.3` are created automatically by `quantity: 4`. The `pattern` then filters which ones are included in each `virtualcurve`. + +### Full example — Monitoring an electric generator [based on a community use case](https://thewatch.centreon.com/infra-monitoring-data-collection-6/monitor-an-electric-generator-with-modbus-376) + +This file monitors the battery voltage, current and power of a generator. The device returns values ×10 (e.g. `230` = `23.0 V`). + +```json +{ + "selection": { + "batteryVoltageRaw": { "address": 1029, "quantity": 1, "type": "holding", "display": false }, + "currentPhase1Raw": { "address": 1045, "quantity": 1, "type": "holding", "display": false }, + "currentPhase2Raw": { "address": 1046, "quantity": 1, "type": "holding", "display": false }, + "currentPhase3Raw": { "address": 1047, "quantity": 1, "type": "holding", "display": false } + }, + "virtualcurve": { + "batteryVoltage": { + "aggregation": "avg", + "custom": "/10", + "unit": "V", + "warning": "22", + "critical": "20", + "formatting": { + "printf_msg": "Battery voltage '%s' is %.1f V", + "printf_var": "$self->{result_values}->{instance}, $self->{result_values}->{value}" + } + }, + "currentPhase1": { + "pattern": "currentPhase1Raw", + "aggregation": "avg", + "custom": "/10", + "unit": "A", + "warning": "45", + "critical": "50" + }, + "powerPhase1": { + "pattern": "currentPhase1Raw", + "aggregation": "avg", + "custom": "/10*230/1000", + "unit": "kW" + }, + "currentPhase2": { + "pattern": "currentPhase2Raw", + "aggregation": "avg", + "custom": "/10", + "unit": "A", + "warning": "45", + "critical": "50" + }, + "currentPhase3": { + "pattern": "currentPhase3Raw", + "aggregation": "avg", + "custom": "/10", + "unit": "A", + "warning": "45", + "critical": "50" + } + } +} +``` + +### Threshold format (`warning` / `critical`) + +Thresholds follow the standard Nagios/Centreon syntax: + +| Example | Meaning | +|-----------|------------------------------------------------------| +| `"50"` | Alert if value > 50 | +| `"0:50"` | Alert if value is outside `[0, 50]` | +| `"@0:50"` | Alert if value is **inside** `[0, 50]` (inverted) | +| `"~:50"` | Alert if value > 50 (no lower bound) | +| `"50:"` | Alert if value < 50 | + + ### Troubleshooting Please find the [troubleshooting documentation](../getting-started/how-to-guides/troubleshooting-plugins.md)