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
311 * python `requests` package.
313 You need to install it manually. (python-requests or python3-requests depending on the version of python).
318 1. **Search performance** charts:
319 * Number of queries, fetches
320 * Time spent on queries, fetches
321 * Query and fetch latency
323 2. **Indexing performance** charts:
324 * Number of documents indexed, index refreshes, flushes
325 * Time spent on indexing, refreshing, flushing
326 * Indexing and flushing latency
328 3. **Memory usage and garbace collection** charts:
329 * JVM heap currently in use, commited
330 * Count of garbage collections
331 * Time spent on garbage collections
333 4. **Host metrics** charts:
334 * Available file descriptors in percent
335 * Opened HTTP connections
336 * Cluster communication transport metrics
338 5. **Queues and rejections** charts:
339 * Number of queued/rejected threads in thread pool
341 6. **Fielddata cache** charts:
342 * Fielddata cache size
343 * Fielddata evictions and circuit breaker tripped count
345 7. **Cluster health API** charts:
347 * Nodes and tasks statistics
350 8. **Cluster stats API** charts:
352 * Query cache statistics
355 * Indices and shards statistics
363 host : 'ipaddress' # Server ip address or hostname
364 port : 'password' # Port on which elasticsearch listed
365 cluster_health : True/False # Calls to cluster health elasticsearch API. Enabled by default.
366 cluster_stats : True/False # Calls to cluster stats elasticsearch API. Enabled by default.
369 If no configuration is given, module will fail to run.
375 Simple module executing `exim -bpc` to grab exim queue.
376 This command can take a lot of time to finish its execution thus it is not recommended to run it every second.
378 It produces only one chart:
380 1. **Exim Queue Emails**
383 Configuration is not needed.
389 Module monitor fail2ban log file to show all bans for all active jails
392 * fail2ban.log file MUST BE readable by netdata (A good idea is to add **create 0640 root netdata** to fail2ban conf at logrotate.d)
394 It produces one chart with multiple lines (one line per jail)
402 log_path: '/var/log/fail2ban.log'
403 conf_path: '/etc/fail2ban/jail.local'
404 exclude: 'dropbear apache'
406 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`.
407 If conf file is not found default jail is `ssh`.
413 Uses the `radclient` command to provide freeradius statistics. It is not recommended to run it every second.
417 1. **Authentication counters:**
420 * auth-dropped-requests
421 * auth-duplicate-requests
422 * auth-invalid-requests
423 * auth-malformed-requests
426 2. **Accounting counters:** [optional]
427 * accounting-requests
428 * accounting-responses
429 * acct-dropped-requests
430 * acct-duplicate-requests
431 * acct-invalid-requests
432 * acct-malformed-requests
435 3. **Proxy authentication counters:** [optional]
436 * proxy-access-accepts
437 * proxy-access-rejects
438 * proxy-auth-dropped-requests
439 * proxy-auth-duplicate-requests
440 * proxy-auth-invalid-requests
441 * proxy-auth-malformed-requests
442 * proxy-auth-unknown-types
444 4. **Proxy accounting counters:** [optional]
445 * proxy-accounting-requests
446 * proxy-accounting-responses
447 * proxy-acct-dropped-requests
448 * proxy-acct-duplicate-requests
449 * proxy-acct-invalid-requests
450 * proxy-acct-malformed-requests
451 * proxy-acct-unknown-typesa
462 secret : 'adminsecret'
463 acct : False # Freeradius accounting statistics.
464 proxy_auth : False # Freeradius proxy authentication statistics.
465 proxy_acct : False # Freeradius proxy accounting statistics.
468 **Freeradius server configuration:**
470 The configuration for the status server is automatically created in the sites-available directory.
471 By default, server is enabled and can be queried from every client.
472 FreeRADIUS will only respond to status-server messages, if the status-server virtual server has been enabled.
474 To do this, create a link from the sites-enabled directory to the status file in the sites-available directory:
476 * ln -s ../sites-available/status status
478 and restart/reload your FREERADIUS server.
484 Module monitors frontend and backend metrics such as bytes in, bytes out, sessions current, sessions in queue current.
485 And health metrics such as backend servers status (server check should be used).
487 Plugin can obtain data from url **OR** unix socket.
490 Socket MUST be readable AND writable by netdata user.
494 1. **Frontend** family charts
498 * Sessions in queue current
500 2. **Backend** family charts
504 * Sessions in queue current
507 * number of failed servers for every backend (in DOWN state)
516 user : 'username' # ONLY IF stats auth is used
517 pass : 'password' # # ONLY IF stats auth is used
518 url : 'http://ip.address:port/url;csv;norefresh'
525 socket : 'path/to/haproxy/sock'
528 If no configuration is given, module will fail to run.
534 Module monitors disk temperatures from one or more hddtemp daemons.
537 Running `hddtemp` in daemonized mode with access on tcp port
539 It produces one chart **Temperature** with dynamic number of dimensions (one per disk)
551 If no configuration is given, module will attempt to connect to hddtemp daemon on `127.0.0.1:7634` address
557 Module monitors [IPFS](https://ipfs.io) basic information.
559 1. **Bandwidth** in kbits/s
568 Only url to IPFS server is needed.
575 url : 'http://localhost:5001'
582 Module monitor leases database to show all active leases for given pools.
585 * dhcpd leases file MUST BE readable by netdata
586 * pools MUST BE in CIDR format
590 1. **Pools utilization** Aggregate chart for all pools.
591 * utilization in percent
594 * leases (overall number of leases for all pools)
596 3. **Active leases** for every pools
597 * leases (number of active leases in pool)
606 leases_path : '/var/lib/dhcp/dhcpd.leases'
607 pools : '192.168.3.0/24 192.168.4.0/24 192.168.5.0/24'
610 In case of python2 you need to install `py2-ipaddress` to make plugin work.
611 The module will not work If no configuration is given.
618 Module monitor /proc/mdstat
622 1. **Health** Number of failed disks in every array (aggregate chart).
625 * total (number of devices array ideally would have)
626 * inuse (number of devices currently are in use)
628 3. **Current status**
630 * recovery in percent
634 4. **Operation status** (if resync/recovery/reshape/check is active)
636 * speed in megabytes/s
639 No configuration is needed.
645 Memcached monitoring module. Data grabbed from [stats interface](https://github.com/memcached/memcached/wiki/Commands#stats).
647 1. **Network** in kilobytes/s
651 2. **Connections** per second
656 3. **Items** in cluster
660 4. **Evicted and Reclaimed** items
664 5. **GET** requests/s
668 6. **GET rate** rate in requests/s
671 7. **SET rate** rate in requests/s
674 8. **DELETE** requests/s
678 9. **CAS** requests/s
683 10. **Increment** requests/s
687 11. **Decrement** requests/s
691 12. **Touch** requests/s
695 13. **Touch rate** rate in requests/s
709 If no configuration is given, module will attempt to connect to memcached instance on `127.0.0.1:11211` address.
715 Module monitor mongodb performance and health metrics
718 * `python-pymongo` package.
720 You need to install it manually.
723 Number of charts depends on mongodb version, storage engine and other features (replication):
725 1. **Read requests**:
727 * getmore (operation the cursor executes to get additional data from query)
729 2. **Write requests**:
734 3. **Active clients**:
735 * readers (number of clients with read operations in progress or queued)
736 * writers (number of clients with write operations in progress or queued)
738 4. **Journal transactions**:
739 * commits (count of transactions that have been written to the journal)
741 5. **Data written to the journal**:
742 * volume (volume of data)
744 6. **Background flush** (MMAPv1):
745 * average ms (average time taken by flushes to execute)
746 * last ms (time taken by the last flush)
748 8. **Read tickets** (WiredTiger):
749 * in use (number of read tickets in use)
750 * available (number of available read tickets remaining)
752 9. **Write tickets** (WiredTiger):
753 * in use (number of write tickets in use)
754 * available (number of available write tickets remaining)
757 * opened (number of cursors currently opened by MongoDB for clients)
758 * timedOut (number of cursors that have timed)
759 * noTimeout (number of open cursors with timeout disabled)
762 * connected (number of clients currently connected to the database server)
763 * unused (number of unused connections available for new clients)
765 12. **Memory usage metrics**:
767 * resident (amount of memory used by the database process)
772 * page faults (number of times MongoDB had to request from disk)
774 14. **Cache metrics** (WiredTiger):
775 * percentage of bytes currently in the cache (amount of space taken by cached data)
776 * percantage of tracked dirty bytes in the cache (amount of space taken by dirty data)
778 15. **Pages evicted from cache** (WiredTiger):
782 16. **Queued requests**:
783 * readers (number of read request currently queued)
784 * writers (number of write request currently queued)
787 * msg (number of message assertions raised)
788 * warning (number of warning assertions raised)
789 * regular (number of regular assertions raised)
790 * user (number of assertions corresponding to errors generated by users)
792 18. **Storage metrics** (one chart for every database)
793 * dataSize (size of all documents + padding in the database)
794 * indexSize (size of all indexes in the database)
795 * storageSize (size of all extents in the database)
797 19. **Documents in the database** (one chart for all databases)
798 * documents (number of objects in the database among all the collections)
800 20. **tcmalloc metrics**
802 * current total thread cache
806 * transfer cache free
809 21. **Commands total/failed rate**
817 22. **Locks metrics** (acquireCount metrics - number of times the lock was acquired in the specified mode)
824 23. **Replica set members state**
828 * window (interval of time between the oldest and the latest entries in the oplog)
830 25. **Replication lag**
831 * member (time when last entry from the oplog was applied for every member)
833 26. **Replication set member heartbeat latency**
834 * member (time when last heartbeat was received from replica set member)
851 If no configuration is given, module will attempt to connect to mongodb daemon on `127.0.0.1:27017` address
858 Module monitors one or more mysql servers
861 * python library [MySQLdb](https://github.com/PyMySQL/mysqlclient-python) (faster) or [PyMySQL](https://github.com/PyMySQL/PyMySQL) (slower)
863 It will produce following charts (if data is available):
865 1. **Bandwidth** in kbps
869 2. **Queries** in queries/sec
874 3. **Operations** in operations/sec
891 4. **Table Locks** in locks/sec
895 5. **Select Issues** in issues/sec
902 6. **Sort Issues** in issues/sec
909 You can provide, per server, the following:
911 1. username which have access to database (deafults to 'root')
912 2. password (defaults to none)
913 3. mysql my.cnf configuration file
914 4. mysql socket (optional)
915 5. mysql host (ip or hostname)
916 6. mysql port (defaults to 3306)
918 Here is an example for 3 servers:
926 'my.cnf' : '/etc/mysql/my.cnf'
931 pass : 'blablablabla'
932 socket : '/var/run/mysqld/mysqld.sock'
943 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`
949 This module will monitor one or more nginx servers depending on configuration. Servers can be either local or remote.
952 * nginx with configured 'ngx_http_stub_status_module'
953 * 'location /stub_status'
955 Example nginx configuration can be found in 'python.d/nginx.conf'
957 It produces following charts:
959 1. **Active Connections**
962 2. **Requests** in requests/s
965 3. **Active Connections by Status**
970 4. **Connections Rate** in connections/s
976 Needs only `url` to server's `stub_status`
978 Here is an example for local server:
985 url : 'http://localhost/stub_status'
989 Without configuration, module attempts to connect to `http://localhost/stub_status`
995 Module monitors nginx access log and produces only one chart:
997 1. **nginx status codes** in requests/s
1005 Sample for two vhosts:
1009 path: '/var/log/nginx/access-A.log'
1013 path: '/var/log/nginx/access-B.log'
1016 When no configuration file is found, module tries to parse `/var/log/nginx/access.log` file.
1022 Module uses the `nsd-control stats_noreset` command to provide `nsd` statistics.
1025 * Version of `nsd` must be 4.0+
1026 * Netdata must have permissions to run `nsd-control stats_noreset`
1071 Configuration is not needed.
1077 Module monitor openvpn-status log file.
1081 * If you are running multiple OpenVPN instances out of the same directory, MAKE SURE TO EDIT DIRECTIVES which create output files
1082 so that multiple instances do not overwrite each other's output files.
1084 * Make sure NETDATA USER CAN READ openvpn-status.log
1086 * Update_every interval MUST MATCH interval on which OpenVPN writes operational status to log file.
1090 1. **Users** OpenVPN active users
1093 2. **Traffic** OpenVPN overall bandwidth usage in kilobit/s
1103 log_path : '/var/log/openvpn-status.log'
1110 This module will monitor one or more php-fpm instances depending on configuration.
1113 * php-fpm with enabled `status` page
1114 * access to `status` page via web server
1116 It produces following charts:
1118 1. **Active Connections**
1123 2. **Requests** in requests/s
1132 Needs only `url` to server's `status`
1134 Here is an example for local instance:
1141 url : 'http://localhost/status'
1145 Without configuration, module attempts to connect to `http://localhost/status`
1151 Simple module executing `postfix -p` to grab postfix queue.
1153 It produces only two charts:
1155 1. **Postfix Queue Emails**
1158 2. **Postfix Queue Emails Size** in KB
1161 Configuration is not needed.
1167 Get INFO data from redis instance.
1169 Following charts are drawn:
1171 1. **Operations** per second
1174 2. **Hit rate** in percent
1177 3. **Memory utilization** in kilobytes
1181 4. **Database keys**
1182 * lines are creates dynamically based on how many databases are there
1196 socket : '/var/lib/redis/redis.sock'
1204 When no configuration file is found, module tries to connect to TCP/IP socket: `localhost:6379`.
1210 System sensors information.
1212 Charts are created dynamically.
1216 For detailed configuration information please read [`sensors.conf`](https://github.com/firehol/netdata/blob/master/conf.d/python.d/sensors.conf) file.
1222 This module will monitor one or more squid instances depending on configuration.
1224 It produces following charts:
1226 1. **Client Bandwidth** in kilobits/s
1231 2. **Client Requests** in requests/s
1236 3. **Server Bandwidth** in kilobits/s
1240 4. **Server Requests** in requests/s
1250 request : 'cache_object://localhost:3128/counters'
1255 Without any configuration module will try to autodetect where squid presents its `counters` data
1261 Present tomcat containers memory utilization.
1265 1. **Requests** per second
1268 2. **Volume** in KB/s
1275 4. **JVM Free Memory** in MB
1283 url : 'http://127.0.0.1:8080/manager/status?XML=true'
1284 user : 'tomcat_username'
1285 pass : 'secret_tomcat_password'
1288 Without configuration, module attempts to connect to `http://localhost:8080/manager/status?XML=true`, without any credentials.
1289 So it will probably fail.
1295 Module uses the `varnishstat` command to provide varnish cache statistics.
1299 1. **Client metrics**
1302 * good client requests received
1304 2. **All history hit rate ratio**
1305 * cache hits in percent
1306 * cache miss in percent
1307 * cache hits for pass percent
1309 3. **Curent poll hit rate ratio**
1310 * cache hits in percent
1311 * cache miss in percent
1312 * cache hits for pass percent
1314 4. **Thread-related metrics** (only for varnish version 4+)
1315 * total number of threads
1317 * threads creation failed
1319 * length os session queue
1320 * sessions queued for thread
1322 5. **Backend health**
1323 * backend conn. success
1324 * backend conn. not attempted
1325 * backend conn. too many
1326 * backend conn. failures
1327 * backend conn. reuses
1328 * backend conn. recycles
1329 * backend conn. retry
1330 * backend requests made
1333 * memory available in megabytes
1334 * memory allocated in megabytes
1336 7. **Problems summary**
1338 * session accept failures
1339 * session pipe overflow
1340 * backend conn. not attempted
1341 * fetch failed (all causes)
1342 * backend conn. too many
1345 * length of session queue
1346 * HTTP header overflows
1348 * ESI parse warnings
1351 * varnish instance uptime in seconds
1355 No configuration is needed.