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 parses bind dump file to collect real-time performance metrics
133 * Version of bind must be 9.6 +
134 * Netdata must have permissions to run `rndc status`
138 1. **Name server statistics**
151 2. **Incoming queries**
172 3. **Outgoing queries**
173 * Same as Incoming queries
182 named_stats_path : '/var/log/bind/named.stats'
185 If no configuration is given, module will attempt to read named.stats file at `/var/log/bind/named.stats`
192 Module shows current cpu frequency by looking at appropriate files in /sys/devices
195 Processor which presents data scaling frequency data
197 It produces one chart with multiple lines (one line per core).
204 sys_dir: "/sys/devices"
207 If no configuration is given, module will search for `scaling_cur_freq` files in `/sys/devices` directory.
208 Directory is also prefixed with `NETDATA_HOST_PREFIX` if specified.
214 This module provides statistics information from dovecot server.
215 Statistics are taken from dovecot socket by executing `EXPORT global` command.
216 More information about dovecot stats can be found on [project wiki page.](http://wiki2.dovecot.org/Statistics)
219 Dovecot unix socket with R/W permissions for user netdata or dovecot with configured TCP/IP socket.
221 Module gives information with following charts:
229 3. **commands** - number of IMAP commands
236 5. **Context Switches**
240 6. **disk** in bytes/s
244 7. **bytes** in bytes/s
248 8. **number of syscalls** in syscalls/s
252 9. **lookups** - number of lookups per second
256 10. **hits** - number of cache hits
259 11. **attempts** - authorization attemts
263 12. **cache** - cached authorization hits
279 socket : '/var/run/dovecot/stats'
282 If no configuration is given, module will attempt to connect to dovecot using unix socket localized in `/var/run/dovecot/stats`
288 Simple module executing `exim -bpc` to grab exim queue.
289 This command can take a lot of time to finish its execution thus it is not recommended to run it every second.
291 It produces only one chart:
293 1. **Exim Queue Emails**
296 Configuration is not needed.
302 Module monitor fail2ban log file to show all bans for all active jails
305 * fail2ban.log file MUST BE readable by netdata (A good idea is to add **create 0640 root netdata** to fail2ban conf at logrotate.d)
307 It produces one chart with multiple lines (one line per jail)
315 log_path: '/var/log/fail2ban.log'
316 conf_path: '/etc/fail2ban/jail.local'
317 exclude: 'dropbear apache'
319 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`.
320 If conf file is not found default jail is `ssh`.
326 Uses the `radclient` command to provide freeradius statistics. It is not recommended to run it every second.
330 1. **Authentication counters:**
333 * auth-dropped-requests
334 * auth-duplicate-requests
335 * auth-invalid-requests
336 * auth-malformed-requests
339 2. **Accounting counters:** [optional]
340 * accounting-requests
341 * accounting-responses
342 * acct-dropped-requests
343 * acct-duplicate-requests
344 * acct-invalid-requests
345 * acct-malformed-requests
348 3. **Proxy authentication counters:** [optional]
349 * proxy-access-accepts
350 * proxy-access-rejects
351 * proxy-auth-dropped-requests
352 * proxy-auth-duplicate-requests
353 * proxy-auth-invalid-requests
354 * proxy-auth-malformed-requests
355 * proxy-auth-unknown-types
357 4. **Proxy accounting counters:** [optional]
358 * proxy-accounting-requests
359 * proxy-accounting-responses
360 * proxy-acct-dropped-requests
361 * proxy-acct-duplicate-requests
362 * proxy-acct-invalid-requests
363 * proxy-acct-malformed-requests
364 * proxy-acct-unknown-typesa
375 secret : 'adminsecret'
376 acct : False # Freeradius accounting statistics.
377 proxy_auth : False # Freeradius proxy authentication statistics.
378 proxy_acct : False # Freeradius proxy accounting statistics.
381 **Freeradius server configuration:**
383 The configuration for the status server is automatically created in the sites-available directory.
384 By default, server is enabled and can be queried from every client.
385 FreeRADIUS will only respond to status-server messages, if the status-server virtual server has been enabled.
387 To do this, create a link from the sites-enabled directory to the status file in the sites-available directory:
389 * ln -s ../sites-available/status status
391 and restart/reload your FREERADIUS server.
397 Module monitors disk temperatures from one or more hddtemp daemons.
400 Running `hddtemp` in daemonized mode with access on tcp port
402 It produces one chart **Temperature** with dynamic number of dimensions (one per disk)
414 If no configuration is given, module will attempt to connect to hddtemp daemon on `127.0.0.1:7634` address
420 Module monitors [IPFS](https://ipfs.io) basic information.
422 1. **Bandwidth** in kbits/s
431 Only url to IPFS server is needed.
438 url : 'http://localhost:5001'
445 Module monitor leases database to show all active leases for given pools.
448 * dhcpd leases file MUST BE readable by netdata
449 * pools MUST BE in CIDR format
453 1. **Pools utilization** Aggregate chart for all pools.
454 * utilization in percent
457 * leases (overall number of leases for all pools)
459 3. **Active leases** for every pools
460 * leases (number of active leases in pool)
469 leases_path : '/var/lib/dhcp/dhcpd.leases'
470 pools : '192.168.3.0/24 192.168.4.0/24 192.168.5.0/24'
473 In case of python2 you need to install `py2-ipaddress` to make plugin work.
474 The module will not work If no configuration is given.
481 Module monitor /proc/mdstat
485 1. **Health** Number of failed disks in every array (aggregate chart).
488 * total (number of devices array ideally would have)
489 * inuse (number of devices currently are in use)
491 3. **Current status**
493 * recovery in percent
497 4. **Operation status** (if resync/recovery/reshape/check is active)
499 * speed in megabytes/s
502 No configuration is needed.
508 Memcached monitoring module. Data grabbed from [stats interface](https://github.com/memcached/memcached/wiki/Commands#stats).
510 1. **Network** in kilobytes/s
514 2. **Connections** per second
519 3. **Items** in cluster
523 4. **Evicted and Reclaimed** items
527 5. **GET** requests/s
531 6. **GET rate** rate in requests/s
534 7. **SET rate** rate in requests/s
537 8. **DELETE** requests/s
541 9. **CAS** requests/s
546 10. **Increment** requests/s
550 11. **Decrement** requests/s
554 12. **Touch** requests/s
558 13. **Touch rate** rate in requests/s
572 If no configuration is given, module will attempt to connect to memcached instance on `127.0.0.1:11211` address.
578 Module monitors one or more mysql servers
581 * python library [MySQLdb](https://github.com/PyMySQL/mysqlclient-python) (faster) or [PyMySQL](https://github.com/PyMySQL/PyMySQL) (slower)
583 It will produce following charts (if data is available):
585 1. **Bandwidth** in kbps
589 2. **Queries** in queries/sec
594 3. **Operations** in operations/sec
611 4. **Table Locks** in locks/sec
615 5. **Select Issues** in issues/sec
622 6. **Sort Issues** in issues/sec
629 You can provide, per server, the following:
631 1. username which have access to database (deafults to 'root')
632 2. password (defaults to none)
633 3. mysql my.cnf configuration file
634 4. mysql socket (optional)
635 5. mysql host (ip or hostname)
636 6. mysql port (defaults to 3306)
638 Here is an example for 3 servers:
646 'my.cnf' : '/etc/mysql/my.cnf'
651 pass : 'blablablabla'
652 socket : '/var/run/mysqld/mysqld.sock'
663 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`
669 This module will monitor one or more nginx servers depending on configuration. Servers can be either local or remote.
672 * nginx with configured 'ngx_http_stub_status_module'
673 * 'location /stub_status'
675 Example nginx configuration can be found in 'python.d/nginx.conf'
677 It produces following charts:
679 1. **Active Connections**
682 2. **Requests** in requests/s
685 3. **Active Connections by Status**
690 4. **Connections Rate** in connections/s
696 Needs only `url` to server's `stub_status`
698 Here is an example for local server:
705 url : 'http://localhost/stub_status'
709 Without configuration, module attempts to connect to `http://localhost/stub_status`
715 Module monitors nginx access log and produces only one chart:
717 1. **nginx status codes** in requests/s
725 Sample for two vhosts:
729 path: '/var/log/nginx/access-A.log'
733 path: '/var/log/nginx/access-B.log'
736 When no configuration file is found, module tries to parse `/var/log/nginx/access.log` file.
742 Module monitor openvpn-status log file.
746 * If you are running multiple OpenVPN instances out of the same directory, MAKE SURE TO EDIT DIRECTIVES which create output files
747 so that multiple instances do not overwrite each other's output files.
749 * Make sure NETDATA USER CAN READ openvpn-status.log
751 * Update_every interval MUST MATCH interval on which OpenVPN writes operational status to log file.
755 1. **Users** OpenVPN active users
758 2. **Traffic** OpenVPN overall bandwidth usage in kilobit/s
768 log_path : '/var/log/openvpn-status.log'
775 This module will monitor one or more php-fpm instances depending on configuration.
778 * php-fpm with enabled `status` page
779 * access to `status` page via web server
781 It produces following charts:
783 1. **Active Connections**
788 2. **Requests** in requests/s
797 Needs only `url` to server's `status`
799 Here is an example for local instance:
806 url : 'http://localhost/status'
810 Without configuration, module attempts to connect to `http://localhost/status`
816 Simple module executing `postfix -p` to grab postfix queue.
818 It produces only two charts:
820 1. **Postfix Queue Emails**
823 2. **Postfix Queue Emails Size** in KB
826 Configuration is not needed.
832 Get INFO data from redis instance.
834 Following charts are drawn:
836 1. **Operations** per second
839 2. **Hit rate** in percent
842 3. **Memory utilization** in kilobytes
847 * lines are creates dynamically based on how many databases are there
861 socket : '/var/lib/redis/redis.sock'
869 When no configuration file is found, module tries to connect to TCP/IP socket: `localhost:6379`.
875 System sensors information.
877 Charts are created dynamically.
881 For detailed configuration information please read [`sensors.conf`](https://github.com/firehol/netdata/blob/master/conf.d/python.d/sensors.conf) file.
887 This module will monitor one or more squid instances depending on configuration.
889 It produces following charts:
891 1. **Client Bandwidth** in kilobits/s
896 2. **Client Requests** in requests/s
901 3. **Server Bandwidth** in kilobits/s
905 4. **Server Requests** in requests/s
915 request : 'cache_object://localhost:3128/counters'
920 Without any configuration module will try to autodetect where squid presents its `counters` data
926 Present tomcat containers memory utilization.
930 1. **Requests** per second
933 2. **Volume** in KB/s
940 4. **JVM Free Memory** in MB
948 url : 'http://127.0.0.1:8080/manager/status?XML=true'
949 user : 'tomcat_username'
950 pass : 'secret_tomcat_password'
953 Without configuration, module attempts to connect to `http://localhost:8080/manager/status?XML=true`, without any credentials.
954 So it will probably fail.