3 Every module should be compatible with python2 and python3.
4 All third party libraries should be installed system-wide or in `python_modules` directory.
5 Module configurations are written in YAML and **pyYAML is required**.
7 Every configuration file must have one of two formats:
9 - Configuration for only one job:
12 update_every : 2 # update frequency
13 retries : 1 # how many failures in update() is tolerated
14 priority : 20000 # where it is shown on dashboard
16 other_var1 : bla # variables passed to module
20 - Configuration for many jobs (ex. mysql):
29 update_every : 5 # job update frequency
30 other_var1 : some_val # module specific variable
33 priority : 5 # job position on dashboard
34 retries : 20 # job retries
35 other_var2 : val # module specific variable
38 `update_every`, `retries`, and `priority` are always optional.
42 The following python.d modules are supported:
46 This module will monitor one or more apache servers depending on configuration.
49 * apache with enabled `mod_status`
51 It produces the following charts:
53 1. **Requests** in requests/s
59 3. **Async Connections**
64 4. **Bandwidth** in kilobytes/s
71 6. **Lifetime Avg. Requests/s** in requests/s
74 7. **Lifetime Avg. Bandwidth/s** in kilobytes/s
77 8. **Lifetime Avg. Response Size** in bytes/request
82 Needs only `url` to server's `server-status?auto`
84 Here is an example for 2 servers:
91 url : 'http://localhost/server-status?auto'
95 url : 'http://www.apache.org/server-status?auto'
100 Without configuration, module attempts to connect to `http://localhost/server-status?auto`
106 Module monitors apache mod_cache log and produces only one chart:
108 **cached responses** in percent cached
121 log_path : '/var/log/apache2/cache.log'
124 If no configuration is given, module will attempt to read log file at `/var/log/apache2/cache.log`
130 Module shows current cpu frequency by looking at appropriate files in /sys/devices
133 Processor which presents data scaling frequency data
135 It produces one chart with multiple lines (one line per core).
142 sys_dir: "/sys/devices"
145 If no configuration is given, module will search for `scaling_cur_freq` files in `/sys/devices` directory.
146 Directory is also prefixed with `NETDATA_HOST_PREFIX` if specified.
152 This module provides statistics information from dovecot server.
153 Statistics are taken from dovecot socket by executing `EXPORT global` command.
154 More information about dovecot stats can be found on [project wiki page.](http://wiki2.dovecot.org/Statistics)
157 Dovecot unix socket with R/W permissions for user netdata or dovecot with configured TCP/IP socket.
159 Module gives information with following charts:
167 3. **commands** - number of IMAP commands
174 5. **Context Switches**
178 6. **disk** in bytes/s
182 7. **bytes** in bytes/s
186 8. **number of syscalls** in syscalls/s
190 9. **lookups** - number of lookups per second
194 10. **hits** - number of cache hits
197 11. **attempts** - authorization attemts
201 12. **cache** - cached authorization hits
217 socket : '/var/run/dovecot/stats'
220 If no configuration is given, module will attempt to connect to dovecot using unix socket localized in `/var/run/dovecot/stats`
226 Simple module executing `exim -bpc` to grab exim queue.
227 This command can take a lot of time to finish its execution thus it is not recommended to run it every second.
229 It produces only one chart:
231 1. **Exim Queue Emails**
234 Configuration is not needed.
240 Module monitor fail2ban log file to show all bans for all active jails
243 * fail2ban.log file MUST BE readable by netdata (A good idea is to add **create 0640 root netdata** to fail2ban conf at logrotate.d)
245 It produces one chart with multiple lines (one line per jail)
253 log_path: '/var/log/fail2ban.log'
254 conf_path: '/etc/fail2ban/jail.local'
255 exclude: 'dropbear apache'
257 If no configuration is given, module will attempt to read log file at `/var/log/fail2ban.log` and conf file at `/etc/fail2ban/jail.local`.
258 If conf file is not found default jail is `ssh`.
264 Uses the `radclient` command to provide freeradius statistics. It is not recommended to run it every second.
268 1. **Authentication counters:**
271 * auth-dropped-requests
272 * auth-duplicate-requests
273 * auth-invalid-requests
274 * auth-malformed-requests
277 2. **Accounting counters:** [optional]
278 * accounting-requests
279 * accounting-responses
280 * acct-dropped-requests
281 * acct-duplicate-requests
282 * acct-invalid-requests
283 * acct-malformed-requests
286 3. **Proxy authentication counters:** [optional]
287 * proxy-access-accepts
288 * proxy-access-rejects
289 * proxy-auth-dropped-requests
290 * proxy-auth-duplicate-requests
291 * proxy-auth-invalid-requests
292 * proxy-auth-malformed-requests
293 * proxy-auth-unknown-types
295 4. **Proxy accounting counters:** [optional]
296 * proxy-accounting-requests
297 * proxy-accounting-responses
298 * proxy-acct-dropped-requests
299 * proxy-acct-duplicate-requests
300 * proxy-acct-invalid-requests
301 * proxy-acct-malformed-requests
302 * proxy-acct-unknown-typesa
313 secret : 'adminsecret'
314 acct : False # Freeradius accounting statistics.
315 proxy_auth : False # Freeradius proxy authentication statistics.
316 proxy_acct : False # Freeradius proxy accounting statistics.
319 **Freeradius server configuration:**
321 The configuration for the status server is automatically created in the sites-available directory.
322 By default, server is enabled and can be queried from every client.
323 FreeRADIUS will only respond to status-server messages, if the status-server virtual server has been enabled.
325 To do this, create a link from the sites-enabled directory to the status file in the sites-available directory:
327 * ln -s ../sites-available/status status
329 and restart/reload your FREERADIUS server.
335 Module monitors disk temperatures from one or more hddtemp daemons.
338 Running `hddtemp` in daemonized mode with access on tcp port
340 It produces one chart **Temperature** with dynamic number of dimensions (one per disk)
352 If no configuration is given, module will attempt to connect to hddtemp daemon on `127.0.0.1:7634` address
358 Module monitors [IPFS](https://ipfs.io) basic information.
360 1. **Bandwidth** in kbits/s
369 Only url to IPFS server is needed.
376 url : 'http://localhost:5001'
383 Module monitor leases database to show all active leases for given pools.
386 * dhcpd leases file MUST BE readable by netdata
387 * pools MUST BE in CIDR format
391 1. **Pools utilization** Aggregate chart for all pools.
392 * utilization in percent
395 * leases (overall number of leases for all pools)
397 3. **Active leases** for every pools
398 * leases (number of active leases in pool)
407 leases_path : '/var/lib/dhcp/dhcpd.leases'
408 pools : '192.168.3.0/24 192.168.4.0/24 192.168.5.0/24'
411 In case of python2 you need to install `py2-ipaddress` to make plugin work.
412 The module will not work If no configuration is given.
419 Module monitor /proc/mdstat
423 1. **Health** Number of failed disks in every array (aggregate chart).
426 * total (number of devices array ideally would have)
427 * inuse (number of devices currently are in use)
429 3. **Current status**
431 * recovery in percent
435 4. **Operation status** (if resync/recovery/reshape/check is active)
437 * speed in megabytes/s
440 No configuration is needed.
446 Memcached monitoring module. Data grabbed from [stats interface](https://github.com/memcached/memcached/wiki/Commands#stats).
448 1. **Network** in kilobytes/s
452 2. **Connections** per second
457 3. **Items** in cluster
461 4. **Evicted and Reclaimed** items
465 5. **GET** requests/s
469 6. **GET rate** rate in requests/s
472 7. **SET rate** rate in requests/s
475 8. **DELETE** requests/s
479 9. **CAS** requests/s
484 10. **Increment** requests/s
488 11. **Decrement** requests/s
492 12. **Touch** requests/s
496 13. **Touch rate** rate in requests/s
510 If no configuration is given, module will attempt to connect to memcached instance on `127.0.0.1:11211` address.
516 Module monitors one or more mysql servers
519 * python library [MySQLdb](https://github.com/PyMySQL/mysqlclient-python) (faster) or [PyMySQL](https://github.com/PyMySQL/PyMySQL) (slower)
521 It will produce following charts (if data is available):
523 1. **Bandwidth** in kbps
527 2. **Queries** in queries/sec
532 3. **Operations** in operations/sec
549 4. **Table Locks** in locks/sec
553 5. **Select Issues** in issues/sec
560 6. **Sort Issues** in issues/sec
567 You can provide, per server, the following:
569 1. username which have access to database (deafults to 'root')
570 2. password (defaults to none)
571 3. mysql my.cnf configuration file
572 4. mysql socket (optional)
573 5. mysql host (ip or hostname)
574 6. mysql port (defaults to 3306)
576 Here is an example for 3 servers:
584 'my.cnf' : '/etc/mysql/my.cnf'
589 pass : 'blablablabla'
590 socket : '/var/run/mysqld/mysqld.sock'
601 If no configuration is given, module will attempt to connect to mysql server via unix socket at `/var/run/mysqld/mysqld.sock` without password and with username `root`
607 This module will monitor one or more nginx servers depending on configuration. Servers can be either local or remote.
610 * nginx with configured 'ngx_http_stub_status_module'
611 * 'location /stub_status'
613 Example nginx configuration can be found in 'python.d/nginx.conf'
615 It produces following charts:
617 1. **Active Connections**
620 2. **Requests** in requests/s
623 3. **Active Connections by Status**
628 4. **Connections Rate** in connections/s
634 Needs only `url` to server's `stub_status`
636 Here is an example for local server:
643 url : 'http://localhost/stub_status'
647 Without configuration, module attempts to connect to `http://localhost/stub_status`
653 Module monitors nginx access log and produces only one chart:
655 1. **nginx status codes** in requests/s
663 Sample for two vhosts:
667 path: '/var/log/nginx/access-A.log'
671 path: '/var/log/nginx/access-B.log'
674 When no configuration file is found, module tries to parse `/var/log/nginx/access.log` file.
680 Module monitor openvpn-status log file.
684 * If you are running multiple OpenVPN instances out of the same directory, MAKE SURE TO EDIT DIRECTIVES which create output files
685 so that multiple instances do not overwrite each other's output files.
687 * Make sure NETDATA USER CAN READ openvpn-status.log
689 * Update_every interval MUST MATCH interval on which OpenVPN writes operational status to log file.
693 1. **Users** OpenVPN active users
696 2. **Traffic** OpenVPN overall bandwidth usage in kilobit/s
706 log_path : '/var/log/openvpn-status.log'
713 This module will monitor one or more php-fpm instances depending on configuration.
716 * php-fpm with enabled `status` page
717 * access to `status` page via web server
719 It produces following charts:
721 1. **Active Connections**
726 2. **Requests** in requests/s
735 Needs only `url` to server's `status`
737 Here is an example for local instance:
744 url : 'http://localhost/status'
748 Without configuration, module attempts to connect to `http://localhost/status`
754 Simple module executing `postfix -p` to grab postfix queue.
756 It produces only two charts:
758 1. **Postfix Queue Emails**
761 2. **Postfix Queue Emails Size** in KB
764 Configuration is not needed.
770 Get INFO data from redis instance.
772 Following charts are drawn:
774 1. **Operations** per second
777 2. **Hit rate** in percent
780 3. **Memory utilization** in kilobytes
785 * lines are creates dynamically based on how many databases are there
799 socket : '/var/lib/redis/redis.sock'
807 When no configuration file is found, module tries to connect to TCP/IP socket: `localhost:6379`.
813 System sensors information.
815 Charts are created dynamically.
819 For detailed configuration information please read [`sensors.conf`](https://github.com/firehol/netdata/blob/master/conf.d/python.d/sensors.conf) file.
825 This module will monitor one or more squid instances depending on configuration.
827 It produces following charts:
829 1. **Client Bandwidth** in kilobits/s
834 2. **Client Requests** in requests/s
839 3. **Server Bandwidth** in kilobits/s
843 4. **Server Requests** in requests/s
853 request : 'cache_object://localhost:3128/counters'
858 Without any configuration module will try to autodetect where squid presents its `counters` data
864 Present tomcat containers memory utilization.
868 1. **Requests** per second
871 2. **Volume** in KB/s
878 4. **JVM Free Memory** in MB
886 url : 'http://127.0.0.1:8080/manager/status?XML=true'
887 user : 'tomcat_username'
888 pass : 'secret_tomcat_password'
891 Without configuration, module attempts to connect to `http://localhost:8080/manager/status?XML=true`, without any credentials.
892 So it will probably fail.