10 files changed, 81 insertions, 16 deletions
diff --git a/src/collectors/debugfs.plugin/README.md b/src/collectors/debugfs.plugin/README.md
new file mode 100644
index 000000000..514c8bb61
--- /dev/null
+++ b/src/collectors/debugfs.plugin/README.md
@@ -0,0 +1,65 @@
+# OS provided metrics (debugfs.plugin)
+
+`debugfs.plugin` gathers metrics from the `/sys/kernel/debug` folder on Linux
+systems. [Debugfs](https://docs.kernel.org/filesystems/debugfs.html) exists as an easy way for kernel developers to
+make information available to user space.
+
+This plugin
+is [external](https://github.com/netdata/netdata/tree/master/src/collectors#collector-architecture-and-terminology),
+the netdata daemon spawns it as a long-running independent process.
+
+In detail, it collects metrics from:
+
+- `/sys/kernel/debug/extfrag` (Memory fragmentation index for each order and zone).
+- `/sys/kernel/debug/zswap` ([Zswap](https://www.kernel.org/doc/Documentation/vm/zswap.txt) performance statistics).
+
+## Prerequisites
+
+### Permissions
+
+> No user action required.
+
+The debugfs root directory is accessible only to the root user by default. Netdata
+uses [Linux Capabilities](https://man7.org/linux/man-pages/man7/capabilities.7.html) to give the plugin access
+to debugfs. `CAP_DAC_READ_SEARCH` is added automatically during installation. This capability allows bypassing file read
+permission checks and directory read and execute permission checks. If file capabilities are not usable, then the plugin is instead installed with the SUID bit set in permissions so that it runs as root.
+
+## Metrics
+
+| Metric                              |   Scope   |                                       Dimensions                                        |    Units     |  Labels   |
+|-------------------------------------|:---------:|:---------------------------------------------------------------------------------------:|:------------:|:---------:|
+| mem.fragmentation_index_dma         | numa node | order0, order1, order2, order3, order4, order5, order6, order7, order8, order9, order10 |    index     | numa_node |
+| mem.fragmentation_index_dma32       | numa node | order0, order1, order2, order3, order4, order5, order6, order7, order8, order9, order10 |    index     | numa_node |
+| mem.fragmentation_index_normal      | numa node | order0, order1, order2, order3, order4, order5, order6, order7, order8, order9, order10 |    index     | numa_node |
+| system.zswap_pool_compression_ratio |           |                                    compression_ratio                                    |    ratio     |           |
+| system.zswap_pool_compressed_size   |           |                                     compressed_size                                     |    bytes     |           |
+| system.zswap_pool_raw_size          |           |                                    uncompressed_size                                    |    bytes     |           |
+| system.zswap_rejections             |           |                 compress_poor, kmemcache_fail, alloc_fail, reclaim_fail                 | rejections/s |           |
+| system.zswap_pool_limit_hit         |           |                                          limit                                          |   events/s   |           |
+| system.zswap_written_back_raw_bytes |           |                                      written_back                                       |   bytes/s    |           |
+| system.zswap_same_filled_raw_size   |           |                                       same_filled                                       |    bytes     |           |
+| system.zswap_duplicate_entry        |           |                                         entries                                         |  entries/s   |           |
+
+## Troubleshooting
+
+To troubleshoot issues with the collector, run the `debugfs.plugin` in the terminal. 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 `debugfs.plugin` to debug the collector:
+
+  ```bash
+  ./debugfs.plugin
+  ```
diff --git a/collectors/debugfs.plugin/debugfs_extfrag.c b/src/collectors/debugfs.plugin/debugfs_extfrag.c
index 75da4deca..75da4deca 100644
--- a/collectors/debugfs.plugin/debugfs_extfrag.c
+++ b/src/collectors/debugfs.plugin/debugfs_extfrag.c
diff --git a/collectors/debugfs.plugin/debugfs_plugin.c b/src/collectors/debugfs.plugin/debugfs_plugin.c
index 13012ec40..94e3db631 100644
--- a/collectors/debugfs.plugin/debugfs_plugin.c
+++ b/src/collectors/debugfs.plugin/debugfs_plugin.c
@@ -28,7 +28,7 @@ static struct debugfs_module {
     { .name = NULL, .enabled = CONFIG_BOOLEAN_NO, .func = NULL}
 };
 
-#ifdef HAVE_CAPABILITY
+#ifdef HAVE_SYS_CAPABILITY_H
 static int debugfs_check_capabilities()
 {
     cap_t caps = cap_get_proc();
@@ -182,7 +182,7 @@ int main(int argc, char **argv)
     // FIXME: remove debugfs_check_sys_permission() after https://github.com/netdata/netdata/issues/15048 is fixed
     if (!debugfs_check_capabilities() && !debugfs_am_i_running_as_root() && !debugfs_check_sys_permission()) {
         uid_t uid = getuid(), euid = geteuid();
-#ifdef HAVE_CAPABILITY
+#ifdef HAVE_SYS_CAPABILITY_H
         netdata_log_error(
             "debugfs.plugin should either run as root (now running with uid %u, euid %u) or have special capabilities. "
             "Without these, debugfs.plugin cannot access /sys/kernel/debug. "
diff --git a/collectors/debugfs.plugin/debugfs_plugin.h b/src/collectors/debugfs.plugin/debugfs_plugin.h
index 903e4a19e..903e4a19e 100644
--- a/collectors/debugfs.plugin/debugfs_plugin.h
+++ b/src/collectors/debugfs.plugin/debugfs_plugin.h
diff --git a/collectors/debugfs.plugin/debugfs_zswap.c b/src/collectors/debugfs.plugin/debugfs_zswap.c
index 502a04f1f..e4d956cda 100644
--- a/collectors/debugfs.plugin/debugfs_zswap.c
+++ b/src/collectors/debugfs.plugin/debugfs_zswap.c
@@ -370,7 +370,7 @@ static int debugfs_is_zswap_enabled()
     snprintfz(filename, FILENAME_MAX, "/sys/module/zswap/parameters/enabled"); // host prefix is not needed here
     char state[ZSWAP_STATE_SIZE + 1];
 
-    int ret = read_file(filename, state, ZSWAP_STATE_SIZE);
+    int ret = read_txt_file(filename, state, sizeof(state));
 
     if (unlikely(!ret && !strcmp(state, "Y"))) {
         return 0;
diff --git a/collectors/debugfs.plugin/integrations/linux_zswap.md b/src/collectors/debugfs.plugin/integrations/linux_zswap.md
index 44478454b..20de4c78d 100644
--- a/collectors/debugfs.plugin/integrations/linux_zswap.md
+++ b/src/collectors/debugfs.plugin/integrations/linux_zswap.md
@@ -1,9 +1,9 @@
 <!--startmeta
-custom_edit_url: "https://github.com/netdata/netdata/edit/master/collectors/debugfs.plugin/integrations/linux_zswap.md"
-meta_yaml: "https://github.com/netdata/netdata/edit/master/collectors/debugfs.plugin/metadata.yaml"
+custom_edit_url: "https://github.com/netdata/netdata/edit/master/src/collectors/debugfs.plugin/integrations/linux_zswap.md"
+meta_yaml: "https://github.com/netdata/netdata/edit/master/src/collectors/debugfs.plugin/metadata.yaml"
 sidebar_label: "Linux ZSwap"
 learn_status: "Published"
-learn_rel_path: "Data Collection/Linux Systems/Memory"
+learn_rel_path: "Collecting Metrics/Linux Systems/Memory"
 most_popular: False
 message: "DO NOT EDIT THIS FILE DIRECTLY, IT IS GENERATED BY THE COLLECTOR'S metadata.yaml FILE"
 endmeta-->
@@ -113,7 +113,7 @@ The file format is a modified INI syntax. The general structure is:
     option3 = some third value
 ```
 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).
+Netdata [config directory](https://github.com/netdata/netdata/blob/master/docs/netdata-agent/configuration.md#the-netdata-config-directory).
 
 ```bash
 cd /etc/netdata 2>/dev/null || cd /opt/netdata/etc/netdata
diff --git a/collectors/debugfs.plugin/integrations/power_capping.md b/src/collectors/debugfs.plugin/integrations/power_capping.md
index d4b7eb890..de68ff542 100644
--- a/collectors/debugfs.plugin/integrations/power_capping.md
+++ b/src/collectors/debugfs.plugin/integrations/power_capping.md
@@ -1,9 +1,9 @@
 <!--startmeta
-custom_edit_url: "https://github.com/netdata/netdata/edit/master/collectors/debugfs.plugin/integrations/power_capping.md"
-meta_yaml: "https://github.com/netdata/netdata/edit/master/collectors/debugfs.plugin/metadata.yaml"
+custom_edit_url: "https://github.com/netdata/netdata/edit/master/src/collectors/debugfs.plugin/integrations/power_capping.md"
+meta_yaml: "https://github.com/netdata/netdata/edit/master/src/collectors/debugfs.plugin/metadata.yaml"
 sidebar_label: "Power Capping"
 learn_status: "Published"
-learn_rel_path: "Data Collection/Linux Systems/Kernel"
+learn_rel_path: "Collecting Metrics/Linux Systems/Kernel"
 most_popular: False
 message: "DO NOT EDIT THIS FILE DIRECTLY, IT IS GENERATED BY THE COLLECTOR'S metadata.yaml FILE"
 endmeta-->
@@ -107,7 +107,7 @@ The file format is a modified INI syntax. The general structure is:
     option3 = some third value
 ```
 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).
+Netdata [config directory](https://github.com/netdata/netdata/blob/master/docs/netdata-agent/configuration.md#the-netdata-config-directory).
 
 ```bash
 cd /etc/netdata 2>/dev/null || cd /opt/netdata/etc/netdata
diff --git a/collectors/debugfs.plugin/integrations/system_memory_fragmentation.md b/src/collectors/debugfs.plugin/integrations/system_memory_fragmentation.md
index ef287bc30..8c5f7317a 100644
--- a/collectors/debugfs.plugin/integrations/system_memory_fragmentation.md
+++ b/src/collectors/debugfs.plugin/integrations/system_memory_fragmentation.md
@@ -1,9 +1,9 @@
 <!--startmeta
-custom_edit_url: "https://github.com/netdata/netdata/edit/master/collectors/debugfs.plugin/integrations/system_memory_fragmentation.md"
-meta_yaml: "https://github.com/netdata/netdata/edit/master/collectors/debugfs.plugin/metadata.yaml"
+custom_edit_url: "https://github.com/netdata/netdata/edit/master/src/collectors/debugfs.plugin/integrations/system_memory_fragmentation.md"
+meta_yaml: "https://github.com/netdata/netdata/edit/master/src/collectors/debugfs.plugin/metadata.yaml"
 sidebar_label: "System Memory Fragmentation"
 learn_status: "Published"
-learn_rel_path: "Data Collection/Linux Systems/Memory"
+learn_rel_path: "Collecting Metrics/Linux Systems/Memory"
 most_popular: False
 message: "DO NOT EDIT THIS FILE DIRECTLY, IT IS GENERATED BY THE COLLECTOR'S metadata.yaml FILE"
 endmeta-->
@@ -111,7 +111,7 @@ The file format is a modified INI syntax. The general structure is:
     option3 = some third value
 ```
 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).
+Netdata [config directory](https://github.com/netdata/netdata/blob/master/docs/netdata-agent/configuration.md#the-netdata-config-directory).
 
 ```bash
 cd /etc/netdata 2>/dev/null || cd /opt/netdata/etc/netdata
diff --git a/collectors/debugfs.plugin/metadata.yaml b/src/collectors/debugfs.plugin/metadata.yaml
index d3bf0a0d8..d3bf0a0d8 100644
--- a/collectors/debugfs.plugin/metadata.yaml
+++ b/src/collectors/debugfs.plugin/metadata.yaml
diff --git a/collectors/debugfs.plugin/sys_devices_virtual_powercap.c b/src/collectors/debugfs.plugin/sys_devices_virtual_powercap.c
index ee261c27f..a5dfb7550 100644
--- a/collectors/debugfs.plugin/sys_devices_virtual_powercap.c
+++ b/src/collectors/debugfs.plugin/sys_devices_virtual_powercap.c
@@ -27,7 +27,7 @@ static struct zone_t *get_rapl_zone(const char *control_type __maybe_unused, str
     snprintfz(temp, FILENAME_MAX, "%s/%s", dirname, "name");
 
     char name[FILENAME_MAX + 1] = "";
-    if (read_file(temp, name, sizeof(name) - 1) != 0)
+    if (read_txt_file(temp, name, sizeof(name)) != 0)
         return NULL;
 
     char *trimmed = trim(name);