| 1 | # OS provided metrics (debugfs.plugin) |
| 2 | |
| 3 | `debugfs.plugin` gathers metrics from the `/sys/kernel/debug` folder on Linux |
| 4 | systems. [Debugfs](https://docs.kernel.org/filesystems/debugfs.html) exists as an easy way for kernel developers to |
| 5 | make information available to user space. |
| 6 | |
| 7 | This plugin |
| 8 | is [external](https://github.com/netdata/netdata/tree/master/src/collectors#collector-architecture-and-terminology), |
| 9 | the netdata daemon spawns it as a long-running independent process. |
| 10 | |
| 11 | In detail, it collects metrics from: |
| 12 | |
| 13 | - `/sys/kernel/debug/extfrag` (Memory fragmentation index for each order and zone). |
| 14 | - `/sys/kernel/debug/zswap` ([Zswap](https://www.kernel.org/doc/Documentation/vm/zswap.txt) performance statistics). |
| 15 | |
| 16 | ## Prerequisites |
| 17 | |
| 18 | ### Permissions |
| 19 | |
| 20 | > No user action required. |
| 21 | |
| 22 | The debugfs root directory is accessible only to the root user by default. Netdata |
| 23 | uses [Linux Capabilities](https://man7.org/linux/man-pages/man7/capabilities.7.html) to give the plugin access |
| 24 | to debugfs. `CAP_DAC_READ_SEARCH` is added automatically during installation. This capability allows bypassing file read |
| 25 | 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. |
| 26 | |
| 27 | ## Metrics |
| 28 | |
| 29 | | Metric | Scope | Dimensions | Units | Labels | |
| 30 | |-------------------------------------|:---------:|:---------------------------------------------------------------------------------------:|:------------:|:---------:| |
| 31 | | mem.fragmentation_index_dma | numa node | order0, order1, order2, order3, order4, order5, order6, order7, order8, order9, order10 | index | numa_node | |
| 32 | | mem.fragmentation_index_dma32 | numa node | order0, order1, order2, order3, order4, order5, order6, order7, order8, order9, order10 | index | numa_node | |
| 33 | | mem.fragmentation_index_normal | numa node | order0, order1, order2, order3, order4, order5, order6, order7, order8, order9, order10 | index | numa_node | |
| 34 | | system.zswap_pool_compression_ratio | | compression_ratio | ratio | | |
| 35 | | system.zswap_pool_compressed_size | | compressed_size | bytes | | |
| 36 | | system.zswap_pool_raw_size | | uncompressed_size | bytes | | |
| 37 | | system.zswap_rejections | | compress_poor, kmemcache_fail, alloc_fail, reclaim_fail | rejections/s | | |
| 38 | | system.zswap_pool_limit_hit | | limit | events/s | | |
| 39 | | system.zswap_written_back_raw_bytes | | written_back | bytes/s | | |
| 40 | | system.zswap_same_filled_raw_size | | same_filled | bytes | | |
| 41 | | system.zswap_duplicate_entry | | entries | entries/s | | |
| 42 | |
| 43 | ## Troubleshooting |
| 44 | |
| 45 | To troubleshoot issues with the collector, run the `debugfs.plugin` in the terminal. The output |
| 46 | should give you clues as to why the collector isn't working. |
| 47 | |
| 48 | - Navigate to the `plugins.d` directory, usually at `/usr/libexec/netdata/plugins.d/`. If that's not the case on |
| 49 | your system, open `netdata.conf` and look for the `plugins` setting under `[directories]`. |
| 50 | |
| 51 | ```bash |
| 52 | cd /usr/libexec/netdata/plugins.d/ |
| 53 | ``` |
| 54 | |
| 55 | - Switch to the `netdata` user. |
| 56 | |
| 57 | ```bash |
| 58 | sudo -u netdata -s |
| 59 | ``` |
| 60 | |
| 61 | - Run the `debugfs.plugin` to debug the collector: |
| 62 | |
| 63 | ```bash |
| 64 | ./debugfs.plugin |
| 65 | ``` |