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 monitor mongodb performance and health metrics
712 * `python-pymongo` package.
714 You need to install it manually.
717 Number of charts depends on mongodb version, storage engine and other features (replication):
719 1. **Read requests**:
721 * getmore (operation the cursor executes to get additional data from query)
723 2. **Write requests**:
728 3. **Active clients**:
729 * readers (number of clients with read operations in progress or queued)
730 * writers (number of clients with write operations in progress or queued)
732 4. **Journal transactions**:
733 * commits (count of transactions that have been written to the journal)
735 5. **Data written to the journal**:
736 * volume (volume of data)
738 6. **Background flush** (MMAPv1):
739 * average ms (average time taken by flushes to execute)
740 * last ms (time taken by the last flush)
742 8. **Read tickets** (WiredTiger):
743 * in use (number of read tickets in use)
744 * available (number of available read tickets remaining)
746 9. **Write tickets** (WiredTiger):
747 * in use (number of write tickets in use)
748 * available (number of available write tickets remaining)
751 * opened (number of cursors currently opened by MongoDB for clients)
752 * timedOut (number of cursors that have timed)
753 * noTimeout (number of open cursors with timeout disabled)
756 * connected (number of clients currently connected to the database server)
757 * unused (number of unused connections available for new clients)
759 12. **Memory usage metrics**:
761 * resident (amount of memory used by the database process)
766 * page faults (number of times MongoDB had to request from disk)
768 14. **Cache metrics** (WiredTiger):
769 * percentage of bytes currently in the cache (amount of space taken by cached data)
770 * percantage of tracked dirty bytes in the cache (amount of space taken by dirty data)
772 15. **Pages evicted from cache** (WiredTiger):
776 16. **Queued requests**:
777 * readers (number of read request currently queued)
778 * writers (number of write request currently queued)
781 * msg (number of message assertions raised)
782 * warning (number of warning assertions raised)
783 * regular (number of regular assertions raised)
784 * user (number of assertions corresponding to errors generated by users)
786 18. **Storage metrics** (one chart for every database)
787 * dataSize (size of all documents + padding in the database)
788 * indexSize (size of all indexes in the database)
789 * storageSize (size of all extents in the database)
791 19. **Documents in the database** (one chart for all databases)
792 * documents (number of objects in the database among all the collections)
794 20. **tcmalloc metrics**
796 * current total thread cache
800 * transfer cache free
803 21. **Commands total/failed rate**
811 22. **Locks metrics** (acquireCount metrics - number of times the lock was acquired in the specified mode)
818 23. **Replica set members state**
822 * window (interval of time between the oldest and the latest entries in the oplog)
824 25. **Replication lag**
825 * member (time when last entry from the oplog was applied for every member)
827 26. **Replication set member heartbeat latency**
828 * member (time when last heartbeat was received from replica set member)
845 If no configuration is given, module will attempt to connect to mongodb daemon on `127.0.0.1:27017` address
852 Module monitors one or more mysql servers
855 * python library [MySQLdb](https://github.com/PyMySQL/mysqlclient-python) (faster) or [PyMySQL](https://github.com/PyMySQL/PyMySQL) (slower)
857 It will produce following charts (if data is available):
859 1. **Bandwidth** in kbps
863 2. **Queries** in queries/sec
868 3. **Operations** in operations/sec
885 4. **Table Locks** in locks/sec
889 5. **Select Issues** in issues/sec
896 6. **Sort Issues** in issues/sec
903 You can provide, per server, the following:
905 1. username which have access to database (deafults to 'root')
906 2. password (defaults to none)
907 3. mysql my.cnf configuration file
908 4. mysql socket (optional)
909 5. mysql host (ip or hostname)
910 6. mysql port (defaults to 3306)
912 Here is an example for 3 servers:
920 'my.cnf' : '/etc/mysql/my.cnf'
925 pass : 'blablablabla'
926 socket : '/var/run/mysqld/mysqld.sock'
937 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`
943 This module will monitor one or more nginx servers depending on configuration. Servers can be either local or remote.
946 * nginx with configured 'ngx_http_stub_status_module'
947 * 'location /stub_status'
949 Example nginx configuration can be found in 'python.d/nginx.conf'
951 It produces following charts:
953 1. **Active Connections**
956 2. **Requests** in requests/s
959 3. **Active Connections by Status**
964 4. **Connections Rate** in connections/s
970 Needs only `url` to server's `stub_status`
972 Here is an example for local server:
979 url : 'http://localhost/stub_status'
983 Without configuration, module attempts to connect to `http://localhost/stub_status`
989 Module uses the `nsd-control stats_noreset` command to provide `nsd` statistics.
992 * Version of `nsd` must be 4.0+
993 * Netdata must have permissions to run `nsd-control stats_noreset`
1038 Configuration is not needed.
1044 Module monitor openvpn-status log file.
1048 * If you are running multiple OpenVPN instances out of the same directory, MAKE SURE TO EDIT DIRECTIVES which create output files
1049 so that multiple instances do not overwrite each other's output files.
1051 * Make sure NETDATA USER CAN READ openvpn-status.log
1053 * Update_every interval MUST MATCH interval on which OpenVPN writes operational status to log file.
1057 1. **Users** OpenVPN active users
1060 2. **Traffic** OpenVPN overall bandwidth usage in kilobit/s
1070 log_path : '/var/log/openvpn-status.log'
1077 This module will monitor one or more php-fpm instances depending on configuration.
1080 * php-fpm with enabled `status` page
1081 * access to `status` page via web server
1083 It produces following charts:
1085 1. **Active Connections**
1090 2. **Requests** in requests/s
1099 Needs only `url` to server's `status`
1101 Here is an example for local instance:
1108 url : 'http://localhost/status'
1112 Without configuration, module attempts to connect to `http://localhost/status`
1118 Simple module executing `postfix -p` to grab postfix queue.
1120 It produces only two charts:
1122 1. **Postfix Queue Emails**
1125 2. **Postfix Queue Emails Size** in KB
1128 Configuration is not needed.
1134 Module monitors one or more postgres servers.
1138 * `python-psycopg2` package. You have to install to manually.
1140 Following charts are drawn:
1142 1. **Database size** MB
1145 2. **Current Backend Processes** processes
1148 3. **Write-Ahead Logging Statistics** files/s
1153 4. **Checkpoints** writes/s
1157 5. **Current connections to db** count
1160 6. **Tuples returned from db** tuples/s
1164 7. **Tuple reads from db** reads/s
1168 8. **Transactions on db** transactions/s
1172 9. **Tuples written to db** writes/s
1178 10. **Locks on db** count per type
1187 database : 'postgres'
1192 database : 'postgres'
1197 When no configuration file is found, module tries to connect to TCP/IP socket: `localhost:5432`.
1203 Get INFO data from redis instance.
1205 Following charts are drawn:
1207 1. **Operations** per second
1210 2. **Hit rate** in percent
1213 3. **Memory utilization** in kilobytes
1217 4. **Database keys**
1218 * lines are creates dynamically based on how many databases are there
1232 socket : '/var/lib/redis/redis.sock'
1240 When no configuration file is found, module tries to connect to TCP/IP socket: `localhost:6379`.
1246 System sensors information.
1248 Charts are created dynamically.
1252 For detailed configuration information please read [`sensors.conf`](https://github.com/firehol/netdata/blob/master/conf.d/python.d/sensors.conf) file.
1258 This module will monitor one or more squid instances depending on configuration.
1260 It produces following charts:
1262 1. **Client Bandwidth** in kilobits/s
1267 2. **Client Requests** in requests/s
1272 3. **Server Bandwidth** in kilobits/s
1276 4. **Server Requests** in requests/s
1286 request : 'cache_object://localhost:3128/counters'
1291 Without any configuration module will try to autodetect where squid presents its `counters` data
1297 Module monitor `smartd` log files to collect HDD/SSD S.M.A.R.T attributes.
1299 It produces following charts (you can add additional attributes in the module configuration file):
1301 1. **Read Error Rate** attribute 1
1303 2. **Start/Stop Count** attribute 4
1305 3. **Reallocated Sectors Count** attribute 5
1307 4. **Seek Error Rate** attribute 7
1309 5. **Power-On Hours Count** attribute 9
1311 6. **Power Cycle Count** attribute 12
1313 7. **Load/Unload Cycles** attribute 193
1315 8. **Temperature** attribute 194
1317 9. **Current Pending Sectors** attribute 197
1319 10. **Off-Line Uncorrectable** attribute 198
1321 11. **Write Error Rate** attribute 200
1327 log_path : '/var/log/smartd/'
1330 If no configuration is given, module will attempt to read log files in /var/log/smartd/ directory.
1336 Present tomcat containers memory utilization.
1340 1. **Requests** per second
1343 2. **Volume** in KB/s
1350 4. **JVM Free Memory** in MB
1358 url : 'http://127.0.0.1:8080/manager/status?XML=true'
1359 user : 'tomcat_username'
1360 pass : 'secret_tomcat_password'
1363 Without configuration, module attempts to connect to `http://localhost:8080/manager/status?XML=true`, without any credentials.
1364 So it will probably fail.
1370 Module uses the `varnishstat` command to provide varnish cache statistics.
1374 1. **Client metrics**
1377 * good client requests received
1379 2. **All history hit rate ratio**
1380 * cache hits in percent
1381 * cache miss in percent
1382 * cache hits for pass percent
1384 3. **Curent poll hit rate ratio**
1385 * cache hits in percent
1386 * cache miss in percent
1387 * cache hits for pass percent
1389 4. **Thread-related metrics** (only for varnish version 4+)
1390 * total number of threads
1392 * threads creation failed
1394 * length os session queue
1395 * sessions queued for thread
1397 5. **Backend health**
1398 * backend conn. success
1399 * backend conn. not attempted
1400 * backend conn. too many
1401 * backend conn. failures
1402 * backend conn. reuses
1403 * backend conn. recycles
1404 * backend conn. retry
1405 * backend requests made
1408 * memory available in megabytes
1409 * memory allocated in megabytes
1411 7. **Problems summary**
1413 * session accept failures
1414 * session pipe overflow
1415 * backend conn. not attempted
1416 * fetch failed (all causes)
1417 * backend conn. too many
1420 * length of session queue
1421 * HTTP header overflows
1423 * ESI parse warnings
1426 * varnish instance uptime in seconds
1430 No configuration is needed.
1436 Tails the apache/nginx/lighttpd/gunicorn log files to collect real-time web-server statistics.
1438 It produces following charts:
1440 1. **Response by type** requests/s
1441 * success (1xx, 2xx, 304)
1443 * redirect (3xx except 304)
1445 * other (all other responses)
1447 2. **Response by code family** requests/s
1448 * 1xx (informational)
1452 * 5xx (internal server errors)
1453 * other (non-standart responses)
1454 * unmatched (the lines in the log file that are not matched)
1456 3. **Detailed Response Codes** requests/s (number of responses for each response code family individually)
1458 4. **Bandwidth** KB/s
1459 * received (bandwidth of requests)
1460 * send (bandwidth of responses)
1462 5. **Timings** ms (request processing time)
1463 * min (bandwidth of requests)
1464 * max (bandwidth of responses)
1465 * average (bandwidth of responses)
1467 6. **Request per url** requests/s (configured by user)
1469 7. **Http Methods** requests/s (requests per http method)
1471 8. **Http Versions** requests/s (requests per http version)
1473 9. **IP protocols** requests/s (requests per ip protocol version)
1475 10. **Curent Poll Unique Client IPs** unique ips/s (unique client IPs per data collection iteration)
1477 11. **All Time Unique Client IPs** unique ips/s (unique client IPs since the last restart of netdata)
1485 path : '/var/log/nginx/access.log'
1489 path : '/var/log/apache/other_vhosts_access.log'
1492 observium : 'observium'
1495 Module has preconfigured jobs for nginx, apache and gunicorn on various distros.