fixed documentation links (#4418)
* fixed documentation links * updated apps.plugin info * updated apps.plugin info * updated apps.plugin info
Costa Tsaousis committed
Oct 17, 2018 at 13:34 UTC
8cff4f255e62e0414527b2b01278adc4243baee1
4 files changed
+371
-100
collectors/apps.plugin/README.md
+169
-48
@@ -1,48 +1,94 @@
1
# apps.plugin
2
3
-This plugin provides charts for 3 sections of the default dashboard:
3
+`apps.plugin` breaks down system resource usage to **processes**, **users** and **user groups**.
4
5
-1. Per application charts
6
-2. Per user charts
7
-3. Per user group charts
5
+To achieve this task, it iterates through the whole process tree, collecting resource usage information
6
+for every process found running.
7
9
-## Per application charts
8
+Since netdata needs to present this information in charts and track them through time,
9
+instead of presenting a `top` like list, `apps.plugin` uses a pre-defined list of **process groups**
10
+to which it assigns all running processes. This list is [customizable](apps_groups.conf) and netdata
11
+ships with a good default for most cases (to edit it on your system run `/etc/netdata/edit-config apps_groups.conf`).
12
11
-This plugin walks through the entire `/proc` filesystem and aggregates statistics for applications of interest, defined in `/etc/netdata/apps_groups.conf` (the default is [here](apps_groups.conf)) (to edit it on your system run `/etc/netdata/edit-config apps_groups.conf`).
13
+So, `apps.plugin` builds a process tree (much like `ps fax` does in Linux), and groups
14
+processes together (evaluating both child and parent processes) so that the result is always a list with
15
+a predefined set of members (of course, only process groups found running are reported).
16
13
-The plugin internally builds a process tree (much like `ps fax` does), and groups processes together (evaluating both child and parent processes) so that the result is always a chart with a predefined set of dimensions (of course, only application groups found running are reported).
17
+> If you find that `apps.plugin` categorizes standard applications as `other`, we would be
18
+> glad to accept pull requests improving the [defaults](apps_groups.conf) shipped with netdata.
19
15
-Using this information it provides the following charts (per application group defined in `/etc/netdata/apps_groups.conf` - to edit it on your system run `/etc/netdata/edit-config apps_groups.conf`):
20
+Unlike traditional process monitoring tools (like `top`), `apps.plugin` is able to account the resource
21
+utilization of exit processes. Their utilization is accounted at their currently running parents.
22
+So, `apps.plugin` is perfectly able to measure the resources used by shell scripts and other processes
23
+that fork/spawn other short lived processes hundreds of times per second.
24
17
-1. Total CPU usage
18
-2. Total User CPU usage
19
-3. Total System CPU usage
20
-4. Total Disk Physical Reads
21
-5. Total Disk Physical Writes
22
-6. Total Disk Logical Reads
23
-7. Total Disk Logical Writes
24
-8. Total Open Files (unique files - if a file is found open multiple times, it is counted just once)
25
-9. Total Dedicated Memory (non shared)
26
-10. Total Minor Page Faults
27
-11. Total Number of Processes
28
-12. Total Number of Threads
29
-13. Total Number of Pipes
30
-14. Total Swap Activity (Major Page Faults)
31
-15. Total Open Sockets
25
+For example, ssh to a server running netdata and execute this:
26
33
-## Per User Charts
27
+```sh
28
+while true; do ls -l /var/run >/dev/null; done
29
+```
30
+
31
+All the console tools will report that a a CPU core is 100% used, but they will fail to identify which
32
+process is using all that CPU (because there is no single process using it - thousands of `ls` per second
33
+are using it). Netdata however, will be able to identify that `ssh` is using it
34
+(`ssh` is the parent process group defined in its [default config](apps_groups.conf)):
35
+
36
+
37
+
38
+This feature makes `apps.plugin` unique in narrowing down the list of offending processes that may be
39
+responsible for slow downs, or abusing system resources.
40
+
41
+## Charts
42
+
43
+`apps.plugin` provides charts for 3 sections:
44
+
45
+1. Per application charts as **Applications** at netdata dashboards
46
+2. Per user charts as **Users** at netdata dashboards
47
+3. Per user group charts as **User Groups** at netdata dashboards
48
+
49
+Each of these sections provides the same number of charts:
50
+
51
+- CPU Utilization
52
+ - Total CPU usage
53
+ - User / System CPU usage
54
+- Disk I/O
55
+ - Physical Reads / Writes
56
+ - Logical Reads / Writes
57
+ - Open Unique Files (if a file is found open multiple times, it is counted just once)
58
+- Memory
59
+ - Real Memory Used (non shared)
60
+ - Virtual Memory Allocated
61
+ - Minor Page Faults (i.e. memory activity)
62
+- Processes
63
+ - Threads Running
64
+ - Processes Running
65
+ - Pipes Open
66
+- Swap Memory
67
+ - Swap Memory Used
68
+ - Major Page Faults (i.e. swap activity)
69
+- Network
70
+ - Sockets Open
71
35
-All the above charts, are also grouped by username, using the effective uid of each process.
72
+The above are reported:
73
37
-## Per Group Charts
74
+- For **Applications** per [target configured](apps_groups.conf).
75
+- For **Users** per username or UID (when the username is not available).
76
+- For **User Groups** per groupname or GID (when groupname is not available).
77
39
-All the above charts, are also grouped by group name, using the effective gid of each process.
78
+## Performance
79
41
-## CPU Usage
80
+`apps.plugin` is a complex piece of software and has a lot of work to do
81
+We are proud that `apps.plugin` is a lot faster compared to any other similar tool,
82
+while collecting a lot more information for the processes, however the fact is that
83
+this plugin requires more CPU resources than the netdata daemon itself.
84
43
-`apps.plugin` is a complex software piece and has a lot of work to do (actually this plugin requires more CPU resources that the netdata daemon). For each process running, `apps.plugin` reads several `/proc` files to get CPU usage, memory allocated, I/O usage, open file descriptors, etc. Doing this work per-second, especially on hosts with several thousands of processes, may increase the CPU resources consumed by the plugin.
85
+Under Linux, for each process running, `apps.plugin` reads several `/proc` files
86
+per process. Doing this work per-second, especially on hosts with several thousands
87
+of processes, may increase the CPU resources consumed by the plugin.
88
45
-In such cases, you many need to lower its data collection frequency. To do this, edit `/etc/netdata/netdata.conf` and find this section:
89
+In such cases, you many need to lower its data collection frequency.
90
+
91
+To do this, edit `/etc/netdata/netdata.conf` and find this section:
92
93
```
94
[plugin:apps]
@@ -50,8 +96,8 @@ In such cases, you many need to lower its data collection frequency. To do this,
96
# command options =
97
```
98
53
-Uncomment the line `update every` and set it to a higher number. If you just set it to ` 2 `, its CPU resources will be cut in half, and data collection will be once every 2 seconds.
54
-
99
+Uncomment the line `update every` and set it to a higher number. If you just set it to ` 2 `,
100
+its CPU resources will be cut in half, and data collection will be once every 2 seconds.
101
102
## Configuration
103
@@ -64,27 +110,63 @@ The configuration file works accepts multiple lines, each having this format:
110
group: process1 process2 ...
111
```
112
67
-Process names should be given as they appear when running `ps -e`. The program will actually match the process names in the `/proc/PID/status` file. So, to be sure the name is right for a process running with PID ` X `, do this:
113
+Each group can be given multiple times, to add more processes to it.
114
69
-```sh
70
-cat /proc/X/status
71
-```
115
+For the **Applications** section, only groups configured in this file are reported.
116
+All other processes will be reported as `other`.
117
+
118
+For each process given, its whole process tree will be grouped, not just the process matched.
119
+The plugin will include both parents and children.
120
+
121
+The process names are the ones returned by:
122
+
123
+ - `ps -e` or `cat /proc/PID/stat`
124
+ - in case of substring mode (see below): `/proc/PID/cmdline`
125
+
126
+To add process names with spaces, enclose them in quotes (single or double)
127
+example: ` 'Plex Media Serv' ` or ` "my other process" `.
128
+
129
+You can add an asterisk ` * ` at the beginning and/or the end of a process:
130
73
-The first line on the output is `Name: xxxxx`. This is the process name `apps.plugin` sees.
131
+ - `*name` *suffix* mode: will search for processes ending with `name` (at `/proc/PID/stat`)
132
+ - `name*` *prefix* mode: will search for processes beginning with `name` (at `/proc/PID/stat`)
133
+ - `*name*` *substring* mode: will search for `name` in the whole command line (at `/proc/PID/cmdline`)
134
75
-The order of the lines in the file is important only if you include the same process name to multiple groups.
135
+If you enter even just one *name* (substring), `apps.plugin` will process
136
+`/proc/PID/cmdline` for all processes (of course only once per process: when they are first seen).
137
77
-## Apps plugin is missing information
138
+To add processes with single quotes, enclose them in double quotes: ` "process with this ' single quote" `
139
79
-`apps.plugin` requires additional privileges to collect all the information it needs. The problem is described in issue #157.
140
+To add processes with double quotes, enclose them in single quotes: ` 'process with this " double quote' `
141
81
-When netdata is installed, `apps.plugin` is given the capabilities `cap_dac_read_search,cap_sys_ptrace+ep`. If that is not possible (i.e. `setcap` fails), `apps.plugin` is setuid to `root`.
142
+If a group or process name starts with a ` - `, the dimension will be hidden from the chart (cpu chart only).
143
83
-## linux capabilities in containers
144
+If a process starts with a ` + `, debugging will be enabled for it (debugging produces a lot of output - do not enable it in production systems).
145
85
-There are a few cases, like `docker` and `virtuozzo` containers, where `setcap` succeeds, but the capabilities are silently ignored (in `lxc` containers `setcap` fails).
146
+You can add any number of groups. Only the ones found running will affect the charts generated.
147
+However, producing charts with hundreds of dimensions may slow down your web browser.
148
87
-In these cases that `setcap` succeeds by capabilities do not work, you will have to setuid to root `apps.plugin` by running these commands:
149
+The order of the entries in this list is important: the first that matches a process is used, so put important
150
+ones at the top. Processes not matched by any row, will inherit it from their parents or children.
151
+
152
+The order also controls the order of the dimensions on the generated charts (although applications started
153
+after apps.plugin is started, will be appended to the existing list of dimensions the netdata daemon maintains).
154
+
155
+## Permissions
156
+
157
+`apps.plugin` requires additional privileges to collect all the information it needs.
158
+The problem is described in issue #157.
159
+
160
+When netdata is installed, `apps.plugin` is given the capabilities `cap_dac_read_search,cap_sys_ptrace+ep`.
161
+If this fails (i.e. `setcap` fails), `apps.plugin` is setuid to `root`.
162
+
163
+#### linux capabilities in containers
164
+
165
+There are a few cases, like `docker` and `virtuozzo` containers, where `setcap` succeeds, but the capabilities
166
+are silently ignored (in `lxc` containers `setcap` fails).
167
+
168
+In these cases ()`setcap` succeeds but capabilities do not work), you will have to setuid
169
+to root `apps.plugin` by running these commands:
170
171
```sh
172
chown root:netdata /usr/libexec/netdata/plugins.d/apps.plugin
@@ -93,11 +175,50 @@ chmod 4750 /usr/libexec/netdata/plugins.d/apps.plugin
175
176
You will have to run these, every time you update netdata.
177
178
+## Security
179
+
180
+`apps.plugin` performs a hard-coded function of building the process tree in memory,
181
+iterating forever, collecting metrics for each running process and sending them to netdata.
182
+This is a one-way communication, from `apps.plugin` to netdata.
183
+
184
+So, since `apps.plugin` cannot be instructed by netdata for the actions it performs,
185
+we think it is pretty safe to allow it have these increased privileges.
186
+
187
+Keep in mind that `apps.plugin` will still run without escalated permissions,
188
+but it will not be able to collect all the information.
189
+
190
+## Application Badges
191
+
192
+You can create badges that you can embed anywhere you like, with URLs like this:
193
+
194
+```
195
+https://your.netdata.ip:19999/api/v1/badge.svg?chart=apps.processes&dimensions=myapp&value_color=green%3E0%7Cred
196
+```
197
+
198
+The color expression unescaped is this: `value_color=green>0|red`.
199
+
200
+Here is an example for the process group `sql` at `https://registry.my-netdata.io`:
201
+
202
+
203
97
-### Is is safe to give `apps.plugin` these privileges?
204
+Netdata is able give you a lot more badges for your app.
205
+Examples below for process group `sql`:
206
99
-`apps.plugin` performs a hard-coded function of building the process tree in memory, iterating forever, collecting metrics for each running process and sending them to netdata. This is a one-way communication, from `apps.plugin` to netdata.
207
+- CPU usage: 
208
+- Disk Physical Reads 
209
+- Disk Physical Writes 
210
+- Disk Logical Reads 
211
+- Disk Logical Writes 
212
+- Open Files 
213
+- Real Memory 
214
+- Virtual Memory 
215
+- Swap Memory 
216
+- Minor Page Faults 
217
+- Processes 
218
+- Threads 
219
+- Major Faults (swap activity) 
220
+- Open Pipes 
221
+- Open Sockets 
222
101
-So, since `apps.plugin` cannot be instructed by netdata for the actions it performs, we think it is pretty safe to allow it have these increased privileges.
223
103
-Keep in mind that `apps.plugin` will still run without these permissions, but it will not be able to collect all the data for every process.
224
+For more information about badges check [Generating Badges](https://github.com/netdata/netdata/wiki/Generating-Badges)
\ No newline at end of file
collectors/charts.d.plugin/apache/README.md
+125
@@ -1,2 +1,127 @@
1
> THIS MODULE IS OBSOLETE.
2
> USE THE PYTHON ONE - IT SUPPORTS MULTIPLE JOBS AND IT IS MORE EFFICIENT
3
+
4
+---
5
+
6
+# Apache Plugin (apache)
7
+
8
+The `apache` collector visualizes key performance data for an apache web server.
9
+
10
+## Example netdata charts
11
+
12
+For apache 2.2:
13
+
14
+
15
+
16
+For apache 2.4:
17
+
18
+
19
+
20
+## How it works
21
+
22
+It runs `curl "http://apache.host/server-status?auto` to fetch the current status of apache.
23
+
24
+It has been tested with apache 2.2 and apache 2.4. The latter also provides connections information (total and break down by status).
25
+
26
+Apache 2.2 response:
27
+
28
+```sh
29
+$ curl "http://127.0.0.1/server-status?auto"
30
+Total Accesses: 80057
31
+Total kBytes: 223017
32
+CPULoad: .018287
33
+Uptime: 64472
34
+ReqPerSec: 1.24173
35
+BytesPerSec: 3542.15
36
+BytesPerReq: 2852.59
37
+BusyWorkers: 1
38
+IdleWorkers: 49
39
+Scoreboard: _________________________......................................._W_______________________.......................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................
40
+```
41
+
42
+Apache 2.4 response:
43
+
44
+```sh
45
+$ curl "http://127.0.0.1/server-status?auto"
46
+127.0.0.1
47
+ServerVersion: Apache/2.4.18 (Unix)
48
+ServerMPM: event
49
+Server Built: Dec 14 2015 08:05:54
50
+CurrentTime: Saturday, 23-Jan-2016 14:42:06 EET
51
+RestartTime: Saturday, 23-Jan-2016 04:57:13 EET
52
+ParentServerConfigGeneration: 2
53
+ParentServerMPMGeneration: 1
54
+ServerUptimeSeconds: 35092
55
+ServerUptime: 9 hours 44 minutes 52 seconds
56
+Load1: 0.32
57
+Load5: 0.32
58
+Load15: 0.27
59
+Total Accesses: 32403
60
+Total kBytes: 34464
61
+CPUUser: 30.37
62
+CPUSystem: 29.55
63
+CPUChildrenUser: 0
64
+CPUChildrenSystem: 0
65
+CPULoad: .170751
66
+Uptime: 35092
67
+ReqPerSec: .923373
68
+BytesPerSec: 1005.67
69
+BytesPerReq: 1089.13
70
+BusyWorkers: 1
71
+IdleWorkers: 99
72
+ConnsTotal: 0
73
+ConnsAsyncWriting: 0
74
+ConnsAsyncKeepAlive: 0
75
+ConnsAsyncClosing: 0
76
+Scoreboard: __________________________________________________________________________________________W_________............................................................................................................................................................................................................................................................................................................
77
+```
78
+
79
+From the apache status output it collects:
80
+
81
+ - total accesses (incremental value, rendered as requests/s)
82
+ - total bandwidth (incremental value, rendered as bandwidth/s)
83
+ - requests per second (this appears to be calculated by apache as an average for its lifetime, while the one calculated by netdata using the total accesses counter is real-time)
84
+ - bytes per second (average for the lifetime of the apache server)
85
+ - bytes per request (average for the lifetime of the apache server)
86
+ - workers by status (`busy` and `idle`)
87
+ - total connections (currently active connections - offered by apache 2.4+)
88
+ - async connections per status (`keepalive`, `writing`, `closing` - offered by apache 2.4+)
89
+
90
+## Configuration
91
+
92
+The configuration is stored in `/etc/netdata/charts.d/apache.conf`.
93
+To edit this file on your system run `/etc/netdata/edit-config charts.d/apache.conf`.
94
+
95
+The internal default is:
96
+
97
+```sh
98
+# the URL your apache server is responding with mod_status information.
99
+apache_url="http://127.0.0.1:80/server-status?auto"
100
+
101
+# use this to set custom curl options you may need
102
+apache_curl_opts=
103
+
104
+# set this to a NUMBER to overwrite the update frequency
105
+# it is in seconds
106
+apache_update_every=
107
+```
108
+
109
+The default `apache_update_every` is configured in netdata.
110
+
111
+## Auto-detection
112
+
113
+If you have configured your apache server to offer server-status information on localhost clients, the defaults should work fine.
114
+
115
+## Apache Configuration
116
+
117
+Apache configuration differs between distributions. Please check your distribution's documentation for information on enabling apache's `mod_status` module.
118
+
119
+If you are able to run successfully, by hand this command:
120
+
121
+```sh
122
+curl "http://127.0.0.1:80/server-status?auto"
123
+```
124
+
125
+netdata will be able to do it too.
126
+
127
+Notice: You may need to have the default `000-default.conf ` website enabled in order for the status mod to work.
collectors/fping.plugin/README.md
+17
-24
@@ -1,8 +1,10 @@
1
# fping.plugin
2
3
-The fping plugin supports monitoring latency, packet loss and uptime of any number of hosts, by pinging them with fping.
3
+The fping plugin supports monitoring latency, packet loss and uptime of any number of network end points,
4
+by pinging them with `fping`.
5
5
-A recent version of `fping` is required (one that supports option ` -N `). The supplied plugin can install it. Run:
6
+A recent version of `fping` is required (one that supports option ` -N `).
7
+The supplied plugin can install it, by running:
8
9
```sh
10
/usr/libexec/netdata/plugins.d/fping.plugin install
@@ -10,7 +12,8 @@ A recent version of `fping` is required (one that supports option ` -N `). The s
12
13
The above will download, build and install the right version as `/usr/local/bin/fping`.
14
13
-Then you need to edit `/etc/netdata/fping.conf` (to edit it on your system run `/etc/netdata/edit-config fping.conf`) like this:
15
+Then you need to edit `/etc/netdata/fping.conf` (to edit it on your system run
16
+`/etc/netdata/edit-config fping.conf`) like this:
17
18
```sh
19
# uncomment the following line - it should already be there
@@ -31,12 +34,10 @@ ping_every=200
34
fping_opts="-R -b 56 -i 1 -r 0 -t 5000"
35
```
36
34
-The latest version of the config: https://github.com/netdata/netdata/blob/master/conf.d/fping.conf
35
-
37
## alarms
38
39
netdata will automatically attach a few alarms for each host.
39
-Check the latest versions of the fping alarms here: https://github.com/netdata/netdata/blob/master/conf.d/health.d/fping.conf
40
+Check the [latest versions of the fping alarms](https://github.com/netdata/netdata/blob/master/health/health.d/fping.conf)
41
42
## Additional Tips
43
@@ -56,7 +57,8 @@ ping_every=5000
57
58
### Multiple fping Plugins With Different Settings
59
59
-You may need to run multiple fping plugins with different settings for different hosts. For example, you may need to ping a few hosts 10 times per second, and others once per second.
60
+You may need to run multiple fping plugins with different settings for different end points.
61
+For example, you may need to ping a few hosts 10 times per second, and others once per second.
62
63
netdata allows you to add as many `fping` plugins as you like.
64
@@ -64,40 +66,31 @@ Follow this procedure:
66
67
**1. Create New fping Configuration File**
68
67
-Step Into Configuration Directory
69
70
```sh
71
+# Step Into Configuration Directory
72
cd /etc/netdata
71
-```
72
-
73
-Copy Original fping Configuration File To New Configuration File
73
75
-```sh
74
+# Copy Original fping Configuration File To New Configuration File
75
cp fping.conf fping2.conf
76
```
77
79
-Edit `fping2.conf` and set the settings and the hosts you need
78
+Edit `fping2.conf` and set the settings and the hosts you need for the seconds instance.
79
80
**2. Soft Link Original fping Plugin to New Plugin File**
81
83
-Become root (If The Step Step Is Performed As Non-Root User)
84
-
82
```sh
83
+# Become root (If The Step Step Is Performed As Non-Root User)
84
sudo su
87
-```
85
89
-Step Into The Plugins Directory
90
-
91
-```sh
86
+# Step Into The Plugins Directory
87
cd /usr/libexec/netdata/plugins.d
93
-```
88
95
-Link fping.plugin to fping2.plugin
96
-
97
-```sh
89
+# Link fping.plugin to fping2.plugin
90
ln -s fping.plugin fping2.plugin
91
```
92
93
That's it. netdata will detect the new plugin and start it.
94
103
-You can name the new plugin any name you like. Just make sure the plugin and the configuration file have the same name.
95
+You can name the new plugin any name you like.
96
+Just make sure the plugin and the configuration file have the same name.
collectors/python.d.plugin/go_expvar/README.md
+60
-28
@@ -1,9 +1,9 @@
1
# go_expvar
2
3
-The `go_expvar` module can monitor any Go application that exposes its metrics with the use of `expvar` package from the Go standard library.
3
+The `go_expvar` module can monitor any Go application that exposes its metrics with the use of
4
+`expvar` package from the Go standard library.
5
6
`go_expvar` produces charts for Go runtime memory statistics and optionally any number of custom charts.
6
-Please see the [wiki page](https://github.com/netdata/netdata/wiki/Monitoring-Go-Applications) for more info.
7
8
For the memory statistics, it produces the following charts:
9
@@ -32,11 +32,13 @@ For the memory statistics, it produces the following charts:
32
33
## Monitoring Go Applications
34
35
-Netdata can be used to monitor running Go applications that expose their metrics with the use of the [expvar package](https://golang.org/pkg/expvar/) included in Go standard library.
35
+Netdata can be used to monitor running Go applications that expose their metrics with
36
+the use of the [expvar package](https://golang.org/pkg/expvar/) included in Go standard library.
37
37
-The `expvar` package exposes these metrics over HTTP and is very easy to use. Consider this minimal sample below:
38
+The `expvar` package exposes these metrics over HTTP and is very easy to use.
39
+Consider this minimal sample below:
40
39
-```
41
+```go
42
package main
43
44
import (
@@ -49,18 +51,23 @@ func main() {
51
}
52
```
53
52
-When imported this way, the `expvar` package registers a HTTP handler at `/debug/vars` that exposes Go runtime's memory statistics in JSON format. You can inspect the output by opening the URL in your browser (or by using `wget` or `curl`). Sample output:
54
+When imported this way, the `expvar` package registers a HTTP handler at `/debug/vars` that
55
+exposes Go runtime's memory statistics in JSON format. You can inspect the output by opening
56
+the URL in your browser (or by using `wget` or `curl`).
57
54
-```
58
+Sample output:
59
+
60
+```json
61
{
62
"cmdline": ["./expvar-demo-binary"],
63
"memstats": {"Alloc":630856,"TotalAlloc":630856,"Sys":3346432,"Lookups":27, <ommited for brevity>}
64
}
65
```
66
61
-You can of course expose and monitor your own variables as well. Here is a sample Go application that exposes a few custom variables:
67
+You can of course expose and monitor your own variables as well.
68
+Here is a sample Go application that exposes a few custom variables:
69
63
-```
70
+```go
71
package main
72
73
import (
@@ -91,13 +98,17 @@ func main() {
98
}
99
```
100
94
-Apart from the runtime memory stats, this application publishes two counters and the number of currently running Goroutines and updates these stats every second.
101
+Apart from the runtime memory stats, this application publishes two counters and the
102
+number of currently running Goroutines and updates these stats every second.
103
96
-In the next section, we will cover how to monitor and chart these exposed stats with the use of `netdata`s ```go_expvar``` module.
104
+In the next section, we will cover how to monitor and chart these exposed stats with
105
+the use of `netdata`s ```go_expvar``` module.
106
107
### Using netdata go_expvar module
108
100
-The `go_expvar` module is disabled by default. To enable it, edit [`python.d.conf`](https://github.com/netdata/netdata/blob/master/conf.d/python.d.conf) (to edit it on your system run `/etc/netdata/edit-config python.d.conf`), and change the `go_expvar` variable to `yes`:
109
+The `go_expvar` module is disabled by default. To enable it, edit [`python.d.conf`](../python.d.conf)
110
+(to edit it on your system run `/etc/netdata/edit-config python.d.conf`), and change the `go_expvar`
111
+variable to `yes`:
112
113
```
114
# Enable / Disable python.d.plugin modules
@@ -113,7 +124,10 @@ go_expvar: yes
124
...
125
```
126
116
-Next, we need to edit the module configuration file (found at [`/etc/netdata/python.d/go_expvar.conf`](https://github.com/netdata/netdata/blob/master/conf.d/python.d/go_expvar.conf) by default) (to edit it on your system run `/etc/netdata/edit-config python.d/go_expvar.conf`). The module configuration consists of jobs, where each job can be used to monitor a separate Go application. Let's see a sample job configuration:
127
+Next, we need to edit the module configuration file (found at [`/etc/netdata/python.d/go_expvar.conf`](go_expvar.conf) by default)
128
+(to edit it on your system run `/etc/netdata/edit-config python.d/go_expvar.conf`).
129
+The module configuration consists of jobs, where each job can be used to monitor a separate Go application.
130
+Let's see a sample job configuration:
131
132
```
133
# /etc/netdata/python.d/go_expvar.conf
@@ -129,23 +143,29 @@ Let's go over each of the defined options:
143
144
name: 'app1'
145
132
-This is the job name that will appear at the netdata dashboard. If not defined, the job_name (top level key) will be used.
146
+This is the job name that will appear at the netdata dashboard.
147
+If not defined, the job_name (top level key) will be used.
148
149
url: 'http://127.0.0.1:8080/debug/vars'
150
136
-This is the URL of the expvar endpoint. As the expvar handler can be installed in a custom path, the whole URL has to be specified. This value is mandatory.
151
+This is the URL of the expvar endpoint. As the expvar handler can be installed
152
+in a custom path, the whole URL has to be specified. This value is mandatory.
153
154
collect_memstats: true
155
140
-Whether to enable collecting stats about Go runtime's memory. You can find more information about the exposed values at the [runtime package docs](https://golang.org/pkg/runtime/#MemStats).
156
+Whether to enable collecting stats about Go runtime's memory. You can find more
157
+information about the exposed values at the [runtime package docs](https://golang.org/pkg/runtime/#MemStats).
158
159
extra_charts: {}
160
144
-Enables the user to specify custom expvars to monitor and chart. Will be explained in more detail below.
161
+Enables the user to specify custom expvars to monitor and chart.
162
+Will be explained in more detail below.
163
146
-**Note: if `collect_memstats` is disabled and no `extra_charts` are defined, the plugin will disable itself, as there will be no data to collect!**
164
+**Note: if `collect_memstats` is disabled and no `extra_charts` are defined, the plugin will
165
+disable itself, as there will be no data to collect!**
166
148
-Apart from these options, each job supports options inherited from netdata's `python.d.plugin` and its base `UrlService` class. These are:
167
+Apart from these options, each job supports options inherited from netdata's `python.d.plugin`
168
+and its base `UrlService` class. These are:
169
170
update_every: 1 # the job's data collection frequency
171
priority: 60000 # the job's order on the dashboard
@@ -155,24 +175,30 @@ Apart from these options, each job supports options inherited from netdata's `py
175
176
### Monitoring custom vars with go_expvar
177
158
-Now, memory stats might be useful, but what if you want netdata to monitor some custom values that your Go application exposes? The `go_expvar` module can do that as well with the use of the `extra_charts` configuration variable.
178
+Now, memory stats might be useful, but what if you want netdata to monitor some custom values
179
+that your Go application exposes? The `go_expvar` module can do that as well with the use of
180
+the `extra_charts` configuration variable.
181
160
-The `extra_charts` variable is a YaML list of netdata chart definitions. Each chart definition has the following keys:
182
+The `extra_charts` variable is a YaML list of netdata chart definitions.
183
+Each chart definition has the following keys:
184
185
id: netdata chart ID
186
options: a key-value mapping of chart options
187
lines: a list of line definitions
188
166
-**Note: please do not use dots in the chart or line ID field. See [this issue](https://github.com/netdata/netdata/pull/1902#issuecomment-284494195) for explanation.**
189
+**Note: please do not use dots in the chart or line ID field.
190
+See [this issue](https://github.com/netdata/netdata/pull/1902#issuecomment-284494195) for explanation.**
191
192
Please see these two links to the official netdata documentation for more information about the values:
193
170
-- [External plugins - charts](https://github.com/netdata/netdata/wiki/External-Plugins#chart)
194
+- [External plugins - charts](../../plugins.d/#chart)
195
- [Chart variables](https://github.com/netdata/netdata/wiki/How-to-write-new-module#global-variables-order-and-chart)
196
197
**Line definitions**
198
175
-Each chart can define multiple lines (dimensions). A line definition is a key-value mapping of line options. Each line can have the following options:
199
+Each chart can define multiple lines (dimensions).
200
+A line definition is a key-value mapping of line options.
201
+Each line can have the following options:
202
203
# mandatory
204
expvar_key: the name of the expvar as present in the JSON output of /debug/vars endpoint
@@ -187,9 +213,11 @@ Each chart can define multiple lines (dimensions). A line definition is a key-va
213
hidden: False
214
215
Please see the following link for more information about the options and their default values:
190
-[External plugins - dimensions](https://github.com/netdata/netdata/wiki/External-Plugins#dimension)
216
+[External plugins - dimensions](../../plugins.d/#dimension)
217
192
-Apart from top-level expvars, this plugin can also parse expvars stored in a multi-level map; All dicts in the resulting JSON document are then flattened to one level. Expvar names are joined together with '.' when flattening.
218
+Apart from top-level expvars, this plugin can also parse expvars stored in a multi-level map;
219
+All dicts in the resulting JSON document are then flattened to one level.
220
+Expvar names are joined together with '.' when flattening.
221
222
Example:
223
```
@@ -199,11 +227,15 @@ Example:
227
}
228
```
229
202
-In the above case, the exported variables will be available under `runtime.goroutines`, `counters.cnt1` and `counters.cnt2` expvar_keys. If the flattening results in a key collision, the first defined key wins and all subsequent keys with the same name are ignored.
230
+In the above case, the exported variables will be available under `runtime.goroutines`,
231
+`counters.cnt1` and `counters.cnt2` expvar_keys. If the flattening results in a key collision,
232
+the first defined key wins and all subsequent keys with the same name are ignored.
233
234
**Configuration example**
235
206
-The configuration below matches the second Go application described above. Netdata will monitor and chart memory stats for the application, as well as a custom chart of running goroutines and two dummy counters.
236
+The configuration below matches the second Go application described above.
237
+Netdata will monitor and chart memory stats for the application, as well as a custom chart of
238
+running goroutines and two dummy counters.
239
240
```
241
app1: