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`
191 This module shows the current CPU frequency as set by the cpufreq kernel
195 You need to have `CONFIG_CPU_FREQ` and (optionally) `CONFIG_CPU_FREQ_STAT`
196 enabled in your kernel.
198 This module tries to read from one of two possible locations. On
199 initialization, it tries to read the `time_in_state` files provided by
200 cpufreq\_stats. If this file does not exist, or doesn't contain valid data, it
201 falls back to using the more inaccurate `scaling_cur_freq` file (which only
202 represents the **current** CPU frequency, and doesn't account for any state
203 changes which happen between updates).
205 It produces one chart with multiple lines (one line per core).
212 sys_dir: "/sys/devices"
215 If no configuration is given, module will search for cpufreq files in `/sys/devices` directory.
216 Directory is also prefixed with `NETDATA_HOST_PREFIX` if specified.
222 This module provides statistics information from dovecot server.
223 Statistics are taken from dovecot socket by executing `EXPORT global` command.
224 More information about dovecot stats can be found on [project wiki page.](http://wiki2.dovecot.org/Statistics)
227 Dovecot unix socket with R/W permissions for user netdata or dovecot with configured TCP/IP socket.
229 Module gives information with following charts:
237 3. **commands** - number of IMAP commands
244 5. **Context Switches**
248 6. **disk** in bytes/s
252 7. **bytes** in bytes/s
256 8. **number of syscalls** in syscalls/s
260 9. **lookups** - number of lookups per second
264 10. **hits** - number of cache hits
267 11. **attempts** - authorization attemts
271 12. **cache** - cached authorization hits
287 socket : '/var/run/dovecot/stats'
290 If no configuration is given, module will attempt to connect to dovecot using unix socket localized in `/var/run/dovecot/stats`
296 Simple module executing `exim -bpc` to grab exim queue.
297 This command can take a lot of time to finish its execution thus it is not recommended to run it every second.
299 It produces only one chart:
301 1. **Exim Queue Emails**
304 Configuration is not needed.
310 Module monitor fail2ban log file to show all bans for all active jails
313 * fail2ban.log file MUST BE readable by netdata (A good idea is to add **create 0640 root netdata** to fail2ban conf at logrotate.d)
315 It produces one chart with multiple lines (one line per jail)
323 log_path: '/var/log/fail2ban.log'
324 conf_path: '/etc/fail2ban/jail.local'
325 exclude: 'dropbear apache'
327 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`.
328 If conf file is not found default jail is `ssh`.
334 Uses the `radclient` command to provide freeradius statistics. It is not recommended to run it every second.
338 1. **Authentication counters:**
341 * auth-dropped-requests
342 * auth-duplicate-requests
343 * auth-invalid-requests
344 * auth-malformed-requests
347 2. **Accounting counters:** [optional]
348 * accounting-requests
349 * accounting-responses
350 * acct-dropped-requests
351 * acct-duplicate-requests
352 * acct-invalid-requests
353 * acct-malformed-requests
356 3. **Proxy authentication counters:** [optional]
357 * proxy-access-accepts
358 * proxy-access-rejects
359 * proxy-auth-dropped-requests
360 * proxy-auth-duplicate-requests
361 * proxy-auth-invalid-requests
362 * proxy-auth-malformed-requests
363 * proxy-auth-unknown-types
365 4. **Proxy accounting counters:** [optional]
366 * proxy-accounting-requests
367 * proxy-accounting-responses
368 * proxy-acct-dropped-requests
369 * proxy-acct-duplicate-requests
370 * proxy-acct-invalid-requests
371 * proxy-acct-malformed-requests
372 * proxy-acct-unknown-typesa
383 secret : 'adminsecret'
384 acct : False # Freeradius accounting statistics.
385 proxy_auth : False # Freeradius proxy authentication statistics.
386 proxy_acct : False # Freeradius proxy accounting statistics.
389 **Freeradius server configuration:**
391 The configuration for the status server is automatically created in the sites-available directory.
392 By default, server is enabled and can be queried from every client.
393 FreeRADIUS will only respond to status-server messages, if the status-server virtual server has been enabled.
395 To do this, create a link from the sites-enabled directory to the status file in the sites-available directory:
397 * ln -s ../sites-available/status status
399 and restart/reload your FREERADIUS server.
405 Module monitors disk temperatures from one or more hddtemp daemons.
408 Running `hddtemp` in daemonized mode with access on tcp port
410 It produces one chart **Temperature** with dynamic number of dimensions (one per disk)
422 If no configuration is given, module will attempt to connect to hddtemp daemon on `127.0.0.1:7634` address
428 Module monitors [IPFS](https://ipfs.io) basic information.
430 1. **Bandwidth** in kbits/s
439 Only url to IPFS server is needed.
446 url : 'http://localhost:5001'
453 Module monitor leases database to show all active leases for given pools.
456 * dhcpd leases file MUST BE readable by netdata
457 * pools MUST BE in CIDR format
461 1. **Pools utilization** Aggregate chart for all pools.
462 * utilization in percent
465 * leases (overall number of leases for all pools)
467 3. **Active leases** for every pools
468 * leases (number of active leases in pool)
477 leases_path : '/var/lib/dhcp/dhcpd.leases'
478 pools : '192.168.3.0/24 192.168.4.0/24 192.168.5.0/24'
481 In case of python2 you need to install `py2-ipaddress` to make plugin work.
482 The module will not work If no configuration is given.
489 Module monitor /proc/mdstat
493 1. **Health** Number of failed disks in every array (aggregate chart).
496 * total (number of devices array ideally would have)
497 * inuse (number of devices currently are in use)
499 3. **Current status**
501 * recovery in percent
505 4. **Operation status** (if resync/recovery/reshape/check is active)
507 * speed in megabytes/s
510 No configuration is needed.
516 Memcached monitoring module. Data grabbed from [stats interface](https://github.com/memcached/memcached/wiki/Commands#stats).
518 1. **Network** in kilobytes/s
522 2. **Connections** per second
527 3. **Items** in cluster
531 4. **Evicted and Reclaimed** items
535 5. **GET** requests/s
539 6. **GET rate** rate in requests/s
542 7. **SET rate** rate in requests/s
545 8. **DELETE** requests/s
549 9. **CAS** requests/s
554 10. **Increment** requests/s
558 11. **Decrement** requests/s
562 12. **Touch** requests/s
566 13. **Touch rate** rate in requests/s
580 If no configuration is given, module will attempt to connect to memcached instance on `127.0.0.1:11211` address.
586 Module monitors one or more mysql servers
589 * python library [MySQLdb](https://github.com/PyMySQL/mysqlclient-python) (faster) or [PyMySQL](https://github.com/PyMySQL/PyMySQL) (slower)
591 It will produce following charts (if data is available):
593 1. **Bandwidth** in kbps
597 2. **Queries** in queries/sec
602 3. **Operations** in operations/sec
619 4. **Table Locks** in locks/sec
623 5. **Select Issues** in issues/sec
630 6. **Sort Issues** in issues/sec
637 You can provide, per server, the following:
639 1. username which have access to database (deafults to 'root')
640 2. password (defaults to none)
641 3. mysql my.cnf configuration file
642 4. mysql socket (optional)
643 5. mysql host (ip or hostname)
644 6. mysql port (defaults to 3306)
646 Here is an example for 3 servers:
654 'my.cnf' : '/etc/mysql/my.cnf'
659 pass : 'blablablabla'
660 socket : '/var/run/mysqld/mysqld.sock'
671 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`
677 This module will monitor one or more nginx servers depending on configuration. Servers can be either local or remote.
680 * nginx with configured 'ngx_http_stub_status_module'
681 * 'location /stub_status'
683 Example nginx configuration can be found in 'python.d/nginx.conf'
685 It produces following charts:
687 1. **Active Connections**
690 2. **Requests** in requests/s
693 3. **Active Connections by Status**
698 4. **Connections Rate** in connections/s
704 Needs only `url` to server's `stub_status`
706 Here is an example for local server:
713 url : 'http://localhost/stub_status'
717 Without configuration, module attempts to connect to `http://localhost/stub_status`
723 Module monitors nginx access log and produces only one chart:
725 1. **nginx status codes** in requests/s
733 Sample for two vhosts:
737 path: '/var/log/nginx/access-A.log'
741 path: '/var/log/nginx/access-B.log'
744 When no configuration file is found, module tries to parse `/var/log/nginx/access.log` file.
750 Module monitor openvpn-status log file.
754 * If you are running multiple OpenVPN instances out of the same directory, MAKE SURE TO EDIT DIRECTIVES which create output files
755 so that multiple instances do not overwrite each other's output files.
757 * Make sure NETDATA USER CAN READ openvpn-status.log
759 * Update_every interval MUST MATCH interval on which OpenVPN writes operational status to log file.
763 1. **Users** OpenVPN active users
766 2. **Traffic** OpenVPN overall bandwidth usage in kilobit/s
776 log_path : '/var/log/openvpn-status.log'
783 This module will monitor one or more php-fpm instances depending on configuration.
786 * php-fpm with enabled `status` page
787 * access to `status` page via web server
789 It produces following charts:
791 1. **Active Connections**
796 2. **Requests** in requests/s
805 Needs only `url` to server's `status`
807 Here is an example for local instance:
814 url : 'http://localhost/status'
818 Without configuration, module attempts to connect to `http://localhost/status`
824 Simple module executing `postfix -p` to grab postfix queue.
826 It produces only two charts:
828 1. **Postfix Queue Emails**
831 2. **Postfix Queue Emails Size** in KB
834 Configuration is not needed.
840 Get INFO data from redis instance.
842 Following charts are drawn:
844 1. **Operations** per second
847 2. **Hit rate** in percent
850 3. **Memory utilization** in kilobytes
855 * lines are creates dynamically based on how many databases are there
869 socket : '/var/lib/redis/redis.sock'
877 When no configuration file is found, module tries to connect to TCP/IP socket: `localhost:6379`.
883 System sensors information.
885 Charts are created dynamically.
889 For detailed configuration information please read [`sensors.conf`](https://github.com/firehol/netdata/blob/master/conf.d/python.d/sensors.conf) file.
895 This module will monitor one or more squid instances depending on configuration.
897 It produces following charts:
899 1. **Client Bandwidth** in kilobits/s
904 2. **Client Requests** in requests/s
909 3. **Server Bandwidth** in kilobits/s
913 4. **Server Requests** in requests/s
923 request : 'cache_object://localhost:3128/counters'
928 Without any configuration module will try to autodetect where squid presents its `counters` data
934 Present tomcat containers memory utilization.
938 1. **Requests** per second
941 2. **Volume** in KB/s
948 4. **JVM Free Memory** in MB
956 url : 'http://127.0.0.1:8080/manager/status?XML=true'
957 user : 'tomcat_username'
958 pass : 'secret_tomcat_password'
961 Without configuration, module attempts to connect to `http://localhost:8080/manager/status?XML=true`, without any credentials.
962 So it will probably fail.