Update apps.plugin documentation and dashboard.info (#9199)
Documentation for new eBPF charts.
thiagoftsm committed
Jun 5, 2020 at 04:28 UTC
5776deefc2ab4a9c0c47c9ccb78d75d50187f3ab
3 files changed
+103
-11
collectors/apps.plugin/README.md
+8
-1
@@ -64,7 +64,10 @@ Each of these sections provides the same number of charts:
64
- Major Page Faults (i.e. swap activity)
65
- Network
66
- Sockets Open
67
-
67
+
68
+In addition, if the [eBPF collector](/collectors/ebpf.plugin/README.md) is running, your dashboard will also show
69
+an additional [list](/collectors/ebpf.plugin/README.md#integration-with-appsplugin) of charts using low-level Linux metrics.
70
+
71
The above are reported:
72
73
- For **Applications** per target configured.
@@ -155,6 +158,10 @@ There are a few command line options you can pass to `apps.plugin`. The list of
158
command options = without-users without-groups
159
```
160
161
+### Integration with eBPF
162
+
163
+If you don't see charts under the **eBPF syscall** or **eBPF net** sections, you should edit your [`ebpf.conf`](/collectors/ebpf.plugin/README.md#ebpf-programs) file to ensure the eBPF program is enabled.
164
+
165
## Permissions
166
167
`apps.plugin` requires additional privileges to collect all the information it needs.
collectors/ebpf.plugin/README.md
+42
@@ -144,6 +144,48 @@ accepts the following values:
144
- `return`: In the `return` mode, the eBPF collector monitors the same kernel functions as `entry`, but also creates
145
new charts for the return of these functions, such as errors. Monitoring function returns can help in debugging
146
software, such as failing to close file descriptors or creating zombie processes.
147
+
148
+#### Integration with `apps.plugin`
149
+
150
+The eBPF collector also creates charts for each running application through an integration with the
151
+[`apps.plugin`](/collectors/apps.plugin/README.md). This integration helps you understand how specific applications
152
+interact with the Linux kernel.
153
+
154
+When the integration is enabled, your dashboard will also show the following charts using low-level Linux metrics:
155
+
156
+- eBPF syscall
157
+ - Number of calls to open files.
158
+ - Number of files closed.
159
+ - Number of calls to delete files.
160
+ - Number of calls to `vfs_write`.
161
+ - Number of calls to `vfs_read`.
162
+ - Number of bytes written trough `vfs_write`
163
+ - Number of bytes read trough `vfs_read`
164
+ - Number of process created trough `do_fork`
165
+ - Number of threads created trough `do_fork` or `__x86_64_sys_clone`, depending on your system's kernel version.
166
+ - Number of times that a process called `do_exit`.
167
+ - Number of calls to open files that returned errors.
168
+ - Number of calls to close files that returned errors.
169
+ - Number of calls to read a file that returned errors.
170
+ - Number of calls to read a file that returned errors.
171
+- eBPF net
172
+ - Number of bytes transmited per seconds.
173
+
174
+If you want to disable these charts, change the setting `disable apps` to `no`.
175
+
176
+```conf
177
+[global]
178
+ disable apps = no
179
+```
180
+
181
+### `[ebpf programs]`
182
+
183
+The eBPF collector enables and runs the following eBPF programs by default:
184
+
185
+- `process`: This eBPF program creates charts that show information about process creation, VFS IO, and files removed.
186
+ When in `return` mode, it also creates charts showing errors when these operations are executed.
187
+- `network viewer`: This eBPF program creates charts with information about `TCP` and `UDP` functions, including the
188
+ bandwidth consumed by each.
189
190
## Troubleshooting
191
web/gui/dashboard_info.js
+53
-10
@@ -3049,44 +3049,87 @@ netdataDashboard.context = {
3049
// ------------------------------------------------------------------------
3050
// eBPF
3051
3052
+ 'ebpf.tcp_functions': {
3053
+ title : 'TCP calls',
3054
+ info: 'Successful or failed calls to functions <code>tcp_sendmsg</code>, <code>tcp_cleanup_rbuf</code> and <code>tcp_close</code.'
3055
+ },
3056
+
3057
+ 'ebpf.tcp_bandwidth': {
3058
+ title : 'TCP bandwidth',
3059
+ info: 'Bytes sent and received for functions <code>tcp_sendmsg</code> and <code>tcp_cleanup_rbuf</code>'
3060
+ },
3061
+
3062
+ 'ebpf.tcp_error': {
3063
+ title : 'TCP errors',
3064
+ info: 'Failed calls that to functions <code>tcp_sendmsg</code>, <code>tcp_cleanup_rbuf</code> and <code>tcp_close</code>.'
3065
+ },
3066
+
3067
+ 'ebpf.udp_functions': {
3068
+ title : 'UDP calls',
3069
+ info: 'Successful or failed calls to functions <code>udp_sendmsg</code> and <code>udp_recvmsg</code>.'
3070
+ },
3071
+
3072
+ 'ebpf.udp_bandwidth': {
3073
+ title : 'UDP bandwidth',
3074
+ info: 'Bytes sent and received for functions <code>udp_sendmsg</code> and <code>udp_recvmsg</code>'
3075
+ },
3076
+
3077
'ebpf.file_descriptor': {
3053
- info: 'File descriptor shows the number of calls for internal functions on Linux kernel. The open dimension is attached to the kernel internal function \'do_sys_open\', that is the common function called from open(2) and openat(2). The close dimension is attached to the function \'__close_fd\', that is called from system call close(2).'
3078
+ title : 'File access',
3079
+ info: 'Calls for internal functions on Linux kernel. The open dimension is attached to the kernel internal function <code>do_sys_open</code>, which is the common function called from'+
3080
+ ' <a href="https://www.man7.org/linux/man-pages/man2/open.2.html" target="_blank">open(2)</a> ' +
3081
+ ' and <a href="https://www.man7.org/linux/man-pages/man2/openat.2.html" target="_blank">openat(2)</a>. ' +
3082
+ ' The close dimension is attached to the function <code>__close_fd</code>, which is called from system call' +
3083
+ ' <a href="https://www.man7.org/linux/man-pages/man2/close.2.html" target="_blank">close(2)</a>. '
3084
},
3085
3086
'ebpf.file_error': {
3057
- info: 'File error shows the number of calls that returned an error when called per period.'
3087
+ title : 'File access error',
3088
+ info: 'Failed calls to the kernel internal function <code>do_sys_open</code>, which is the common function called from'+
3089
+ ' <a href="https://www.man7.org/linux/man-pages/man2/open.2.html" target="_blank">open(2)</a> ' +
3090
+ ' and <a href="https://www.man7.org/linux/man-pages/man2/openat.2.html" target="_blank">openat(2)</a>. ' +
3091
+ ' The close dimension is attached to the function <code>__close_fd</code>, which is called from system call' +
3092
+ ' <a href="https://www.man7.org/linux/man-pages/man2/close.2.html" target="_blank">close(2)</a>. '
3093
},
3094
3095
'ebpf.deleted_objects': {
3061
- info: 'Deleted objects monitors calls to the function \'vfs_unlink\'. This chart does not show all events to remove files from the file system, because file systems can create their own functions to remove files.'
3096
+ title : 'VFS remove',
3097
+ info: 'This chart does not show all events that remove files from the file system, because file systems can create their own functions to remove files, it shows calls for the function <code>vfs_unlink</code>. '
3098
},
3099
3100
'ebpf.io': {
3065
- info: 'IO shows the number of calls for functions \'vfs_read\' and \'vfs_write\' independent of the return to be success or fail. Like the chart \'deleted_objects\', case the file system uses other function to store data on disks, this chart will not show events for it.'
3101
+ title : 'VFS IO',
3102
+ info: 'Successful or failed calls to functions <code>vfs_read</code> and <code>vfs_write</code>. This chart may not show all file system events if it uses other functions to store data on disk.'
3103
},
3104
3105
'ebpf.io_bytes': {
3069
- info: 'IO bytes shows the total of bytes read or written with success using the functions \'vfs_read\' and \'vfs_write\'.'
3106
+ title : 'VFS bytes written',
3107
+ info: 'Total of bytes read or written with success using the functions <code>vfs_read</code> and <code>vfs_write</code>.'
3108
},
3109
3110
'ebpf.io_error': {
3073
- info: 'IO error shows the number of calls for \'vfs_read\' and \'vfs_write\' that did not have success.'
3111
+ title : 'VFS IO error',
3112
+ info: 'Failed calls to functions <code>vfs_read</code> and <code>vfs_write</code>.'
3113
},
3114
3115
'ebpf.process_thread': {
3077
- info: 'Process thread counts the number of times that the function \'do_fork\' was called to create a new task. Task is the common name used to define process and tasks inside the kernel, to identify the threads, Netdata also counts the number of calls for \'sys_clone\' that has the flag \'CLONE_THREAD\' set.'
3116
+ title : 'Task creation',
3117
+ info: 'Number of times that the function <code>do_fork</code> is called to create a new task, which is the common name used to define process and tasks inside the kernel. Netdata identifies the threads by couting the number of calls for <code>sys_clone</code> that has the flag <code>CLONE_THREAD</code> set.'
3118
},
3119
3120
'ebpf.exit': {
3081
- info: 'Exit count the number of calls for the functions responsible to close (\'do_exit\') and release(\'release_task\') tasks.'
3121
+ title : 'Exit monitoring',
3122
+ info: 'Calls for the functions responsible for closing (<code>do_exit</code>) and releasing (<code>release_task</code>) tasks.'
3123
},
3124
3125
'ebpf.task_error': {
3085
- info: 'Task error count the number of errors to create a new process or thread.'
3126
+ title : 'Task error',
3127
+ info: 'Number of errors to create a new process or thread.'
3128
},
3129
3130
'ebpf.process_status': {
3089
- info: 'This chart demonstrate the difference between the number of process created and the number of threads created per period(\'process\' dimension), it also shows the number of possible zombie process running on system.'
3131
+ title : 'Task status',
3132
+ info: 'Difference between the number of process created and the number of threads created per period(<code>process</code> dimension), it also shows the number of possible zombie process running on system.'
3133
},
3134
3135
// ------------------------------------------------------------------------