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 monitors the usage of CPU idle states.
217 Your kernel needs to have `CONFIG_CPU_IDLE` enabled.
219 It produces one stacked chart per CPU, showing the percentage of time spent in
226 This module provides statistics information from dovecot server.
227 Statistics are taken from dovecot socket by executing `EXPORT global` command.
228 More information about dovecot stats can be found on [project wiki page.](http://wiki2.dovecot.org/Statistics)
231 Dovecot unix socket with R/W permissions for user netdata or dovecot with configured TCP/IP socket.
233 Module gives information with following charts:
241 3. **commands** - number of IMAP commands
248 5. **Context Switches**
252 6. **disk** in bytes/s
256 7. **bytes** in bytes/s
260 8. **number of syscalls** in syscalls/s
264 9. **lookups** - number of lookups per second
268 10. **hits** - number of cache hits
271 11. **attempts** - authorization attemts
275 12. **cache** - cached authorization hits
291 socket : '/var/run/dovecot/stats'
294 If no configuration is given, module will attempt to connect to dovecot using unix socket localized in `/var/run/dovecot/stats`
300 Simple module executing `exim -bpc` to grab exim queue.
301 This command can take a lot of time to finish its execution thus it is not recommended to run it every second.
303 It produces only one chart:
305 1. **Exim Queue Emails**
308 Configuration is not needed.
314 Module monitor fail2ban log file to show all bans for all active jails
317 * fail2ban.log file MUST BE readable by netdata (A good idea is to add **create 0640 root netdata** to fail2ban conf at logrotate.d)
319 It produces one chart with multiple lines (one line per jail)
327 log_path: '/var/log/fail2ban.log'
328 conf_path: '/etc/fail2ban/jail.local'
329 exclude: 'dropbear apache'
331 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`.
332 If conf file is not found default jail is `ssh`.
338 Uses the `radclient` command to provide freeradius statistics. It is not recommended to run it every second.
342 1. **Authentication counters:**
345 * auth-dropped-requests
346 * auth-duplicate-requests
347 * auth-invalid-requests
348 * auth-malformed-requests
351 2. **Accounting counters:** [optional]
352 * accounting-requests
353 * accounting-responses
354 * acct-dropped-requests
355 * acct-duplicate-requests
356 * acct-invalid-requests
357 * acct-malformed-requests
360 3. **Proxy authentication counters:** [optional]
361 * proxy-access-accepts
362 * proxy-access-rejects
363 * proxy-auth-dropped-requests
364 * proxy-auth-duplicate-requests
365 * proxy-auth-invalid-requests
366 * proxy-auth-malformed-requests
367 * proxy-auth-unknown-types
369 4. **Proxy accounting counters:** [optional]
370 * proxy-accounting-requests
371 * proxy-accounting-responses
372 * proxy-acct-dropped-requests
373 * proxy-acct-duplicate-requests
374 * proxy-acct-invalid-requests
375 * proxy-acct-malformed-requests
376 * proxy-acct-unknown-typesa
387 secret : 'adminsecret'
388 acct : False # Freeradius accounting statistics.
389 proxy_auth : False # Freeradius proxy authentication statistics.
390 proxy_acct : False # Freeradius proxy accounting statistics.
393 **Freeradius server configuration:**
395 The configuration for the status server is automatically created in the sites-available directory.
396 By default, server is enabled and can be queried from every client.
397 FreeRADIUS will only respond to status-server messages, if the status-server virtual server has been enabled.
399 To do this, create a link from the sites-enabled directory to the status file in the sites-available directory:
401 * ln -s ../sites-available/status status
403 and restart/reload your FREERADIUS server.
409 Module monitors disk temperatures from one or more hddtemp daemons.
412 Running `hddtemp` in daemonized mode with access on tcp port
414 It produces one chart **Temperature** with dynamic number of dimensions (one per disk)
426 If no configuration is given, module will attempt to connect to hddtemp daemon on `127.0.0.1:7634` address
432 Module monitors [IPFS](https://ipfs.io) basic information.
434 1. **Bandwidth** in kbits/s
443 Only url to IPFS server is needed.
450 url : 'http://localhost:5001'
457 Module monitor leases database to show all active leases for given pools.
460 * dhcpd leases file MUST BE readable by netdata
461 * pools MUST BE in CIDR format
465 1. **Pools utilization** Aggregate chart for all pools.
466 * utilization in percent
469 * leases (overall number of leases for all pools)
471 3. **Active leases** for every pools
472 * leases (number of active leases in pool)
481 leases_path : '/var/lib/dhcp/dhcpd.leases'
482 pools : '192.168.3.0/24 192.168.4.0/24 192.168.5.0/24'
485 In case of python2 you need to install `py2-ipaddress` to make plugin work.
486 The module will not work If no configuration is given.
493 Module monitor /proc/mdstat
497 1. **Health** Number of failed disks in every array (aggregate chart).
500 * total (number of devices array ideally would have)
501 * inuse (number of devices currently are in use)
503 3. **Current status**
505 * recovery in percent
509 4. **Operation status** (if resync/recovery/reshape/check is active)
511 * speed in megabytes/s
514 No configuration is needed.
520 Memcached monitoring module. Data grabbed from [stats interface](https://github.com/memcached/memcached/wiki/Commands#stats).
522 1. **Network** in kilobytes/s
526 2. **Connections** per second
531 3. **Items** in cluster
535 4. **Evicted and Reclaimed** items
539 5. **GET** requests/s
543 6. **GET rate** rate in requests/s
546 7. **SET rate** rate in requests/s
549 8. **DELETE** requests/s
553 9. **CAS** requests/s
558 10. **Increment** requests/s
562 11. **Decrement** requests/s
566 12. **Touch** requests/s
570 13. **Touch rate** rate in requests/s
584 If no configuration is given, module will attempt to connect to memcached instance on `127.0.0.1:11211` address.
590 Module monitors one or more mysql servers
593 * python library [MySQLdb](https://github.com/PyMySQL/mysqlclient-python) (faster) or [PyMySQL](https://github.com/PyMySQL/PyMySQL) (slower)
595 It will produce following charts (if data is available):
597 1. **Bandwidth** in kbps
601 2. **Queries** in queries/sec
606 3. **Operations** in operations/sec
623 4. **Table Locks** in locks/sec
627 5. **Select Issues** in issues/sec
634 6. **Sort Issues** in issues/sec
641 You can provide, per server, the following:
643 1. username which have access to database (deafults to 'root')
644 2. password (defaults to none)
645 3. mysql my.cnf configuration file
646 4. mysql socket (optional)
647 5. mysql host (ip or hostname)
648 6. mysql port (defaults to 3306)
650 Here is an example for 3 servers:
658 'my.cnf' : '/etc/mysql/my.cnf'
663 pass : 'blablablabla'
664 socket : '/var/run/mysqld/mysqld.sock'
675 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`
681 This module will monitor one or more nginx servers depending on configuration. Servers can be either local or remote.
684 * nginx with configured 'ngx_http_stub_status_module'
685 * 'location /stub_status'
687 Example nginx configuration can be found in 'python.d/nginx.conf'
689 It produces following charts:
691 1. **Active Connections**
694 2. **Requests** in requests/s
697 3. **Active Connections by Status**
702 4. **Connections Rate** in connections/s
708 Needs only `url` to server's `stub_status`
710 Here is an example for local server:
717 url : 'http://localhost/stub_status'
721 Without configuration, module attempts to connect to `http://localhost/stub_status`
727 Module monitors nginx access log and produces only one chart:
729 1. **nginx status codes** in requests/s
737 Sample for two vhosts:
741 path: '/var/log/nginx/access-A.log'
745 path: '/var/log/nginx/access-B.log'
748 When no configuration file is found, module tries to parse `/var/log/nginx/access.log` file.
754 Module monitor openvpn-status log file.
758 * If you are running multiple OpenVPN instances out of the same directory, MAKE SURE TO EDIT DIRECTIVES which create output files
759 so that multiple instances do not overwrite each other's output files.
761 * Make sure NETDATA USER CAN READ openvpn-status.log
763 * Update_every interval MUST MATCH interval on which OpenVPN writes operational status to log file.
767 1. **Users** OpenVPN active users
770 2. **Traffic** OpenVPN overall bandwidth usage in kilobit/s
780 log_path : '/var/log/openvpn-status.log'
787 This module will monitor one or more php-fpm instances depending on configuration.
790 * php-fpm with enabled `status` page
791 * access to `status` page via web server
793 It produces following charts:
795 1. **Active Connections**
800 2. **Requests** in requests/s
809 Needs only `url` to server's `status`
811 Here is an example for local instance:
818 url : 'http://localhost/status'
822 Without configuration, module attempts to connect to `http://localhost/status`
828 Simple module executing `postfix -p` to grab postfix queue.
830 It produces only two charts:
832 1. **Postfix Queue Emails**
835 2. **Postfix Queue Emails Size** in KB
838 Configuration is not needed.
844 Get INFO data from redis instance.
846 Following charts are drawn:
848 1. **Operations** per second
851 2. **Hit rate** in percent
854 3. **Memory utilization** in kilobytes
859 * lines are creates dynamically based on how many databases are there
873 socket : '/var/lib/redis/redis.sock'
881 When no configuration file is found, module tries to connect to TCP/IP socket: `localhost:6379`.
887 System sensors information.
889 Charts are created dynamically.
893 For detailed configuration information please read [`sensors.conf`](https://github.com/firehol/netdata/blob/master/conf.d/python.d/sensors.conf) file.
899 This module will monitor one or more squid instances depending on configuration.
901 It produces following charts:
903 1. **Client Bandwidth** in kilobits/s
908 2. **Client Requests** in requests/s
913 3. **Server Bandwidth** in kilobits/s
917 4. **Server Requests** in requests/s
927 request : 'cache_object://localhost:3128/counters'
932 Without any configuration module will try to autodetect where squid presents its `counters` data
938 Present tomcat containers memory utilization.
942 1. **Requests** per second
945 2. **Volume** in KB/s
952 4. **JVM Free Memory** in MB
960 url : 'http://127.0.0.1:8080/manager/status?XML=true'
961 user : 'tomcat_username'
962 pass : 'secret_tomcat_password'
965 Without configuration, module attempts to connect to `http://localhost:8080/manager/status?XML=true`, without any credentials.
966 So it will probably fail.