c1b51033a · cryptotaxi247/netdata-1

@@ -1,42 +1,39 @@

1 # ebpf_process.plugin

2

3 -This plugin uses eBPF to monitor system calls inside your operating system's kernel. For now, the main goal of this

4 -plugin is to monitor IO and process management on the host where it is running.

3 +This collector plugin uses eBPF to monitor system calls inside your operating system's kernel. For now, the main goal of

4 +this plugin is to monitor IO and process management on the host where it is running.

5

6 -This plugin has different configuration modes, all of which can be adjusted with its configuration file at

7 -`ebpf_process.conf`. By default, the plugin uses the less expensive `entry` mode. You can learn more about how the

8 -plugin works using `entry` by reading this configuration file.

6 +<figure>

7 + <img src="https://user-images.githubusercontent.com/1153921/74746434-ad6a1e00-5222-11ea-858a-a7882617ae02.png" alt="n example of VFS charts, made possible by the eBPF collector plugin">

8 + <figcaption>An example of VFS charts, made possible by the eBPF collector plugin</figcaption>

9 +</figure>

10

10 -You can always edit this file with `edit-config`:

11 +## Enable the collector on Linux

12

12 -```bash

13 -cd /etc/netdata/ # Replace with your Netdata configuration directory, if not /etc/netdata/

14 -./edit-config ebpf_process.conf

15 -```

13 +Currently, this `ebpf_process` collector only works on Linux systems. Because it adds overhead to the system running it,

14 +the collector is also disabled by default.

15

17 -## Enable the plugin on Linux

16 +Follow the next few steps to ensure compatibility, prepare your system, install Netdata with eBPF compiled, and enable

17 +the collector.

18

19 -Currently, `ebpf_process` only works on Linux systems.

19 +### Ensure kernel compatibility

20

21 -To enable this plugin and its collector, your operating system's kernel must be more recent than `4.11.0`, and it must

22 -be compiled with the option `CONFIG_KPROBES=y`. You can verify whether your kernel has this option enabled by running

21 +To enable this plugin and its collector, you must be on a Linux system with a kernel that is more recent than `4.11.0`

22 +and compiled with the option `CONFIG_KPROBES=y`. You can verify whether your kernel has this option enabled by running

23 the following commands:

24

25 ```bash

26 -# grep CONFIG_KPROBES=y /boot/config-$(uname -r)

27 -# zgrep CONFIG_KPROBES=y /proc/config.gz

26 +grep CONFIG_KPROBES=y /boot/config-$(uname -r)

27 +zgrep CONFIG_KPROBES=y /proc/config.gz

28 ```

29

30 -If `Kprobes` is enabled, you will see `CONFIG_KPROBES=y` as the command's output. If you don't see `CONFIG_KPROBES=y`

