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 monitors the usage of CPU idle states.
225 Your kernel needs to have `CONFIG_CPU_IDLE` enabled.
227 It produces one stacked chart per CPU, showing the percentage of time spent in
234 This module provides statistics information from dovecot server.
235 Statistics are taken from dovecot socket by executing `EXPORT global` command.
236 More information about dovecot stats can be found on [project wiki page.](http://wiki2.dovecot.org/Statistics)
239 Dovecot unix socket with R/W permissions for user netdata or dovecot with configured TCP/IP socket.
241 Module gives information with following charts:
249 3. **commands** - number of IMAP commands
256 5. **Context Switches**
260 6. **disk** in bytes/s
264 7. **bytes** in bytes/s
268 8. **number of syscalls** in syscalls/s
272 9. **lookups** - number of lookups per second
276 10. **hits** - number of cache hits
279 11. **attempts** - authorization attemts
283 12. **cache** - cached authorization hits
299 socket : '/var/run/dovecot/stats'
302 If no configuration is given, module will attempt to connect to dovecot using unix socket localized in `/var/run/dovecot/stats`
308 Module monitor elasticsearch performance and health metrics
312 1. **Search performance** charts:
313 * Number of queries, fetches
314 * Time spent on queries, fetches
315 * Query and fetch latency
317 2. **Indexing performance** charts:
318 * Number of documents indexed, index refreshes, flushes
319 * Time spent on indexing, refreshing, flushing
320 * Indexing and flushing latency
322 3. **Memory usage and garbace collection** charts:
323 * JVM heap currently in use, commited
324 * Count of garbage collections
325 * Time spent on garbage collections
327 4. **Host metrics** charts:
328 * Available file descriptors in percent
329 * Opened HTTP connections
330 * Cluster communication transport metrics
332 5. **Queues and rejections** charts:
333 * Number of queued/rejected threads in thread pool
335 6. **Fielddata cache** charts:
336 * Fielddata cache size
337 * Fielddata evictions and circuit breaker tripped count
339 7. **Cluster health API** charts:
341 * Nodes and tasks statistics
344 8. **Cluster stats API** charts:
346 * Query cache statistics
349 * Indices and shards statistics
357 host : 'ipaddress' # Server ip address or hostname
358 port : 'password' # Port on which elasticsearch listed
359 cluster_health : True/False # Calls to cluster health elasticsearch API. Enabled by default.
360 cluster_stats : True/False # Calls to cluster stats elasticsearch API. Enabled by default.
363 If no configuration is given, module will fail to run.
369 Simple module executing `exim -bpc` to grab exim queue.
370 This command can take a lot of time to finish its execution thus it is not recommended to run it every second.
372 It produces only one chart:
374 1. **Exim Queue Emails**
377 Configuration is not needed.
383 Module monitor fail2ban log file to show all bans for all active jails
386 * fail2ban.log file MUST BE readable by netdata (A good idea is to add **create 0640 root netdata** to fail2ban conf at logrotate.d)
388 It produces one chart with multiple lines (one line per jail)
396 log_path: '/var/log/fail2ban.log'
397 conf_path: '/etc/fail2ban/jail.local'
398 exclude: 'dropbear apache'
400 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`.
401 If conf file is not found default jail is `ssh`.
407 Uses the `radclient` command to provide freeradius statistics. It is not recommended to run it every second.
411 1. **Authentication counters:**
414 * auth-dropped-requests
415 * auth-duplicate-requests
416 * auth-invalid-requests
417 * auth-malformed-requests
420 2. **Accounting counters:** [optional]
421 * accounting-requests
422 * accounting-responses
423 * acct-dropped-requests
424 * acct-duplicate-requests
425 * acct-invalid-requests
426 * acct-malformed-requests
429 3. **Proxy authentication counters:** [optional]
430 * proxy-access-accepts
431 * proxy-access-rejects
432 * proxy-auth-dropped-requests
433 * proxy-auth-duplicate-requests
434 * proxy-auth-invalid-requests
435 * proxy-auth-malformed-requests
436 * proxy-auth-unknown-types
438 4. **Proxy accounting counters:** [optional]
439 * proxy-accounting-requests
440 * proxy-accounting-responses
441 * proxy-acct-dropped-requests
442 * proxy-acct-duplicate-requests
443 * proxy-acct-invalid-requests
444 * proxy-acct-malformed-requests
445 * proxy-acct-unknown-typesa
456 secret : 'adminsecret'
457 acct : False # Freeradius accounting statistics.
458 proxy_auth : False # Freeradius proxy authentication statistics.
459 proxy_acct : False # Freeradius proxy accounting statistics.
462 **Freeradius server configuration:**
464 The configuration for the status server is automatically created in the sites-available directory.
465 By default, server is enabled and can be queried from every client.
466 FreeRADIUS will only respond to status-server messages, if the status-server virtual server has been enabled.
468 To do this, create a link from the sites-enabled directory to the status file in the sites-available directory:
470 * ln -s ../sites-available/status status
472 and restart/reload your FREERADIUS server.
478 Module monitors frontend and backend metrics such as bytes in, bytes out, sessions current, sessions in queue current.
479 And health metrics such as backend servers status (server check should be used).
481 Plugin can obtain data from url **OR** unix socket.
484 Socket MUST be readable AND writable by netdata user.
488 1. **Frontend** family charts
492 * Sessions in queue current
494 2. **Backend** family charts
498 * Sessions in queue current
501 * number of failed servers for every backend (in DOWN state)
510 user : 'username' # ONLY IF stats auth is used
511 pass : 'password' # # ONLY IF stats auth is used
512 url : 'http://ip.address:port/url;csv;norefresh'
519 socket : 'path/to/haproxy/sock'
522 If no configuration is given, module will fail to run.
528 Module monitors disk temperatures from one or more hddtemp daemons.
531 Running `hddtemp` in daemonized mode with access on tcp port
533 It produces one chart **Temperature** with dynamic number of dimensions (one per disk)
545 If no configuration is given, module will attempt to connect to hddtemp daemon on `127.0.0.1:7634` address
551 Module monitors [IPFS](https://ipfs.io) basic information.
553 1. **Bandwidth** in kbits/s
562 Only url to IPFS server is needed.
569 url : 'http://localhost:5001'
576 Module monitor leases database to show all active leases for given pools.
579 * dhcpd leases file MUST BE readable by netdata
580 * pools MUST BE in CIDR format
584 1. **Pools utilization** Aggregate chart for all pools.
585 * utilization in percent
588 * leases (overall number of leases for all pools)
590 3. **Active leases** for every pools
591 * leases (number of active leases in pool)
600 leases_path : '/var/lib/dhcp/dhcpd.leases'
601 pools : '192.168.3.0/24 192.168.4.0/24 192.168.5.0/24'
604 In case of python2 you need to install `py2-ipaddress` to make plugin work.
605 The module will not work If no configuration is given.
612 Module monitor /proc/mdstat
616 1. **Health** Number of failed disks in every array (aggregate chart).
619 * total (number of devices array ideally would have)
620 * inuse (number of devices currently are in use)
622 3. **Current status**
624 * recovery in percent
628 4. **Operation status** (if resync/recovery/reshape/check is active)
630 * speed in megabytes/s
633 No configuration is needed.
639 Memcached monitoring module. Data grabbed from [stats interface](https://github.com/memcached/memcached/wiki/Commands#stats).
641 1. **Network** in kilobytes/s
645 2. **Connections** per second
650 3. **Items** in cluster
654 4. **Evicted and Reclaimed** items
658 5. **GET** requests/s
662 6. **GET rate** rate in requests/s
665 7. **SET rate** rate in requests/s
668 8. **DELETE** requests/s
672 9. **CAS** requests/s
677 10. **Increment** requests/s
681 11. **Decrement** requests/s
685 12. **Touch** requests/s
689 13. **Touch rate** rate in requests/s
703 If no configuration is given, module will attempt to connect to memcached instance on `127.0.0.1:11211` address.
709 Module monitors one or more mysql servers
712 * python library [MySQLdb](https://github.com/PyMySQL/mysqlclient-python) (faster) or [PyMySQL](https://github.com/PyMySQL/PyMySQL) (slower)
714 It will produce following charts (if data is available):
716 1. **Bandwidth** in kbps
720 2. **Queries** in queries/sec
725 3. **Operations** in operations/sec
742 4. **Table Locks** in locks/sec
746 5. **Select Issues** in issues/sec
753 6. **Sort Issues** in issues/sec
760 You can provide, per server, the following:
762 1. username which have access to database (deafults to 'root')
763 2. password (defaults to none)
764 3. mysql my.cnf configuration file
765 4. mysql socket (optional)
766 5. mysql host (ip or hostname)
767 6. mysql port (defaults to 3306)
769 Here is an example for 3 servers:
777 'my.cnf' : '/etc/mysql/my.cnf'
782 pass : 'blablablabla'
783 socket : '/var/run/mysqld/mysqld.sock'
794 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`
800 This module will monitor one or more nginx servers depending on configuration. Servers can be either local or remote.
803 * nginx with configured 'ngx_http_stub_status_module'
804 * 'location /stub_status'
806 Example nginx configuration can be found in 'python.d/nginx.conf'
808 It produces following charts:
810 1. **Active Connections**
813 2. **Requests** in requests/s
816 3. **Active Connections by Status**
821 4. **Connections Rate** in connections/s
827 Needs only `url` to server's `stub_status`
829 Here is an example for local server:
836 url : 'http://localhost/stub_status'
840 Without configuration, module attempts to connect to `http://localhost/stub_status`
846 Module monitors nginx access log and produces only one chart:
848 1. **nginx status codes** in requests/s
856 Sample for two vhosts:
860 path: '/var/log/nginx/access-A.log'
864 path: '/var/log/nginx/access-B.log'
867 When no configuration file is found, module tries to parse `/var/log/nginx/access.log` file.
873 Module monitor openvpn-status log file.
877 * If you are running multiple OpenVPN instances out of the same directory, MAKE SURE TO EDIT DIRECTIVES which create output files
878 so that multiple instances do not overwrite each other's output files.
880 * Make sure NETDATA USER CAN READ openvpn-status.log
882 * Update_every interval MUST MATCH interval on which OpenVPN writes operational status to log file.
886 1. **Users** OpenVPN active users
889 2. **Traffic** OpenVPN overall bandwidth usage in kilobit/s
899 log_path : '/var/log/openvpn-status.log'
906 This module will monitor one or more php-fpm instances depending on configuration.
909 * php-fpm with enabled `status` page
910 * access to `status` page via web server
912 It produces following charts:
914 1. **Active Connections**
919 2. **Requests** in requests/s
928 Needs only `url` to server's `status`
930 Here is an example for local instance:
937 url : 'http://localhost/status'
941 Without configuration, module attempts to connect to `http://localhost/status`
947 Simple module executing `postfix -p` to grab postfix queue.
949 It produces only two charts:
951 1. **Postfix Queue Emails**
954 2. **Postfix Queue Emails Size** in KB
957 Configuration is not needed.
963 Get INFO data from redis instance.
965 Following charts are drawn:
967 1. **Operations** per second
970 2. **Hit rate** in percent
973 3. **Memory utilization** in kilobytes
978 * lines are creates dynamically based on how many databases are there
992 socket : '/var/lib/redis/redis.sock'
1000 When no configuration file is found, module tries to connect to TCP/IP socket: `localhost:6379`.
1006 System sensors information.
1008 Charts are created dynamically.
1012 For detailed configuration information please read [`sensors.conf`](https://github.com/firehol/netdata/blob/master/conf.d/python.d/sensors.conf) file.
1018 This module will monitor one or more squid instances depending on configuration.
1020 It produces following charts:
1022 1. **Client Bandwidth** in kilobits/s
1027 2. **Client Requests** in requests/s
1032 3. **Server Bandwidth** in kilobits/s
1036 4. **Server Requests** in requests/s
1046 request : 'cache_object://localhost:3128/counters'
1051 Without any configuration module will try to autodetect where squid presents its `counters` data
1057 Present tomcat containers memory utilization.
1061 1. **Requests** per second
1064 2. **Volume** in KB/s
1071 4. **JVM Free Memory** in MB
1079 url : 'http://127.0.0.1:8080/manager/status?XML=true'
1080 user : 'tomcat_username'
1081 pass : 'secret_tomcat_password'
1084 Without configuration, module attempts to connect to `http://localhost:8080/manager/status?XML=true`, without any credentials.
1085 So it will probably fail.
1091 Module uses the `varnishstat` command to provide varnish cache statistics.
1095 1. **Client metrics**
1098 * good client requests received
1100 2. **All history hit rate ratio**
1101 * cache hits in percent
1102 * cache miss in percent
1103 * cache hits for pass percent
1105 3. **Curent poll hit rate ratio**
1106 * cache hits in percent
1107 * cache miss in percent
1108 * cache hits for pass percent
1110 4. **Thread-related metrics** (only for varnish version 4+)
1111 * total number of threads
1113 * threads creation failed
1115 * length os session queue
1116 * sessions queued for thread
1118 5. **Backend health**
1119 * backend conn. success
1120 * backend conn. not attempted
1121 * backend conn. too many
1122 * backend conn. failures
1123 * backend conn. reuses
1124 * backend conn. recycles
1125 * backend conn. retry
1126 * backend requests made
1129 * memory available in megabytes
1130 * memory allocated in megabytes
1132 7. **Problems summary**
1134 * session accept failures
1135 * session pipe overflow
1136 * backend conn. not attempted
1137 * fetch failed (all causes)
1138 * backend conn. too many
1141 * length of session queue
1142 * HTTP header overflows
1144 * ESI parse warnings
1147 * varnish instance uptime in seconds
1151 No configuration is needed.