From 1a0c79b57cc529aeb9ba7207582bccbfdfbc2978 Mon Sep 17 00:00:00 2001
From: Philip Allgaier <philip.allgaier@gmx.de>
Date: Sat, 5 Sep 2020 16:43:10 +0200
Subject: [PATCH] Clarification reg. disk sensors of systemmonitor (#14400)

* Clarification reg. disk sensors of systemmonitor

* Added "mandatory" column for arguments

* Apply suggestions from code review

Co-authored-by: Franck Nijhof <git@frenck.dev>

* Adjusted mandatory column

Co-authored-by: Franck Nijhof <git@frenck.dev>
---
 source/_integrations/systemmonitor.markdown | 65 ++++++++++++---------
 1 file changed, 39 insertions(+), 26 deletions(-)

diff --git a/source/_integrations/systemmonitor.markdown b/source/_integrations/systemmonitor.markdown
index a65dd885567..a8add075c15 100644
--- a/source/_integrations/systemmonitor.markdown
+++ b/source/_integrations/systemmonitor.markdown
@@ -42,37 +42,50 @@ resources:
 The table contains types and their argument to use in your `configuration.yaml`
 file.
 
-| Type (`type:`)         | Argument (`arg:`)         |
-| :--------------------- |:--------------------------|
-| disk_use_percent       | Path, e.g., `/`           |
-| disk_use               | Path, e.g., `/`           |
-| disk_free              | Path, e.g., `/`           |
-| memory_use_percent     |                           |
-| memory_use             |                           |
-| memory_free            |                           |
-| swap_use_percent       |                           |
-| swap_use               |                           |
-| swap_free              |                           |
-| load_1m                |                           |
-| load_5m                |                           |
-| load_15m               |                           |
-| network_in             | Interface, e.g., `eth0`   |
-| network_out            | Interface, e.g., `eth0`   |
-| throughput_network_in  | Interface, e.g., `eth0`   |
-| throughput_network_out | Interface, e.g., `eth0`   |
-| packets_in             | Interface, e.g., `eth0`   |
-| packets_out            | Interface, e.g., `eth0`   |
-| ipv4_address           | Interface, e.g., `eth0`   |
-| ipv6_address           | Interface, e.g., `eth0`   |
-| processor_use          |                           |
-| processor_temperature  |                           |
-| process                | Binary, e.g., `octave-cli` |
-| last_boot              |                           |
+| Type (`type:`)         | Argument (`arg:`)         | Argument mandatory        |
+| :--------------------- |:--------------------------|:--------------------------|
+| disk_use_percent       | Path, e.g., `/`           | no                        |
+| disk_use               | Path, e.g., `/`           | no                        |
+| disk_free              | Path, e.g., `/`           | no                        |
+| memory_use_percent     |                           |                           |
+| memory_use             |                           |                           |
+| memory_free            |                           |                           |
+| swap_use_percent       |                           |                           |
+| swap_use               |                           |                           |
+| swap_free              |                           |                           |
+| load_1m                |                           |                           |
+| load_5m                |                           |                           |
+| load_15m               |                           |                           |
+| network_in             | Interface, e.g., `eth0`   | yes                       |
+| network_out            | Interface, e.g., `eth0`   | yes                       |
+| throughput_network_in  | Interface, e.g., `eth0`   | yes                       |
+| throughput_network_out | Interface, e.g., `eth0`   | yes                       |
+| packets_in             | Interface, e.g., `eth0`   | yes                       |
+| packets_out            | Interface, e.g., `eth0`   | yes                       |
+| ipv4_address           | Interface, e.g., `eth0`   | yes                       |
+| ipv6_address           | Interface, e.g., `eth0`   | yes                       |
+| processor_use          |                           |                           |
+| processor_temperature  |                           |                           |
+| process                | Binary, e.g., `octave-cli` | yes                       |
+| last_boot              |                           |                           |
 
 ## Disk usage
 
 If no path is provided via the optional argument, the integration defaults to '/' (root).
 
+**Note:** The disk usage sensors do not support monitoring folder/directory sizes. Instead, it is only concerned with "disks" (more specifically mount points on Linux).
+
+```bash
+$ df -H
+Filesystem      Size  Used Avail Use% Mounted on
+/dev/root        29G   12G   16G  42% /
+devtmpfs        805M     0  805M   0% /dev
+tmpfs           934M     0  934M   0% /dev/shm
+/dev/mmcblk0p1  253M   54M  199M  22% /boot
+```
+
+Defining a `disk_use` sensor for `/` and `/home/pi` is redundant and will return the same values, since they both belong to the same "disk". However, defining separate sensors for `/dev` and `dev/shm` is possible and provides different values, since those are treated as separate "disks" by the integration.
+
 ## Processor temperature
 
 - If no hardware sensor data is available (e.g., because the integration runs in a virtualized environment), the sensor entity will not be created.