31 -for any of the commands above, you will have to recompile your kernel to enable it. See the next step, [Recompiling your

32 -kernel](#recompile-your-kernel), for details.

33 -

34 -You also need to have both the `tracefs` and `debugfs` filesystems mounted on your system.

30 +If `Kprobes` is enabled, you will see `CONFIG_KPROBES=y` as the command's output, and can skip ahead to the next step: [mount `debugfs` and `tracefs`](#mount-debugfs-and-tracefs).

31

36 -### Recompile your kernel

32 +If you don't see `CONFIG_KPROBES=y` for any of the commands above, you will have to recompile your kernel to enable it.

33

34 The process of recompiling Linux kernels varies based on your distribution and version. Read the documentation for your

39 -system's distribution to learn more about the specific workflow for

35 +system's distribution to learn more about the specific workflow for recompiling the kernel, ensuring that you set the

36 +`CONFIG_KPROBES` setting to `y` in the process.

37

38 - [Ubuntu](https://wiki.ubuntu.com/Kernel/BuildYourOwnKernel)

39 - [Debian](https://kernel-team.pages.debian.net/kernel-handbook/ch-common-tasks.html#s-common-official)

@@ -47,26 +44,53 @@ system's distribution to learn more about the specific workflow for

44

45 ### Mount `debugfs` and `tracefs`

46

50 -Try mounting the `tracefs` and `debugfs` filesystems using the commands below:

47 +The eBPF collector also requires both the `tracefs` and `debugfs` filesystems. Try mounting the `tracefs` and `debugfs`

48 +filesystems using the commands below:

49

50 ```bash

53 -# mount -t debugfs nodev /sys/kernel/debug

54 -# mount -t tracefs nodev /sys/kernel/tracing

51 +sudo mount -t debugfs nodev /sys/kernel/debug

52 +sudo mount -t tracefs nodev /sys/kernel/tracing

53 ```

54

57 -If they are already mounted, you will see an error. You can also configure your system's `/etc/fstab` configuration to

58 -mount these filesystems.

55 +If they are already mounted, you will see an error. If they are not mounted, they should be after running those two

56 +commands. You can also configure your system's `/etc/fstab` configuration to mount these filesystems.

57 +

58 +### Install Netdata with the `--enable-ebpf`

59 +

60 +eBPF collection is only enabled if you install Netdata with the `--enable-ebpf` option.

61 +

62 +If you installed via the [one-line installation script](../../packaging/installer/README.md), [64-bit

63 +binary](../../packaging/installer/methods/kickstart-64.md), or [manually](../../packaging/installer/methods/manual.md),

64 +you can append the `--enable-ebpf` option when you reinstall.

65 +

66 +For example, if you used the one-line installation script, you can reinstall Netdata with the following:

67 +

68 +```bash

69 +bash <(curl -Ss https://my-netdata.io/kickstart.sh) --enable-ebpf

70 +```

71 +

72 +This process will not overwrite any changes you made to configuration files.

73

60 -## Enable the eBPF plugin

61 -The plugin is disabled by default because it adds overhead to the system running the Netdata agent.

74 +### Edit `netdata.conf` to enable the collector

75

63 -To enable it, use `edit-config` to open `netdata.conf` and set `ebpf_process = yes` in the `[plugins]` section.

76 +After installing Netdata with the `--enable-ebpf` option, you still need to enable the plugin explicitly. To do so, use

77 +`edit-config` to open `netdata.conf` and set `ebpf_process = yes` in the `[plugins]` section.

78 +

79 +```bash

80 +cd /etc/netdata/ # Replace with your Netdata configuration directory, if not /etc/netdata/

81 +./edit-config netdata.conf

82 +```

83 +

84 +Scroll down to the `[plugins]` section and uncomment the `ebpf_process` line after changing its setting to `yes`.

85

86 ```conf

87 [plugins]

88 ebpf_process = yes

89 ```

90

91 +Restart Netdata with `service netdata restart`, or the appropriate method for your system, and reload your browser to

92 +see eBPF charts.

93 +

94 ## Charts

95

96 The first version of `ebpf_process.plugin` gives a general vision about process running on computer. The charts related

@@ -83,7 +107,7 @@ descriptors.

107

108 #### File descriptor

109

86 -This chart contain two dimensions that show the number of calls to the functions `do_sys_open` and `__close_fd`. These

110 +This chart contains two dimensions that show the number of calls to the functions `do_sys_open` and `__close_fd`. These

111 functions are not commonly called from software, but they are behind the system cals `open(2)`, `openat(2)`, and

112 `close(2)`.

113

@@ -93,7 +117,7 @@ This charts demonstrate the number of times some software tried and failed to op

117

118 ### VFS

119

96 -A [virtual file system](https://en.wikipedia.org/wiki/Virtual_file_system) (VFS) is an layer on top of regular

120 +A [virtual file system](https://en.wikipedia.org/wiki/Virtual_file_system) (VFS) is a layer on top of regular

121 filesystems. The functions present inside this API are used for all filesystems, so it's possible the charts in this

122 group won't show _all_ the actions that occured on your system.

123

@@ -142,8 +166,16 @@ process and thread creation.

166

167 ## Configuration

168

145 -The collector configuration file follows the same structure as `netdata.conf`. It is divided in different sections, with

146 -each one of them having the internal variables.

169 +This plugin has different configuration modes, all of which can be adjusted with its configuration file at

170 +`ebpf_process.conf`. By default, the plugin uses the less expensive `entry` mode. You can learn more about how the

171 +plugin works using `entry` by reading this configuration file.

172 +

173 +You can always edit this file with `edit-config`:

174 +

175 +```bash

176 +cd /etc/netdata/ # Replace with your Netdata configuration directory, if not /etc/netdata/

177 +./edit-config ebpf_process.conf

178 +```

179

180 ### `[global]`

181

Update eBPF docs with better install/enable instructions (#8125)