Adding upstream version 1.43.0.upstream/1.43.0

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

19 files changed, 1216 insertions, 382 deletions

diff --git a/collectors/charts.d.plugin/ap/README.md b/collectors/charts.d.plugin/ap/README.md
index 339ad1375..5b6e75130 100644..120000
--- a/collectors/charts.d.plugin/ap/README.md
+++ b/collectors/charts.d.plugin/ap/README.md
@@ -1,104 +1 @@
-<!--
-title: "Access point monitoring with Netdata"
-custom_edit_url: "https://github.com/netdata/netdata/edit/master/collectors/charts.d.plugin/ap/README.md"
-sidebar_label: "Access points"
-learn_status: "Published"
-learn_topic_type: "References"
-learn_rel_path: "Integrations/Monitor/Remotes/Devices"
--->
-
-# Access point collector
-
-The `ap` collector visualizes data related to access points.
-
-## Example Netdata charts
-
-![image](https://cloud.githubusercontent.com/assets/2662304/12377654/9f566e88-bd2d-11e5-855a-e0ba96b8fd98.png)
-
-## How it works
-
-It does the following:
-
-1.  Runs `iw dev` searching for interfaces that have `type AP`.
-
-    From the same output it collects the SSIDs each AP supports by looking for lines `ssid NAME`.
-
-    Example:
-
-```sh
-# iw dev
-phy#0
-        Interface wlan0
-                ifindex 3
-                wdev 0x1
-                addr 7c:dd:90:77:34:2a
-                ssid TSAOUSIS
-                type AP
-                channel 7 (2442 MHz), width: 20 MHz, center1: 2442 MHz
-```
-
-2.  For each interface found, it runs `iw INTERFACE station dump`.
-
-    From the output is collects:
-
-    -   rx/tx bytes
-    -   rx/tx packets
-    -   tx retries
-    -   tx failed
-    -   signal strength
-    -   rx/tx bitrate
-    -   expected throughput
-
-    Example:
-
-```sh
-# iw wlan0 station dump
-Station 40:b8:37:5a:ed:5e (on wlan0)
-        inactive time:  910 ms
-        rx bytes:       15588897
-        rx packets:     127772
-        tx bytes:       52257763
-        tx packets:     95802
-        tx retries:     2162
-        tx failed:      28
-        signal:         -43 dBm
-        signal avg:     -43 dBm
-        tx bitrate:     65.0 MBit/s MCS 7
-        rx bitrate:     1.0 MBit/s
-        expected throughput:    32.125Mbps
-        authorized:     yes
-        authenticated:  yes
-        preamble:       long
-        WMM/WME:        yes
-        MFP:            no
-        TDLS peer:      no
-```
-
-3.  For each interface found, it creates 6 charts:
-
-    -   Number of Connected clients
-    -   Bandwidth for all clients
-    -   Packets for all clients
-    -   Transmit Issues for all clients
-    -   Average Signal among all clients
-    -   Average Bitrate (including average expected throughput) among all clients
-
-## Configuration
-
-If using [our official native DEB/RPM packages](https://github.com/netdata/netdata/blob/master/packaging/installer/methods/packages.md), make sure `netdata-plugin-chartsd` is installed.
-
-Edit the `charts.d/ap.conf` configuration file using `edit-config` from the Netdata [config
-directory](https://github.com/netdata/netdata/blob/master/docs/configure/nodes.md), which is typically at `/etc/netdata`.
-
-```bash
-cd /etc/netdata   # Replace this path with your Netdata config directory, if different
-sudo ./edit-config charts.d/ap.conf
-```
-
-You can only set `ap_update_every=NUMBER` to change the data collection frequency.
-
-## Auto-detection
-
-The plugin is able to auto-detect if you are running access points on your linux box.
-
-
+integrations/access_points.md
\ No newline at end of file
diff --git a/collectors/charts.d.plugin/ap/integrations/access_points.md b/collectors/charts.d.plugin/ap/integrations/access_points.md
new file mode 100644
index 000000000..0d8d39046
--- /dev/null
+++ b/collectors/charts.d.plugin/ap/integrations/access_points.md
@@ -0,0 +1,173 @@
+<!--startmeta
+custom_edit_url: "https://github.com/netdata/netdata/edit/master/collectors/charts.d.plugin/ap/README.md"
+meta_yaml: "https://github.com/netdata/netdata/edit/master/collectors/charts.d.plugin/ap/metadata.yaml"
+sidebar_label: "Access Points"
+learn_status: "Published"
+learn_rel_path: "Data Collection/Linux Systems/Network"
+message: "DO NOT EDIT THIS FILE DIRECTLY, IT IS GENERATED BY THE COLLECTOR'S metadata.yaml FILE"
+endmeta-->
+
+# Access Points
+
+
+<img src="https://netdata.cloud/img/network-wired.svg" width="150"/>
+
+
+Plugin: charts.d.plugin
+Module: ap
+
+<img src="https://img.shields.io/badge/maintained%20by-Netdata-%2300ab44" />
+
+## Overview
+
+The ap collector visualizes data related to wireless access points.
+
+It uses the `iw` command line utility to detect access points. For each interface that is of `type AP`, it then runs `iw INTERFACE station dump` and collects statistics.
+
+This collector is only supported on the following platforms:
+
+- Linux
+
+This collector only supports collecting metrics from a single instance of this integration.
+
+
+### Default Behavior
+
+#### Auto-Detection
+
+The plugin is able to auto-detect if you are running access points on your linux box.
+
+#### Limits
+
+The default configuration for this integration does not impose any limits on data collection.
+
+#### Performance Impact
+
+The default configuration for this integration is not expected to impose a significant performance impact on the system.
+
+
+## Metrics
+
+Metrics grouped by *scope*.
+
+The scope defines the instance that the metric belongs to. An instance is uniquely identified by a set of labels.
+
+
+
+### Per wireless device
+
+These metrics refer to the entire monitored application.
+
+This scope has no labels.
+
+Metrics:
+
+| Metric | Dimensions | Unit |
+|:------|:----------|:----|
+| ap.clients | clients | clients |
+| ap.net | received, sent | kilobits/s |
+| ap.packets | received, sent | packets/s |
+| ap.issues | retries, failures | issues/s |
+| ap.signal | average signal | dBm |
+| ap.bitrate | receive, transmit, expected | Mbps |
+
+
+
+## Alerts
+
+There are no alerts configured by default for this integration.
+
+
+## Setup
+
+### Prerequisites
+
+#### Install charts.d plugin
+
+If [using our official native DEB/RPM packages](https://github.com/netdata/netdata/blob/master/packaging/installer/UPDATE.md#determine-which-installation-method-you-used), make sure `netdata-plugin-chartsd` is installed.
+
+
+#### `iw` utility.
+
+Make sure the `iw` utility is installed.
+
+
+### Configuration
+
+#### File
+
+The configuration file name for this integration is `charts.d/ap.conf`.
+
+
+You can edit the configuration file using the `edit-config` script from the
+Netdata [config directory](https://github.com/netdata/netdata/blob/master/docs/configure/nodes.md#the-netdata-config-directory).
+
+```bash
+cd /etc/netdata 2>/dev/null || cd /opt/netdata/etc/netdata
+sudo ./edit-config charts.d/ap.conf
+```
+#### Options
+
+The config file is sourced by the charts.d plugin. It's a standard bash file.
+
+The following collapsed table contains all the options that can be configured for the ap collector.
+
+
+<details><summary>Config options</summary>
+
+| Name | Description | Default | Required |
+|:----|:-----------|:-------|:--------:|
+| ap_update_every | The data collection frequency. If unset, will inherit the netdata update frequency. | 1 | False |
+| ap_priority | Controls the order of charts at the netdata dashboard. | 6900 | False |
+| ap_retries | The number of retries to do in case of failure before disabling the collector. | 10 | False |
+
+</details>
+
+#### Examples
+
+##### Change the collection frequency
+
+Specify a custom collection frequence (update_every) for this collector
+
+```yaml
+# the data collection frequency
+# if unset, will inherit the netdata update frequency
+ap_update_every=10
+
+# the charts priority on the dashboard
+#ap_priority=6900
+
+# the number of retries to do in case of failure
+# before disabling the module
+#ap_retries=10
+
+```
+
+
+## Troubleshooting
+
+### Debug Mode
+
+To troubleshoot issues with the `ap` collector, run the `charts.d.plugin` with the debug option enabled. The output
+should give you clues as to why the collector isn't working.
+
+- Navigate to the `plugins.d` directory, usually at `/usr/libexec/netdata/plugins.d/`. If that's not the case on
+  your system, open `netdata.conf` and look for the `plugins` setting under `[directories]`.
+
+  ```bash
+  cd /usr/libexec/netdata/plugins.d/
+  ```
+
+- Switch to the `netdata` user.
+
+  ```bash
+  sudo -u netdata -s
+  ```
+
+- Run the `charts.d.plugin` to debug the collector:
+
+  ```bash
+  ./charts.d.plugin debug 1 ap
+  ```
+
+
diff --git a/collectors/charts.d.plugin/ap/metadata.yaml b/collectors/charts.d.plugin/ap/metadata.yaml
index c4e96a14a..ee941e417 100644
--- a/collectors/charts.d.plugin/ap/metadata.yaml
+++ b/collectors/charts.d.plugin/ap/metadata.yaml
@@ -41,6 +41,9 @@ modules:
     setup:
       prerequisites:
         list:
+          - title: "Install charts.d plugin"
+            description: |
+              If [using our official native DEB/RPM packages](https://github.com/netdata/netdata/blob/master/packaging/installer/UPDATE.md#determine-which-installation-method-you-used), make sure `netdata-plugin-chartsd` is installed.
           - title: "`iw` utility."
             description: "Make sure the `iw` utility is installed."
       configuration:
diff --git a/collectors/charts.d.plugin/apcupsd/README.md b/collectors/charts.d.plugin/apcupsd/README.md
index 00e9697dc..fc6681fe6 100644..120000
--- a/collectors/charts.d.plugin/apcupsd/README.md
+++ b/collectors/charts.d.plugin/apcupsd/README.md
@@ -1,26 +1 @@
-<!--
-title: "APC UPS monitoring with Netdata"
-custom_edit_url: "https://github.com/netdata/netdata/edit/master/collectors/charts.d.plugin/apcupsd/README.md"
-sidebar_label: "APC UPS"
-learn_status: "Published"
-learn_topic_type: "References"
-learn_rel_path: "Integrations/Monitor/Remotes/Devices"
--->
-
-# APC UPS collector
-
-Monitors different APC UPS models and retrieves status information using `apcaccess` tool.
-
-## Configuration
-
-If using [our official native DEB/RPM packages](https://github.com/netdata/netdata/blob/master/packaging/installer/methods/packages.md), make sure `netdata-plugin-chartsd` is installed.
-
-Edit the `charts.d/apcupsd.conf` configuration file using `edit-config` from the Netdata [config
-directory](https://github.com/netdata/netdata/blob/master/docs/configure/nodes.md), which is typically at `/etc/netdata`.
-
-```bash
-cd /etc/netdata   # Replace this path with your Netdata config directory, if different
-sudo ./edit-config charts.d/apcupsd.conf
-```
-
-
+integrations/apc_ups.md
\ No newline at end of file
diff --git a/collectors/charts.d.plugin/apcupsd/integrations/apc_ups.md b/collectors/charts.d.plugin/apcupsd/integrations/apc_ups.md
new file mode 100644
index 000000000..4d1f2edd6
--- /dev/null
+++ b/collectors/charts.d.plugin/apcupsd/integrations/apc_ups.md
@@ -0,0 +1,193 @@
+<!--startmeta
+custom_edit_url: "https://github.com/netdata/netdata/edit/master/collectors/charts.d.plugin/apcupsd/README.md"
+meta_yaml: "https://github.com/netdata/netdata/edit/master/collectors/charts.d.plugin/apcupsd/metadata.yaml"
+sidebar_label: "APC UPS"
+learn_status: "Published"
+learn_rel_path: "Data Collection/UPS"
+message: "DO NOT EDIT THIS FILE DIRECTLY, IT IS GENERATED BY THE COLLECTOR'S metadata.yaml FILE"
+endmeta-->
+
+# APC UPS
+
+
+<img src="https://netdata.cloud/img/apc.svg" width="150"/>
+
+
+Plugin: charts.d.plugin
+Module: apcupsd
+
+<img src="https://img.shields.io/badge/maintained%20by-Netdata-%2300ab44" />
+
+## Overview
+
+Monitor APC UPS performance with Netdata for optimal uninterruptible power supply operations. Enhance your power supply reliability with real-time APC UPS metrics.
+
+The collector uses the `apcaccess` tool to contact the `apcupsd` daemon and get the APC UPS statistics.
+
+This collector is supported on all platforms.
+
+This collector only supports collecting metrics from a single instance of this integration.
+
+
+### Default Behavior
+
+#### Auto-Detection
+
+By default, with no configuration provided, the collector will try to contact 127.0.0.1:3551 with using the `apcaccess` utility.
+
+#### Limits
+
+The default configuration for this integration does not impose any limits on data collection.
+
+#### Performance Impact
+
+The default configuration for this integration is not expected to impose a significant performance impact on the system.
+
+
+## Metrics
+
+Metrics grouped by *scope*.
+
+The scope defines the instance that the metric belongs to. An instance is uniquely identified by a set of labels.
+
+
+
+### Per ups
+
+Metrics related to UPS. Each UPS provides its own set of the following metrics.
+
+This scope has no labels.
+
+Metrics:
+
+| Metric | Dimensions | Unit |
+|:------|:----------|:----|
+| apcupsd.charge | charge | percentage |
+| apcupsd.battery.voltage | voltage, nominal | Volts |
+| apcupsd.input.voltage | voltage, min, max | Volts |
+| apcupsd.output.voltage | absolute, nominal | Volts |
+| apcupsd.input.frequency | frequency | Hz |
+| apcupsd.load | load | percentage |
+| apcupsd.load_usage | load | Watts |
+| apcupsd.temperature | temp | Celsius |
+| apcupsd.time | time | Minutes |
+| apcupsd.online | online | boolean |
+
+
+
+## Alerts
+
+
+The following alerts are available:
+
+| Alert name  | On metric | Description |
+|:------------|:----------|:------------|
+| [ apcupsd_ups_charge ](https://github.com/netdata/netdata/blob/master/health/health.d/apcupsd.conf) | apcupsd.charge | average UPS charge over the last minute |
+| [ apcupsd_10min_ups_load ](https://github.com/netdata/netdata/blob/master/health/health.d/apcupsd.conf) | apcupsd.load | average UPS load over the last 10 minutes |
+| [ apcupsd_last_collected_secs ](https://github.com/netdata/netdata/blob/master/health/health.d/apcupsd.conf) | apcupsd.load | number of seconds since the last successful data collection |
+
+
+## Setup
+
+### Prerequisites
+
+#### Install charts.d plugin
+
+If [using our official native DEB/RPM packages](https://github.com/netdata/netdata/blob/master/packaging/installer/UPDATE.md#determine-which-installation-method-you-used), make sure `netdata-plugin-chartsd` is installed.
+
+
+#### Required software
+
+Make sure the `apcaccess` and `apcupsd` are installed and running.
+
+
+### Configuration
+
+#### File
+
+The configuration file name for this integration is `charts.d/apcupsd.conf`.
+
+
+You can edit the configuration file using the `edit-config` script from the
+Netdata [config directory](https://github.com/netdata/netdata/blob/master/docs/configure/nodes.md#the-netdata-config-directory).
+
+```bash
+cd /etc/netdata 2>/dev/null || cd /opt/netdata/etc/netdata
+sudo ./edit-config charts.d/apcupsd.conf
+```
+#### Options
+
+The config file is sourced by the charts.d plugin. It's a standard bash file.
+
+The following collapsed table contains all the options that can be configured for the apcupsd collector.
+
+
+<details><summary>Config options</summary>
+
+| Name | Description | Default | Required |
+|:----|:-----------|:-------|:--------:|
+| apcupsd_sources | This is an array of apcupsd sources. You can have multiple entries there. Please refer to the example below on how to set it. | 127.0.0.1:3551 | False |
+| apcupsd_timeout | How long to wait for apcupsd to respond. | 3 | False |
+| apcupsd_update_every | The data collection frequency. If unset, will inherit the netdata update frequency. | 1 | False |
+| apcupsd_priority | The charts priority on the dashboard. | 90000 | False |
+| apcupsd_retries | The number of retries to do in case of failure before disabling the collector. | 10 | False |
+
+</details>
+
+#### Examples
+
+##### Multiple apcupsd sources
+
+Specify a multiple apcupsd sources along with a custom update interval
+
+```yaml
+# add all your APC UPSes in this array - uncomment it too
+declare -A apcupsd_sources=(
+    ["local"]="127.0.0.1:3551",
+    ["remote"]="1.2.3.4:3551"
+)
+
+# how long to wait for apcupsd to respond
+#apcupsd_timeout=3
+
+# the data collection frequency
+# if unset, will inherit the netdata update frequency
+apcupsd_update_every=5
+
+# the charts priority on the dashboard
+#apcupsd_priority=90000
+
+# the number of retries to do in case of failure
+# before disabling the module
+#apcupsd_retries=10
+
+```
+
+
+## Troubleshooting
+
+### Debug Mode
+
+To troubleshoot issues with the `apcupsd` collector, run the `charts.d.plugin` with the debug option enabled. The output
+should give you clues as to why the collector isn't working.
+
+- Navigate to the `plugins.d` directory, usually at `/usr/libexec/netdata/plugins.d/`. If that's not the case on
+  your system, open `netdata.conf` and look for the `plugins` setting under `[directories]`.
+
+  ```bash
+  cd /usr/libexec/netdata/plugins.d/
+  ```
+
+- Switch to the `netdata` user.
+
+  ```bash
+  sudo -u netdata -s
+  ```
+
+- Run the `charts.d.plugin` to debug the collector:
+
+  ```bash
+  ./charts.d.plugin debug 1 apcupsd
+  ```
+
+
diff --git a/collectors/charts.d.plugin/apcupsd/metadata.yaml b/collectors/charts.d.plugin/apcupsd/metadata.yaml
index d078074b7..07d56d48d 100644
--- a/collectors/charts.d.plugin/apcupsd/metadata.yaml
+++ b/collectors/charts.d.plugin/apcupsd/metadata.yaml
@@ -42,6 +42,9 @@ modules:
     setup:
       prerequisites:
         list:
+          - title: "Install charts.d plugin"
+            description: |
+              If [using our official native DEB/RPM packages](https://github.com/netdata/netdata/blob/master/packaging/installer/UPDATE.md#determine-which-installation-method-you-used), make sure `netdata-plugin-chartsd` is installed.
           - title: "Required software"
             description: "Make sure the `apcaccess` and `apcupsd` are installed and running."
       configuration:
diff --git a/collectors/charts.d.plugin/charts.d.plugin.in b/collectors/charts.d.plugin/charts.d.plugin.in
index 20996eb93..34a5a656e 100755
--- a/collectors/charts.d.plugin/charts.d.plugin.in
+++ b/collectors/charts.d.plugin/charts.d.plugin.in
@@ -20,6 +20,21 @@ PROGRAM_NAME="$(basename $0)"
 PROGRAM_NAME="${PROGRAM_NAME/.plugin/}"
 MODULE_NAME="main"
 
+LOG_LEVEL_ERR=1
+LOG_LEVEL_WARN=2
+LOG_LEVEL_INFO=3
+LOG_LEVEL="$LOG_LEVEL_INFO"
+
+set_log_severity_level() {
+  case ${NETDATA_LOG_SEVERITY_LEVEL,,} in
+    "info") LOG_LEVEL="$LOG_LEVEL_INFO";;
+    "warn" | "warning") LOG_LEVEL="$LOG_LEVEL_WARN";;
+    "err" | "error") LOG_LEVEL="$LOG_LEVEL_ERR";;
+  esac
+}
+
+set_log_severity_level
+
 # -----------------------------------------------------------------------------
 # create temp dir
 
@@ -55,16 +70,19 @@ log() {
 
 }
 
-warning() {
-	log WARNING "${@}"
+info() {
+  [[ -n "$LOG_LEVEL" && "$LOG_LEVEL_INFO" -gt "$LOG_LEVEL" ]] && return
+  log INFO "${@}"
 }
 
-error() {
-	log ERROR "${@}"
+warning() {
+  [[ -n "$LOG_LEVEL" && "$LOG_LEVEL_WARN" -gt "$LOG_LEVEL" ]] && return
+  log WARNING "${@}"
 }
 
-info() {
-	log INFO "${@}"
+error() {
+  [[ -n "$LOG_LEVEL" && "$LOG_LEVEL_ERR" -gt "$LOG_LEVEL" ]] && return
+  log ERROR "${@}"
 }
 
 fatal() {
diff --git a/collectors/charts.d.plugin/libreswan/README.md b/collectors/charts.d.plugin/libreswan/README.md
index b6eeb0180..1416d9597 100644..120000
--- a/collectors/charts.d.plugin/libreswan/README.md
+++ b/collectors/charts.d.plugin/libreswan/README.md
@@ -1,61 +1 @@
-<!--
-title: "Libreswan IPSec tunnel monitoring with Netdata"
-custom_edit_url: "https://github.com/netdata/netdata/edit/master/collectors/charts.d.plugin/libreswan/README.md"
-sidebar_label: "Libreswan IPSec tunnels"
-learn_status: "Published"
-learn_topic_type: "References"
-learn_rel_path: "Integrations/Monitor/Networking"
--->
-
-# Libreswan IPSec tunnel collector
-
-Collects bytes-in, bytes-out and uptime for all established libreswan IPSEC tunnels.
-
-The following charts are created, **per tunnel**:
-
-1.  **Uptime**
-
--   the uptime of the tunnel
-
-2.  **Traffic**
-
--   bytes in
--   bytes out
-
-## Configuration
-
-If using [our official native DEB/RPM packages](https://github.com/netdata/netdata/blob/master/packaging/installer/methods/packages.md), make sure `netdata-plugin-chartsd` is installed.
-
-Edit the `charts.d/libreswan.conf` configuration file using `edit-config` from the Netdata [config
-directory](https://github.com/netdata/netdata/blob/master/docs/configure/nodes.md), which is typically at `/etc/netdata`.
-
-```bash
-cd /etc/netdata   # Replace this path with your Netdata config directory, if different
-sudo ./edit-config charts.d/libreswan.conf
-```
-
-The plugin executes 2 commands to collect all the information it needs:
-
-```sh
-ipsec whack --status
-ipsec whack --trafficstatus
-```
-
-The first command is used to extract the currently established tunnels, their IDs and their names.
-The second command is used to extract the current uptime and traffic.
-
-Most probably user `netdata` will not be able to query libreswan, so the `ipsec` commands will be denied.
-The plugin attempts to run `ipsec` as `sudo ipsec ...`, to get access to libreswan statistics.
-
-To allow user `netdata` execute `sudo ipsec ...`, create the file `/etc/sudoers.d/netdata` with this content:
-
-```
-netdata ALL = (root) NOPASSWD: /sbin/ipsec whack --status
-netdata ALL = (root) NOPASSWD: /sbin/ipsec whack --trafficstatus
-```
-
-Make sure the path `/sbin/ipsec` matches your setup (execute `which ipsec` to find the right path).
-
----
-
-
+integrations/libreswan.md
\ No newline at end of file
diff --git a/collectors/charts.d.plugin/libreswan/integrations/libreswan.md b/collectors/charts.d.plugin/libreswan/integrations/libreswan.md
new file mode 100644
index 000000000..6f93a5f4c
--- /dev/null
+++ b/collectors/charts.d.plugin/libreswan/integrations/libreswan.md
@@ -0,0 +1,193 @@
+<!--startmeta
+custom_edit_url: "https://github.com/netdata/netdata/edit/master/collectors/charts.d.plugin/libreswan/README.md"
+meta_yaml: "https://github.com/netdata/netdata/edit/master/collectors/charts.d.plugin/libreswan/metadata.yaml"
+sidebar_label: "Libreswan"
+learn_status: "Published"
+learn_rel_path: "Data Collection/VPNs"
+message: "DO NOT EDIT THIS FILE DIRECTLY, IT IS GENERATED BY THE COLLECTOR'S metadata.yaml FILE"
+endmeta-->
+
+# Libreswan
+
+
+<img src="https://netdata.cloud/img/libreswan.png" width="150"/>
+
+
+Plugin: charts.d.plugin
+Module: libreswan
+
+<img src="https://img.shields.io/badge/maintained%20by-Netdata-%2300ab44" />
+
+## Overview
+
+Monitor Libreswan performance for optimal IPsec VPN operations. Improve your VPN operations with Netdata''s real-time metrics and built-in alerts.
+
+The collector uses the `ipsec` command to collect the information it needs.
+
+This collector is supported on all platforms.
+
+This collector supports collecting metrics from multiple instances of this integration, including remote instances.
+
+
+### Default Behavior
+
+#### Auto-Detection
+
+This integration doesn't support auto-detection.
+
+#### Limits
+
+The default configuration for this integration does not impose any limits on data collection.
+
+#### Performance Impact
+
+The default configuration for this integration is not expected to impose a significant performance impact on the system.
+
+
+## Metrics
+
+Metrics grouped by *scope*.
+
+The scope defines the instance that the metric belongs to. An instance is uniquely identified by a set of labels.
+
+
+
+### Per IPSEC tunnel
+
+Metrics related to IPSEC tunnels. Each tunnel provides its own set of the following metrics.
+
+This scope has no labels.
+
+Metrics:
+
+| Metric | Dimensions | Unit |
+|:------|:----------|:----|
+| libreswan.net | in, out | kilobits/s |
+| libreswan.uptime | uptime | seconds |
+
+
+
+## Alerts
+
+There are no alerts configured by default for this integration.
+
+
+## Setup
+
+### Prerequisites
+
+#### Install charts.d plugin
+
+If [using our official native DEB/RPM packages](https://github.com/netdata/netdata/blob/master/packaging/installer/UPDATE.md#determine-which-installation-method-you-used), make sure `netdata-plugin-chartsd` is installed.
+
+
+#### Permissions to execute `ipsec`
+
+The plugin executes 2 commands to collect all the information it needs:
+
+```sh
+ipsec whack --status
+ipsec whack --trafficstatus
+```
+
+The first command is used to extract the currently established tunnels, their IDs and their names.
+The second command is used to extract the current uptime and traffic.
+
+Most probably user `netdata` will not be able to query libreswan, so the `ipsec` commands will be denied.
+The plugin attempts to run `ipsec` as `sudo ipsec ...`, to get access to libreswan statistics.
+
+To allow user `netdata` execute `sudo ipsec ...`, create the file `/etc/sudoers.d/netdata` with this content:
+
+```
+netdata ALL = (root) NOPASSWD: /sbin/ipsec whack --status
+netdata ALL = (root) NOPASSWD: /sbin/ipsec whack --trafficstatus
+```
+
+Make sure the path `/sbin/ipsec` matches your setup (execute `which ipsec` to find the right path).
+
+
+
+### Configuration
+
+#### File
+
+The configuration file name for this integration is `charts.d/libreswan.conf`.
+
+
+You can edit the configuration file using the `edit-config` script from the
+Netdata [config directory](https://github.com/netdata/netdata/blob/master/docs/configure/nodes.md#the-netdata-config-directory).
+
+```bash
+cd /etc/netdata 2>/dev/null || cd /opt/netdata/etc/netdata
+sudo ./edit-config charts.d/libreswan.conf
+```
+#### Options
+
+The config file is sourced by the charts.d plugin. It's a standard bash file.
+
+The following collapsed table contains all the options that can be configured for the libreswan collector.
+
+
+<details><summary>Config options</summary>
+
+| Name | Description | Default | Required |
+|:----|:-----------|:-------|:--------:|
+| libreswan_update_every | The data collection frequency. If unset, will inherit the netdata update frequency. | 1 | False |
+| libreswan_priority | The charts priority on the dashboard | 90000 | False |
+| libreswan_retries | The number of retries to do in case of failure before disabling the collector. | 10 | False |
+| libreswan_sudo | Whether to run `ipsec` with `sudo` or not. | 1 | False |
+
+</details>
+
+#### Examples
+
+##### Run `ipsec` without sudo
+
+Run the `ipsec` utility without sudo
+
+```yaml
+# the data collection frequency
+# if unset, will inherit the netdata update frequency
+#libreswan_update_every=1
+
+# the charts priority on the dashboard
+#libreswan_priority=90000
+
+# the number of retries to do in case of failure
+# before disabling the module
+#libreswan_retries=10
+
+# set to 1, to run ipsec with sudo (the default)
+# set to 0, to run ipsec without sudo
+libreswan_sudo=0
+
+```
+
+
+## Troubleshooting
+
+### Debug Mode
+
+To troubleshoot issues with the `libreswan` collector, run the `charts.d.plugin` with the debug option enabled. The output
+should give you clues as to why the collector isn't working.
+
+- Navigate to the `plugins.d` directory, usually at `/usr/libexec/netdata/plugins.d/`. If that's not the case on
+  your system, open `netdata.conf` and look for the `plugins` setting under `[directories]`.
+
+  ```bash
+  cd /usr/libexec/netdata/plugins.d/
+  ```
+
+- Switch to the `netdata` user.
+
+  ```bash
+  sudo -u netdata -s
+  ```
+
+- Run the `charts.d.plugin` to debug the collector:
+
+  ```bash
+  ./charts.d.plugin debug 1 libreswan
+  ```
+
+
diff --git a/collectors/charts.d.plugin/libreswan/metadata.yaml b/collectors/charts.d.plugin/libreswan/metadata.yaml
index 484d79ede..77cb25450 100644
--- a/collectors/charts.d.plugin/libreswan/metadata.yaml
+++ b/collectors/charts.d.plugin/libreswan/metadata.yaml
@@ -40,6 +40,9 @@ modules:
     setup:
       prerequisites:
         list:
+          - title: "Install charts.d plugin"
+            description: |
+              If [using our official native DEB/RPM packages](https://github.com/netdata/netdata/blob/master/packaging/installer/UPDATE.md#determine-which-installation-method-you-used), make sure `netdata-plugin-chartsd` is installed.
           - title: "Permissions to execute `ipsec`"
             description: |
               The plugin executes 2 commands to collect all the information it needs:
diff --git a/collectors/charts.d.plugin/nut/README.md b/collectors/charts.d.plugin/nut/README.md
index 4608ce3e1..abfefd6f7 100644..120000
--- a/collectors/charts.d.plugin/nut/README.md
+++ b/collectors/charts.d.plugin/nut/README.md
@@ -1,79 +1 @@
-<!--
-title: "UPS/PDU monitoring with Netdata"
-custom_edit_url: "https://github.com/netdata/netdata/edit/master/collectors/charts.d.plugin/nut/README.md"
-sidebar_label: "UPS/PDU"
-learn_status: "Published"
-learn_topic_type: "References"
-learn_rel_path: "Integrations/Monitor/Remotes/Devices"
--->
-
-# UPS/PDU collector
-
-Collects UPS data for all power devices configured in the system.
-
-The following charts will be created:
-
-1.  **UPS Charge**
-
--   percentage changed
-
-2.  **UPS Battery Voltage**
-
--   current voltage
--   high voltage
--   low voltage
--   nominal voltage
-
-3.  **UPS Input Voltage**
-
--   current voltage
--   fault voltage
--   nominal voltage
-
-4.  **UPS Input Current**
-
--   nominal current
-
-5.  **UPS Input Frequency**
-
--   current frequency
--   nominal frequency
-
-6.  **UPS Output Voltage**
-
--   current voltage
-
-7.  **UPS Load**
-
--   current load
-
-8.  **UPS Temperature**
-
--   current temperature
-
-## Configuration
-
-If using [our official native DEB/RPM packages](https://github.com/netdata/netdata/blob/master/packaging/installer/methods/packages.md), make sure `netdata-plugin-chartsd` is installed.
-
-Edit the `charts.d/nut.conf` configuration file using `edit-config` from the Netdata [config
-directory](https://github.com/netdata/netdata/blob/master/docs/configure/nodes.md), which is typically at `/etc/netdata`.
-
-```bash
-cd /etc/netdata   # Replace this path with your Netdata config directory, if different
-sudo ./edit-config charts.d/nut.conf
-```
-
-This is the internal default for `charts.d/nut.conf`
-
-```sh
-# a space separated list of UPS names
-# if empty, the list returned by 'upsc -l' will be used
-nut_ups=
-
-# how frequently to collect UPS data
-nut_update_every=2
-```
-
----
-
-
+integrations/network_ups_tools_nut.md
\ No newline at end of file
diff --git a/collectors/charts.d.plugin/nut/integrations/network_ups_tools_nut.md b/collectors/charts.d.plugin/nut/integrations/network_ups_tools_nut.md
new file mode 100644
index 000000000..74be607a1
--- /dev/null
+++ b/collectors/charts.d.plugin/nut/integrations/network_ups_tools_nut.md
@@ -0,0 +1,207 @@
+<!--startmeta
+custom_edit_url: "https://github.com/netdata/netdata/edit/master/collectors/charts.d.plugin/nut/README.md"
+meta_yaml: "https://github.com/netdata/netdata/edit/master/collectors/charts.d.plugin/nut/metadata.yaml"
+sidebar_label: "Network UPS Tools (NUT)"
+learn_status: "Published"
+learn_rel_path: "Data Collection/UPS"
+message: "DO NOT EDIT THIS FILE DIRECTLY, IT IS GENERATED BY THE COLLECTOR'S metadata.yaml FILE"
+endmeta-->
+
+# Network UPS Tools (NUT)
+
+
+<img src="https://netdata.cloud/img/plug-circle-bolt.svg" width="150"/>
+
+
+Plugin: charts.d.plugin
+Module: nut
+
+<img src="https://img.shields.io/badge/maintained%20by-Netdata-%2300ab44" />
+
+## Overview
+
+Examine UPS/PDU metrics with Netdata for insights into power device performance. Improve your power device performance with comprehensive dashboards and anomaly detection.
+
+This collector uses the `nut` (Network UPS Tools) to query statistics for multiple UPS devices.
+
+This collector is supported on all platforms.
+
+This collector supports collecting metrics from multiple instances of this integration, including remote instances.
+
+
+### Default Behavior
+
+#### Auto-Detection
+
+This integration doesn't support auto-detection.
+
+#### Limits
+
+The default configuration for this integration does not impose any limits on data collection.
+
+#### Performance Impact
+
+The default configuration for this integration is not expected to impose a significant performance impact on the system.
+
+
+## Metrics
+
+Metrics grouped by *scope*.
+
+The scope defines the instance that the metric belongs to. An instance is uniquely identified by a set of labels.
+
+
+
+### Per ups
+
+Metrics related to UPS. Each UPS provides its own set of the following metrics.
+
+This scope has no labels.
+
+Metrics:
+
+| Metric | Dimensions | Unit |
+|:------|:----------|:----|
+| nut.charge | charge | percentage |
+| nut.runtime | runtime | seconds |
+| nut.battery.voltage | voltage, high, low, nominal | Volts |
+| nut.input.voltage | voltage, fault, nominal | Volts |
+| nut.input.current | nominal | Ampere |
+| nut.input.frequency | frequency, nominal | Hz |
+| nut.output.voltage | voltage | Volts |
+| nut.load | load | percentage |
+| nut.load_usage | load_usage | Watts |
+| nut.temperature | temp | temperature |
+| nut.clients | clients | clients |
+
+
+
+## Alerts
+
+
+The following alerts are available:
+
+| Alert name  | On metric | Description |
+|:------------|:----------|:------------|
+| [ nut_ups_charge ](https://github.com/netdata/netdata/blob/master/health/health.d/nut.conf) | nut.charge | average UPS charge over the last minute |
+| [ nut_10min_ups_load ](https://github.com/netdata/netdata/blob/master/health/health.d/nut.conf) | nut.load | average UPS load over the last 10 minutes |
+| [ nut_last_collected_secs ](https://github.com/netdata/netdata/blob/master/health/health.d/nut.conf) | nut.load | number of seconds since the last successful data collection |
+
+
+## Setup
+
+### Prerequisites
+
+#### Install charts.d plugin
+
+If [using our official native DEB/RPM packages](https://github.com/netdata/netdata/blob/master/packaging/installer/UPDATE.md#determine-which-installation-method-you-used), make sure `netdata-plugin-chartsd` is installed.
+
+
+#### Required software
+
+Make sure the Network UPS Tools (`nut`) is installed and can detect your UPS devices.
+
+
+### Configuration
+
+#### File
+
+The configuration file name for this integration is `charts.d/nut.conf`.
+
+
+You can edit the configuration file using the `edit-config` script from the
+Netdata [config directory](https://github.com/netdata/netdata/blob/master/docs/configure/nodes.md#the-netdata-config-directory).
+
+```bash
+cd /etc/netdata 2>/dev/null || cd /opt/netdata/etc/netdata
+sudo ./edit-config charts.d/nut.conf
+```
+#### Options
+
+The config file is sourced by the charts.d plugin. It's a standard bash file.
+
+The following collapsed table contains all the options that can be configured for the nut collector.
+
+
+<details><summary>Config options</summary>
+
+| Name | Description | Default | Required |
+|:----|:-----------|:-------|:--------:|
+| nut_ups | A space separated list of UPS names. If empty, the list returned by `upsc -l` will be used. |  | False |
+| nut_names | Each line represents an alias for one UPS. If empty, the FQDN will be used. |  | False |
+| nut_timeout | How long to wait for nut to respond. | 2 | False |
+| nut_clients_chart | Set this to 1 to enable another chart showing the number of UPS clients connected to `upsd`. | 1 | False |
+| nut_update_every | The data collection frequency. If unset, will inherit the netdata update frequency. | 2 | False |
+| nut_priority | The charts priority on the dashboard | 90000 | False |
+| nut_retries | The number of retries to do in case of failure before disabling the collector. | 10 | False |
+
+</details>
+
+#### Examples
+
+##### Provide names to UPS devices
+
+Map aliases to UPS devices
+
+<details><summary>Config</summary>
+
+```yaml
+# a space separated list of UPS names
+# if empty, the list returned by 'upsc -l' will be used
+#nut_ups=
+
+# each line represents an alias for one UPS
+# if empty, the FQDN will be used
+nut_names["XXXXXX"]="UPS-office"
+nut_names["YYYYYY"]="UPS-rack"
+
+# how much time in seconds, to wait for nut to respond
+#nut_timeout=2
+
+# set this to 1, to enable another chart showing the number
+# of UPS clients connected to upsd
+#nut_clients_chart=1
+
+# the data collection frequency
+# if unset, will inherit the netdata update frequency
+#nut_update_every=2
+
+# the charts priority on the dashboard
+#nut_priority=90000
+
+# the number of retries to do in case of failure
+# before disabling the module
+#nut_retries=10
+
+```
+</details>
+
+
+
+## Troubleshooting
+
+### Debug Mode
+
+To troubleshoot issues with the `nut` collector, run the `charts.d.plugin` with the debug option enabled. The output
+should give you clues as to why the collector isn't working.
+
+- Navigate to the `plugins.d` directory, usually at `/usr/libexec/netdata/plugins.d/`. If that's not the case on
+  your system, open `netdata.conf` and look for the `plugins` setting under `[directories]`.
+
+  ```bash
+  cd /usr/libexec/netdata/plugins.d/
+  ```
+
+- Switch to the `netdata` user.
+
+  ```bash
+  sudo -u netdata -s
+  ```
+
+- Run the `charts.d.plugin` to debug the collector:
+
+  ```bash
+  ./charts.d.plugin debug 1 nut
+  ```
+
+
diff --git a/collectors/charts.d.plugin/nut/metadata.yaml b/collectors/charts.d.plugin/nut/metadata.yaml
index ea2e6b2eb..ed3ffebf7 100644
--- a/collectors/charts.d.plugin/nut/metadata.yaml
+++ b/collectors/charts.d.plugin/nut/metadata.yaml
@@ -40,6 +40,9 @@ modules:
     setup:
       prerequisites:
         list:
+          - title: "Install charts.d plugin"
+            description: |
+              If [using our official native DEB/RPM packages](https://github.com/netdata/netdata/blob/master/packaging/installer/UPDATE.md#determine-which-installation-method-you-used), make sure `netdata-plugin-chartsd` is installed.
           - title: "Required software"
             description: "Make sure the Network UPS Tools (`nut`) is installed and can detect your UPS devices."
       configuration:
diff --git a/collectors/charts.d.plugin/opensips/README.md b/collectors/charts.d.plugin/opensips/README.md
index 1d7322140..bb85ba6d0 100644..120000
--- a/collectors/charts.d.plugin/opensips/README.md
+++ b/collectors/charts.d.plugin/opensips/README.md
@@ -1,24 +1 @@
-<!--
-title: "OpenSIPS monitoring with Netdata"
-custom_edit_url: "https://github.com/netdata/netdata/edit/master/collectors/charts.d.plugin/opensips/README.md"
-sidebar_label: "OpenSIPS"
-learn_status: "Published"
-learn_topic_type: "References"
-learn_rel_path: "Integrations/Monitor/Networking"
--->
-
-# OpenSIPS collector
-
-## Configuration
-
-If using [our official native DEB/RPM packages](https://github.com/netdata/netdata/blob/master/packaging/installer/methods/packages.md), make sure `netdata-plugin-chartsd` is installed.
-
-Edit the `charts.d/opensips.conf` configuration file using `edit-config` from the Netdata [config
-directory](https://github.com/netdata/netdata/blob/master/docs/configure/nodes.md), which is typically at `/etc/netdata`.
-
-```bash
-cd /etc/netdata   # Replace this path with your Netdata config directory, if different
-sudo ./edit-config charts.d/opensips.conf
-```
-
-
+integrations/opensips.md
\ No newline at end of file
diff --git a/collectors/charts.d.plugin/opensips/integrations/opensips.md b/collectors/charts.d.plugin/opensips/integrations/opensips.md
new file mode 100644
index 000000000..96abc3325
--- /dev/null
+++ b/collectors/charts.d.plugin/opensips/integrations/opensips.md
@@ -0,0 +1,191 @@
+<!--startmeta
+custom_edit_url: "https://github.com/netdata/netdata/edit/master/collectors/charts.d.plugin/opensips/README.md"
+meta_yaml: "https://github.com/netdata/netdata/edit/master/collectors/charts.d.plugin/opensips/metadata.yaml"
+sidebar_label: "OpenSIPS"
+learn_status: "Published"
+learn_rel_path: "Data Collection/Telephony Servers"
+message: "DO NOT EDIT THIS FILE DIRECTLY, IT IS GENERATED BY THE COLLECTOR'S metadata.yaml FILE"
+endmeta-->
+
+# OpenSIPS
+
+
+<img src="https://netdata.cloud/img/opensips.png" width="150"/>
+
+
+Plugin: charts.d.plugin
+Module: opensips
+
+<img src="https://img.shields.io/badge/maintained%20by-Netdata-%2300ab44" />
+
+## Overview
+
+Examine OpenSIPS metrics for insights into SIP server operations. Study call rates, error rates, and response times for reliable voice over IP services.
+
+The collector uses the `opensipsctl` command line utility to gather OpenSIPS metrics.
+
+This collector is supported on all platforms.
+
+This collector supports collecting metrics from multiple instances of this integration, including remote instances.
+
+
+### Default Behavior
+
+#### Auto-Detection
+
+The collector will attempt to call `opensipsctl` along with a default number of parameters, even without any configuration.
+
+#### Limits
+
+The default configuration for this integration does not impose any limits on data collection.
+
+#### Performance Impact
+
+The default configuration for this integration is not expected to impose a significant performance impact on the system.
+
+
+## Metrics
+
+Metrics grouped by *scope*.
+
+The scope defines the instance that the metric belongs to. An instance is uniquely identified by a set of labels.
+
+
+
+### Per OpenSIPS instance
+
+These metrics refer to the entire monitored application.
+
+This scope has no labels.
+
+Metrics:
+
+| Metric | Dimensions | Unit |
+|:------|:----------|:----|
+| opensips.dialogs_active | active, early | dialogs |
+| opensips.users | registered, location, contacts, expires | users |
+| opensips.registrar | accepted, rejected | registrations/s |
+| opensips.transactions | UAS, UAC | transactions/s |
+| opensips.core_rcv | requests, replies | queries/s |
+| opensips.core_fwd | requests, replies | queries/s |
+| opensips.core_drop | requests, replies | queries/s |
+| opensips.core_err | requests, replies | queries/s |
+| opensips.core_bad | bad_URIs_rcvd, unsupported_methods, bad_msg_hdr | queries/s |
+| opensips.tm_replies | received, relayed, local | replies/s |
+| opensips.transactions_status | 2xx, 3xx, 4xx, 5xx, 6xx | transactions/s |
+| opensips.transactions_inuse | inuse | transactions |
+| opensips.sl_replies | 1xx, 2xx, 3xx, 4xx, 5xx, 6xx, sent, error, ACKed | replies/s |
+| opensips.dialogs | processed, expire, failed | dialogs/s |
+| opensips.net_waiting | UDP, TCP | kilobytes |
+| opensips.uri_checks | positive, negative | checks / sec |
+| opensips.traces | requests, replies | traces / sec |
+| opensips.shmem | total, used, real_used, max_used, free | kilobytes |
+| opensips.shmem_fragment | fragments | fragments |
+
+
+
+## Alerts
+
+There are no alerts configured by default for this integration.
+
+
+## Setup
+
+### Prerequisites
+
+#### Install charts.d plugin
+
+If [using our official native DEB/RPM packages](https://github.com/netdata/netdata/blob/master/packaging/installer/UPDATE.md#determine-which-installation-method-you-used), make sure `netdata-plugin-chartsd` is installed.
+
+
+#### Required software
+
+The collector requires the `opensipsctl` to be installed.
+
+
+### Configuration
+
+#### File
+
+The configuration file name for this integration is `charts.d/opensips.conf`.
+
+
+You can edit the configuration file using the `edit-config` script from the
+Netdata [config directory](https://github.com/netdata/netdata/blob/master/docs/configure/nodes.md#the-netdata-config-directory).
+
+```bash
+cd /etc/netdata 2>/dev/null || cd /opt/netdata/etc/netdata
+sudo ./edit-config charts.d/opensips.conf
+```
+#### Options
+
+The config file is sourced by the charts.d plugin. It's a standard bash file.
+
+The following collapsed table contains all the options that can be configured for the opensips collector.
+
+
+<details><summary>Config options</summary>
+
+| Name | Description | Default | Required |
+|:----|:-----------|:-------|:--------:|
+| opensips_opts | Specify parameters to the `opensipsctl` command. If the default value fails to get global status, set here whatever options are needed to connect to the opensips server. | fifo get_statistics all | False |
+| opensips_cmd | If `opensipsctl` is not in $PATH, specify it's full path here. |  | False |
+| opensips_timeout | How long to wait for `opensipsctl` to respond. | 2 | False |
+| opensips_update_every | The data collection frequency. If unset, will inherit the netdata update frequency. | 5 | False |
+| opensips_priority | The charts priority on the dashboard. | 80000 | False |
+| opensips_retries | The number of retries to do in case of failure before disabling the collector. | 10 | False |
+
+</details>
+
+#### Examples
+
+##### Custom `opensipsctl` command
+
+Set a custom path to the `opensipsctl` command
+
+```yaml
+#opensips_opts="fifo get_statistics all"
+opensips_cmd=/opt/opensips/bin/opensipsctl
+#opensips_timeout=2
+
+# the data collection frequency
+# if unset, will inherit the netdata update frequency
+#opensips_update_every=5
+
+# the charts priority on the dashboard
+#opensips_priority=80000
+
+# the number of retries to do in case of failure
+# before disabling the module
+#opensips_retries=10
+
+```
+
+
+## Troubleshooting
+
+### Debug Mode
+
+To troubleshoot issues with the `opensips` collector, run the `charts.d.plugin` with the debug option enabled. The output
+should give you clues as to why the collector isn't working.
+
+- Navigate to the `plugins.d` directory, usually at `/usr/libexec/netdata/plugins.d/`. If that's not the case on
+  your system, open `netdata.conf` and look for the `plugins` setting under `[directories]`.
+
+  ```bash
+  cd /usr/libexec/netdata/plugins.d/
+  ```
+
+- Switch to the `netdata` user.
+
+  ```bash
+  sudo -u netdata -s
+  ```
+
+- Run the `charts.d.plugin` to debug the collector:
+
+  ```bash
+  ./charts.d.plugin debug 1 opensips
+  ```
+
+
diff --git a/collectors/charts.d.plugin/opensips/metadata.yaml b/collectors/charts.d.plugin/opensips/metadata.yaml
index 27f663286..356de5615 100644
--- a/collectors/charts.d.plugin/opensips/metadata.yaml
+++ b/collectors/charts.d.plugin/opensips/metadata.yaml
@@ -41,6 +41,9 @@ modules:
     setup:
       prerequisites:
         list:
+          - title: "Install charts.d plugin"
+            description: |
+              If [using our official native DEB/RPM packages](https://github.com/netdata/netdata/blob/master/packaging/installer/UPDATE.md#determine-which-installation-method-you-used), make sure `netdata-plugin-chartsd` is installed.
           - title: "Required software"
             description: "The collector requires the `opensipsctl` to be installed."
       configuration:
diff --git a/collectors/charts.d.plugin/sensors/README.md b/collectors/charts.d.plugin/sensors/README.md
index 0dbe96225..7e5a416c4 100644..120000
--- a/collectors/charts.d.plugin/sensors/README.md
+++ b/collectors/charts.d.plugin/sensors/README.md
@@ -1,81 +1 @@
-# Linux machine sensors collector
-
-Use this collector when `lm-sensors` doesn't work on your device (e.g. for RPi temperatures).
-For all other cases use the [Python collector](https://github.com/netdata/netdata/blob/master/collectors/python.d.plugin/sensors), which supports multiple
-jobs, is more efficient and performs calculations on top of the kernel provided values.
-
-This plugin will provide charts for all configured system sensors, by reading sensors directly from the kernel.
-The values graphed are the raw hardware values of the sensors.
-
-The plugin will create Netdata charts for:
-
-1. **Temperature**
-2. **Voltage**
-3. **Current**
-4. **Power**
-5. **Fans Speed**
-6. **Energy**
-7. **Humidity**
-
-One chart for every sensor chip found and each of the above will be created.
-
-## Enable the collector
-
-If using [our official native DEB/RPM packages](https://github.com/netdata/netdata/blob/master/packaging/installer/methods/packages.md), make sure `netdata-plugin-chartsd` is installed.
-
-The `sensors` collector is disabled by default.
-
-To enable the collector, you need to edit the configuration file of `charts.d/sensors.conf`. You can do so by using the `edit config` script.
-
-> ### Info
->
-> To edit configuration files in a safe way, we provide the [`edit config` script](https://github.com/netdata/netdata/blob/master/docs/configure/nodes.md#use-edit-config-to-edit-configuration-files) located in your [Netdata config directory](https://github.com/netdata/netdata/blob/master/docs/configure/nodes.md#the-netdata-config-directory) (typically is `/etc/netdata`) that creates the proper file and opens it in an editor automatically.
-> It is recommended to use this way for configuring Netdata.
->
-> Please also note that after most configuration changes you will need to [restart the Agent](https://github.com/netdata/netdata/blob/master/docs/configure/start-stop-restart.md) for the changes to take effect.
-
-```bash
-cd /etc/netdata   # Replace this path with your Netdata config directory, if different
-sudo ./edit-config charts.d.conf
-```
-
-You need to uncomment the regarding `sensors`, and set the value to `force`.
-
-```shell
-# example=force
-sensors=force
-```
-
-## Configuration
-
-Edit the `charts.d/sensors.conf` configuration file using `edit-config`:
-
-```bash
-cd /etc/netdata   # Replace this path with your Netdata config directory, if different
-sudo ./edit-config charts.d/sensors.conf
-```
-
-This is the internal default for `charts.d/sensors.conf`
-
-```sh
-# the directory the kernel keeps sensor data
-sensors_sys_dir="${NETDATA_HOST_PREFIX}/sys/devices"
-
-# how deep in the tree to check for sensor data
-sensors_sys_depth=10
-
-# if set to 1, the script will overwrite internal
-# script functions with code generated ones
-# leave to 1, is faster
-sensors_source_update=1
-
-# how frequently to collect sensor data
-# the default is to collect it at every iteration of charts.d
-sensors_update_every=
-
-# array of sensors which are excluded
-# the default is to include all
-sensors_excluded=()
-```
-
----
+integrations/linux_sensors_sysfs.md
\ No newline at end of file
diff --git a/collectors/charts.d.plugin/sensors/integrations/linux_sensors_sysfs.md b/collectors/charts.d.plugin/sensors/integrations/linux_sensors_sysfs.md
new file mode 100644
index 000000000..e0ce74d06
--- /dev/null
+++ b/collectors/charts.d.plugin/sensors/integrations/linux_sensors_sysfs.md
@@ -0,0 +1,200 @@
+<!--startmeta
+custom_edit_url: "https://github.com/netdata/netdata/edit/master/collectors/charts.d.plugin/sensors/README.md"
+meta_yaml: "https://github.com/netdata/netdata/edit/master/collectors/charts.d.plugin/sensors/metadata.yaml"
+sidebar_label: "Linux Sensors (sysfs)"
+learn_status: "Published"
+learn_rel_path: "Data Collection/Hardware Devices and Sensors"
+message: "DO NOT EDIT THIS FILE DIRECTLY, IT IS GENERATED BY THE COLLECTOR'S metadata.yaml FILE"
+endmeta-->
+
+# Linux Sensors (sysfs)
+
+
+<img src="https://netdata.cloud/img/microchip.svg" width="150"/>
+
+
+Plugin: charts.d.plugin
+Module: sensors
+
+<img src="https://img.shields.io/badge/maintained%20by-Netdata-%2300ab44" />
+
+## Overview
+
+Use this collector when `lm-sensors` doesn't work on your device (e.g. for RPi temperatures).
+For all other cases use the [Python collector](https://github.com/netdata/netdata/blob/master/collectors/python.d.plugin/sensors), which supports multiple jobs, is more efficient and performs calculations on top of the kernel provided values."
+
+
+It will provide charts for all configured system sensors, by reading sensors directly from the kernel.
+The values graphed are the raw hardware values of the sensors.
+
+
+This collector is only supported on the following platforms:
+
+- Linux
+
+This collector supports collecting metrics from multiple instances of this integration, including remote instances.
+
+
+### Default Behavior
+
+#### Auto-Detection
+
+By default, the collector will try to read entries under `/sys/devices`
+
+#### Limits
+
+The default configuration for this integration does not impose any limits on data collection.
+
+#### Performance Impact
+
+The default configuration for this integration is not expected to impose a significant performance impact on the system.
+
+
+## Metrics
+
+Metrics grouped by *scope*.
+
+The scope defines the instance that the metric belongs to. An instance is uniquely identified by a set of labels.
+
+
+
+### Per sensor chip
+
+Metrics related to sensor chips. Each chip provides its own set of the following metrics.
+
+This scope has no labels.
+
+Metrics:
+
+| Metric | Dimensions | Unit |
+|:------|:----------|:----|
+| sensors.temp | {filename} | Celsius |
+| sensors.volt | {filename} | Volts |
+| sensors.curr | {filename} | Ampere |
+| sensors.power | {filename} | Watt |
+| sensors.fans | {filename} | Rotations / Minute |
+| sensors.energy | {filename} | Joule |
+| sensors.humidity | {filename} | Percent |
+
+
+
+## Alerts
+
+There are no alerts configured by default for this integration.
+
+
+## Setup
+
+### Prerequisites
+
+#### Install charts.d plugin
+
+If [using our official native DEB/RPM packages](https://github.com/netdata/netdata/blob/master/packaging/installer/UPDATE.md#determine-which-installation-method-you-used), make sure `netdata-plugin-chartsd` is installed.
+
+
+#### Enable the sensors collector
+
+The `sensors` collector is disabled by default. To enable it, use `edit-config` from the Netdata [config directory](https://github.com/netdata/netdata/blob/master/docs/configure/nodes.md), which is typically at `/etc/netdata`, to edit the `charts.d.conf` file.
+
+```bash
+cd /etc/netdata   # Replace this path with your Netdata config directory, if different
+sudo ./edit-config charts.d.conf
+```
+
+Change the value of the `sensors` setting to `force` and uncomment the line. Save the file and restart the Netdata Agent with `sudo systemctl restart netdata`, or the [appropriate method](https://github.com/netdata/netdata/blob/master/docs/configure/start-stop-restart.md) for your system.
+
+
+
+### Configuration
+
+#### File
+
+The configuration file name for this integration is `charts.d/sensors.conf`.
+
+
+You can edit the configuration file using the `edit-config` script from the
+Netdata [config directory](https://github.com/netdata/netdata/blob/master/docs/configure/nodes.md#the-netdata-config-directory).
+
+```bash
+cd /etc/netdata 2>/dev/null || cd /opt/netdata/etc/netdata
+sudo ./edit-config charts.d/sensors.conf
+```
+#### Options
+
+The config file is sourced by the charts.d plugin. It's a standard bash file.
+
+The following collapsed table contains all the options that can be configured for the sensors collector.
+
+
+<details><summary>Config options</summary>
+
+| Name | Description | Default | Required |
+|:----|:-----------|:-------|:--------:|
+| sensors_sys_dir | The directory the kernel exposes sensor data. | /sys/devices | False |
+| sensors_sys_depth | How deep in the tree to check for sensor data. | 10 | False |
+| sensors_source_update | If set to 1, the script will overwrite internal script functions with code generated ones. | 1 | False |
+| sensors_update_every | The data collection frequency. If unset, will inherit the netdata update frequency. | 1 | False |
+| sensors_priority | The charts priority on the dashboard. | 90000 | False |
+| sensors_retries | The number of retries to do in case of failure before disabling the collector. | 10 | False |
+
+</details>
+
+#### Examples
+
+##### Set sensors path depth
+
+Set a different sensors path depth
+
+```yaml
+# the directory the kernel keeps sensor data
+#sensors_sys_dir="/sys/devices"
+
+# how deep in the tree to check for sensor data
+sensors_sys_depth=5
+
+# if set to 1, the script will overwrite internal
+# script functions with code generated ones
+# leave to 1, is faster
+#sensors_source_update=1
+
+# the data collection frequency
+# if unset, will inherit the netdata update frequency
+#sensors_update_every=
+
+# the charts priority on the dashboard
+#sensors_priority=90000
+
+# the number of retries to do in case of failure
+# before disabling the module
+#sensors_retries=10
+
+```
+
+
+## Troubleshooting
+
+### Debug Mode
+
+To troubleshoot issues with the `sensors` collector, run the `charts.d.plugin` with the debug option enabled. The output
+should give you clues as to why the collector isn't working.
+
+- Navigate to the `plugins.d` directory, usually at `/usr/libexec/netdata/plugins.d/`. If that's not the case on
+  your system, open `netdata.conf` and look for the `plugins` setting under `[directories]`.
+
+  ```bash
+  cd /usr/libexec/netdata/plugins.d/
+  ```
+
+- Switch to the `netdata` user.
+
+  ```bash
+  sudo -u netdata -s
+  ```
+
+- Run the `charts.d.plugin` to debug the collector:
+
+  ```bash
+  ./charts.d.plugin debug 1 sensors
+  ```
+
+
diff --git a/collectors/charts.d.plugin/sensors/metadata.yaml b/collectors/charts.d.plugin/sensors/metadata.yaml
index 33beaad29..47f6f4042 100644
--- a/collectors/charts.d.plugin/sensors/metadata.yaml
+++ b/collectors/charts.d.plugin/sensors/metadata.yaml
@@ -44,7 +44,20 @@ modules:
           description: ""
     setup:
       prerequisites:
-        list: []
+        list:
+          - title: "Install charts.d plugin"
+            description: |
+              If [using our official native DEB/RPM packages](https://github.com/netdata/netdata/blob/master/packaging/installer/UPDATE.md#determine-which-installation-method-you-used), make sure `netdata-plugin-chartsd` is installed.
+          - title: "Enable the sensors collector"
+            description: |
+              The `sensors` collector is disabled by default. To enable it, use `edit-config` from the Netdata [config directory](https://github.com/netdata/netdata/blob/master/docs/configure/nodes.md), which is typically at `/etc/netdata`, to edit the `charts.d.conf` file.
+
+              ```bash
+              cd /etc/netdata   # Replace this path with your Netdata config directory, if different
+              sudo ./edit-config charts.d.conf
+              ```
+
+              Change the value of the `sensors` setting to `force` and uncomment the line. Save the file and restart the Netdata Agent with `sudo systemctl restart netdata`, or the [appropriate method](https://github.com/netdata/netdata/blob/master/docs/configure/start-stop-restart.md) for your system.
       configuration:
         file:
           name: charts.d/sensors.conf