python.d/README.md

   1 # Disclaimer
   2
   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**.
   6
   7 Every configuration file must have one of two formats:
   8
   9 - Configuration for only one job:
  10
  11 ```yaml
  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
  15
  16 other_var1   : bla  # variables passed to module
  17 other_var2   : alb
  18 ```
  19
  20 - Configuration for many jobs (ex. mysql):
  21
  22 ```yaml
  23 # module defaults:
  24 update_every : 2
  25 retries      : 1
  26 priority     : 20000
  27
  28 local:  # job name
  29   update_every : 5 # job update frequency
  30   other_var1   : some_val # module specific variable
  31
  32 other_job:
  33   priority     : 5 # job position on dashboard
  34   retries      : 20 # job retries
  35   other_var2   : val # module specific variable
  36 ```
  37
  38 `update_every`, `retries`, and `priority` are always optional.
  39
  40 ---
  41
  42 The following python.d modules are supported:
  43
  44 # apache
  45
  46 This module will monitor one or more apache servers depending on configuration.
  47
  48 **Requirements:**
  49  * apache with enabled `mod_status`
  50
  51 It produces the following charts:
  52
  53 1. **Requests** in requests/s
  54  * requests
  55
  56 2. **Connections**
  57  * connections
  58
  59 3. **Async Connections**
  60  * keepalive
  61  * closing
  62  * writing
  63
  64 4. **Bandwidth** in kilobytes/s
  65  * sent
  66
  67 5. **Workers**
  68  * idle
  69  * busy
  70
  71 6. **Lifetime Avg. Requests/s** in requests/s
  72  * requests_sec
  73
  74 7. **Lifetime Avg. Bandwidth/s** in kilobytes/s
  75  * size_sec
  76
  77 8. **Lifetime Avg. Response Size** in bytes/request
  78  * size_req
  79
  80 ### configuration
  81
  82 Needs only `url` to server's `server-status?auto`
  83
  84 Here is an example for 2 servers:
  85
  86 ```yaml
  87 update_every : 10
  88 priority     : 90100
  89
  90 local:
  91   url      : 'http://localhost/server-status?auto'
  92   retries  : 20
  93
  94 remote:
  95   url          : 'http://www.apache.org/server-status?auto'
  96   update_every : 5
  97   retries      : 4
  98 ```
  99
 100 Without configuration, module attempts to connect to `http://localhost/server-status?auto`
 101
 102 ---
 103
 104 # apache_cache
 105
 106 Module monitors apache mod_cache log and produces only one chart:
 107
 108 **cached responses** in percent cached
 109  * hit
 110  * miss
 111  * other
 112
 113 ### configuration
 114
 115 Sample:
 116
 117 ```yaml
 118 update_every : 10
 119 priority     : 120000
 120 retries      : 5
 121 log_path     : '/var/log/apache2/cache.log'
 122 ```
 123
 124 If no configuration is given, module will attempt to read log file at `/var/log/apache2/cache.log`
 125
 126 ---
 127
 128 # bind_rndc
 129
 130 Module parses bind dump file to collect real-time performance metrics
 131
 132 **Requirements:**
 133  * Version of bind must be 9.6 +
 134  * Netdata must have permissions to run `rndc status`
 135
 136 It produces:
 137
 138 1. **Name server statistics**
 139  * requests
 140  * responses
 141  * success
 142  * auth_answer
 143  * nonauth_answer
 144  * nxrrset
 145  * failure
 146  * nxdomain
 147  * recursion
 148  * duplicate
 149  * rejections
 150
 151 2. **Incoming queries**
 152  * RESERVED0
 153  * A
 154  * NS
 155  * CNAME
 156  * SOA
 157  * PTR
 158  * MX
 159  * TXT
 160  * X25
 161  * AAAA
 162  * SRV
 163  * NAPTR
 164  * A6
 165  * DS
 166  * RSIG
 167  * DNSKEY
 168  * SPF
 169  * ANY
 170  * DLV
 171
 172 3. **Outgoing queries**
 173  * Same as Incoming queries
 174
 175
 176 ### configuration
 177
 178 Sample:
 179
 180 ```yaml
 181 local:
 182   named_stats_path       : '/var/log/bind/named.stats'
 183 ```
 184
 185 If no configuration is given, module will attempt to read named.stats file  at `/var/log/bind/named.stats`
 186
 187 ---
 188
 189 # cpufreq
 190
 191 This module shows the current CPU frequency as set by the cpufreq kernel
 192 module.
 193
 194 **Requirement:**
 195 You need to have `CONFIG_CPU_FREQ` and (optionally) `CONFIG_CPU_FREQ_STAT`
 196 enabled in your kernel.
 197
 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).
 204
 205 It produces one chart with multiple lines (one line per core).
 206
 207 ### configuration
 208
 209 Sample:
 210
 211 ```yaml
 212 sys_dir: "/sys/devices"
 213 ```
 214
 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.
 217
 218 ---
 219
 220 # cpuidle
 221
 222 This module monitors the usage of CPU idle states.
 223
 224 **Requirement:**
 225 Your kernel needs to have `CONFIG_CPU_IDLE` enabled.
 226
 227 It produces one stacked chart per CPU, showing the percentage of time spent in
 228 each state.
 229
 230 ---
 231 # dns_query_time
 232
 233 This module provides dns query time statistics.
 234
 235 **Requirement:**
 236 * `python-dnspython` package
 237
 238 It produces one aggregate chart or one chart per dns server, showing the query time.
 239
 240 ---
 241
 242 # dovecot
 243
 244 This module provides statistics information from dovecot server.
 245 Statistics are taken from dovecot socket by executing `EXPORT global` command.
 246 More information about dovecot stats can be found on [project wiki page.](http://wiki2.dovecot.org/Statistics)
 247
 248 **Requirement:**
 249 Dovecot unix socket with R/W permissions for user netdata or dovecot with configured TCP/IP socket.
 250
 251 Module gives information with following charts:
 252
 253 1. **sessions**
 254  * active sessions
 255
 256 2. **logins**
 257  * logins
 258
 259 3. **commands** - number of IMAP commands
 260  * commands
 261
 262 4. **Faults**
 263  * minor
 264  * major
 265
 266 5. **Context Switches**
 267  * volountary
 268  * involountary
 269
 270 6. **disk** in bytes/s
 271  * read
 272  * write
 273
 274 7. **bytes** in bytes/s
 275  * read
 276  * write
 277
 278 8. **number of syscalls** in syscalls/s
 279  * read
 280  * write
 281
 282 9. **lookups** - number of lookups per second
 283  * path
 284  * attr
 285
 286 10. **hits** - number of cache hits
 287  * hits
 288
 289 11. **attempts** - authorization attemts
 290  * success
 291  * failure
 292
 293 12. **cache** - cached authorization hits
 294  * hit
 295  * miss
 296
 297 ### configuration
 298
 299 Sample:
 300
 301 ```yaml
 302 localtcpip:
 303   name     : 'local'
 304   host     : '127.0.0.1'
 305   port     : 24242
 306
 307 localsocket:
 308   name     : 'local'
 309   socket   : '/var/run/dovecot/stats'
 310 ```
 311
 312 If no configuration is given, module will attempt to connect to dovecot using unix socket localized in `/var/run/dovecot/stats`
 313
 314 ---
 315
 316 # elasticsearch
 317
 318 Module monitor elasticsearch performance and health metrics
 319
 320 It produces:
 321
 322 1. **Search performance** charts:
 323  * Number of queries, fetches
 324  * Time spent on queries, fetches
 325  * Query and fetch latency
 326
 327 2. **Indexing performance** charts:
 328  * Number of documents indexed, index refreshes, flushes
 329  * Time spent on indexing, refreshing, flushing
 330  * Indexing and flushing latency
 331
 332 3. **Memory usage and garbace collection** charts:
 333  * JVM heap currently in use, commited
 334  * Count of garbage collections
 335  * Time spent on garbage collections
 336
 337 4. **Host metrics** charts:
 338  * Available file descriptors in percent
 339  * Opened HTTP connections
 340  * Cluster communication transport metrics
 341
 342 5. **Queues and rejections** charts:
 343  * Number of queued/rejected threads in thread pool
 344
 345 6. **Fielddata cache** charts:
 346  * Fielddata cache size
 347  * Fielddata evictions and circuit breaker tripped count
 348
 349 7. **Cluster health API** charts:
 350  * Cluster status
 351  * Nodes and tasks statistics
 352  * Shards statistics
 353
 354 8. **Cluster stats API** charts:
 355  * Nodes statistics
 356  * Query cache statistics
 357  * Docs statistics
 358  * Store statistics
 359  * Indices and shards statistics
 360
 361 ### configuration
 362
 363 Sample:
 364
 365 ```yaml
 366 local:
 367   host               :  'ipaddress'   # Server ip address or hostname
 368   port               : 'password'     # Port on which elasticsearch listed
 369   cluster_health     :  True/False    # Calls to cluster health elasticsearch API. Enabled by default.
 370   cluster_stats      :  True/False    # Calls to cluster stats elasticsearch API. Enabled by default.
 371 ```
 372
 373 If no configuration is given, module will fail to run.
 374
 375 ---
 376
 377 # exim
 378
 379 Simple module executing `exim -bpc` to grab exim queue.
 380 This command can take a lot of time to finish its execution thus it is not recommended to run it every second.
 381
 382 It produces only one chart:
 383
 384 1. **Exim Queue Emails**
 385  * emails
 386
 387 Configuration is not needed.
 388
 389 ---
 390
 391 # fail2ban
 392
 393 Module monitor fail2ban log file to show all bans for all active jails
 394
 395 **Requirements:**
 396  * fail2ban.log file MUST BE readable by netdata (A good idea is to add  **create 0640 root netdata** to fail2ban conf at logrotate.d)
 397
 398 It produces one chart with multiple lines (one line per jail)
 399
 400 ### configuration
 401
 402 Sample:
 403
 404 ```yaml
 405 local:
 406  log_path: '/var/log/fail2ban.log'
 407  conf_path: '/etc/fail2ban/jail.local'
 408  exclude: 'dropbear apache'
 409 ```
 410 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`.
 411 If conf file is not found default jail is `ssh`.
 412
 413 ---
 414
 415 # freeradius
 416
 417 Uses the `radclient` command to provide freeradius statistics. It is not recommended to run it every second.
 418
 419 It produces:
 420
 421 1. **Authentication counters:**
 422  * access-accepts
 423  * access-rejects
 424  * auth-dropped-requests
 425  * auth-duplicate-requests
 426  * auth-invalid-requests
 427  * auth-malformed-requests
 428  * auth-unknown-types
 429
 430 2. **Accounting counters:** [optional]
 431  * accounting-requests
 432  * accounting-responses
 433  * acct-dropped-requests
 434  * acct-duplicate-requests
 435  * acct-invalid-requests
 436  * acct-malformed-requests
 437  * acct-unknown-types
 438
 439 3. **Proxy authentication counters:** [optional]
 440  * proxy-access-accepts
 441  * proxy-access-rejects
 442  * proxy-auth-dropped-requests
 443  * proxy-auth-duplicate-requests
 444  * proxy-auth-invalid-requests
 445  * proxy-auth-malformed-requests
 446  * proxy-auth-unknown-types
 447
 448 4. **Proxy accounting counters:** [optional]
 449  * proxy-accounting-requests
 450  * proxy-accounting-responses
 451  * proxy-acct-dropped-requests
 452  * proxy-acct-duplicate-requests
 453  * proxy-acct-invalid-requests
 454  * proxy-acct-malformed-requests
 455  * proxy-acct-unknown-typesa
 456
 457
 458 ### configuration
 459
 460 Sample:
 461
 462 ```yaml
 463 local:
 464   host       : 'localhost'
 465   port       : '18121'
 466   secret     : 'adminsecret'
 467   acct       : False # Freeradius accounting statistics.
 468   proxy_auth : False # Freeradius proxy authentication statistics.
 469   proxy_acct : False # Freeradius proxy accounting statistics.
 470 ```
 471
 472 **Freeradius server configuration:**
 473
 474 The configuration for the status server is automatically created in the sites-available directory.
 475 By default, server is enabled and can be queried from every client.
 476 FreeRADIUS will only respond to status-server messages, if the status-server virtual server has been enabled.
 477
 478 To do this, create a link from the sites-enabled directory to the status file in the sites-available directory:
 479  * cd sites-enabled
 480  * ln -s ../sites-available/status status
 481
 482 and restart/reload your FREERADIUS server.
 483
 484 ---
 485
 486 # haproxy
 487
 488 Module monitors frontend and backend metrics such as bytes in, bytes out, sessions current, sessions in queue current.
 489 And health metrics such as backend servers status (server check should be used).
 490
 491 Plugin can obtain data from url **OR** unix socket.
 492
 493 **Requirement:**
 494 Socket MUST be readable AND writable by netdata user.
 495
 496 It produces:
 497
 498 1. **Frontend** family charts
 499  * Kilobytes in/s
 500  * Kilobytes out/s
 501  * Sessions current
 502  * Sessions in queue current
 503
 504 2. **Backend** family charts
 505  * Kilobytes in/s
 506  * Kilobytes out/s
 507  * Sessions current
 508  * Sessions in queue current
 509
 510 3. **Health** chart
 511  * number of failed servers for every backend (in DOWN state)
 512
 513
 514 ### configuration
 515
 516 Sample:
 517
 518 ```yaml
 519 via_url:
 520   user       : 'username' # ONLY IF stats auth is used
 521   pass       : 'password' # # ONLY IF stats auth is used
 522   url     : 'http://ip.address:port/url;csv;norefresh'
 523 ```
 524
 525 OR
 526
 527 ```yaml
 528 via_socket:
 529   socket       : 'path/to/haproxy/sock'
 530 ```
 531
 532 If no configuration is given, module will fail to run.
 533
 534 ---
 535
 536 # hddtemp
 537
 538 Module monitors disk temperatures from one or more hddtemp daemons.
 539
 540 **Requirement:**
 541 Running `hddtemp` in daemonized mode with access on tcp port
 542
 543 It produces one chart **Temperature** with dynamic number of dimensions (one per disk)
 544
 545 ### configuration
 546
 547 Sample:
 548
 549 ```yaml
 550 update_every: 3
 551 host: "127.0.0.1"
 552 port: 7634
 553 ```
 554
 555 If no configuration is given, module will attempt to connect to hddtemp daemon on `127.0.0.1:7634` address
 556
 557 ---
 558
 559 # IPFS
 560
 561 Module monitors [IPFS](https://ipfs.io) basic information.
 562
 563 1. **Bandwidth** in kbits/s
 564  * in
 565  * out
 566
 567 2. **Peers**
 568  * peers
 569
 570 ### configuration
 571
 572 Only url to IPFS server is needed.
 573
 574 Sample:
 575
 576 ```yaml
 577 localhost:
 578   name : 'local'
 579   url  : 'http://localhost:5001'
 580 ```
 581
 582 ---
 583
 584 # isc_dhcpd
 585
 586 Module monitor leases database to show all active leases for given pools.
 587
 588 **Requirements:**
 589  * dhcpd leases file MUST BE readable by netdata
 590  * pools MUST BE in CIDR format
 591
 592 It produces:
 593
 594 1. **Pools utilization** Aggregate chart for all pools.
 595  * utilization in percent
 596
 597 2. **Total leases**
 598  * leases (overall number of leases for all pools)
 599
 600 3. **Active leases** for every pools
 601   * leases (number of active leases in pool)
 602
 603
 604 ### configuration
 605
 606 Sample:
 607
 608 ```yaml
 609 local:
 610   leases_path       : '/var/lib/dhcp/dhcpd.leases'
 611   pools       : '192.168.3.0/24 192.168.4.0/24 192.168.5.0/24'
 612 ```
 613
 614 In case of python2 you need to  install `py2-ipaddress` to make plugin work.
 615 The module will not work If no configuration is given.
 616
 617 ---
 618
 619
 620 # mdstat
 621
 622 Module monitor /proc/mdstat
 623
 624 It produces:
 625
 626 1. **Health** Number of failed disks in every array (aggregate chart).
 627
 628 2. **Disks stats**
 629  * total (number of devices array ideally would have)
 630  * inuse (number of devices currently are in use)
 631
 632 3. **Current status**
 633  * resync in percent
 634  * recovery in percent
 635  * reshape in percent
 636  * check in percent
 637
 638 4. **Operation status** (if resync/recovery/reshape/check is active)
 639  * finish in minutes
 640  * speed in megabytes/s
 641
 642 ### configuration
 643 No configuration is needed.
 644
 645 ---
 646
 647 # memcached
 648
 649 Memcached monitoring module. Data grabbed from [stats interface](https://github.com/memcached/memcached/wiki/Commands#stats).
 650
 651 1. **Network** in kilobytes/s
 652  * read
 653  * written
 654
 655 2. **Connections** per second
 656  * current
 657  * rejected
 658  * total
 659
 660 3. **Items** in cluster
 661  * current
 662  * total
 663
 664 4. **Evicted and Reclaimed** items
 665  * evicted
 666  * reclaimed
 667
 668 5. **GET** requests/s
 669  * hits
 670  * misses
 671
 672 6. **GET rate** rate in requests/s
 673  * rate
 674
 675 7. **SET rate** rate in requests/s
 676  * rate
 677
 678 8. **DELETE** requests/s
 679  * hits
 680  * misses
 681
 682 9. **CAS** requests/s
 683  * hits
 684  * misses
 685  * bad value
 686
 687 10. **Increment** requests/s
 688  * hits
 689  * misses
 690
 691 11. **Decrement** requests/s
 692  * hits
 693  * misses
 694
 695 12. **Touch** requests/s
 696  * hits
 697  * misses
 698
 699 13. **Touch rate** rate in requests/s
 700  * rate
 701
 702 ### configuration
 703
 704 Sample:
 705
 706 ```yaml
 707 localtcpip:
 708   name     : 'local'
 709   host     : '127.0.0.1'
 710   port     : 24242
 711 ```
 712
 713 If no configuration is given, module will attempt to connect to memcached instance on `127.0.0.1:11211` address.
 714
 715 ---
 716
 717 # mongodb
 718
 719 Module monitor mongodb performance and health metrics
 720
 721 **Requirements:**
 722  * `python-pymongo` package.
 723
 724 You need to install it manually.
 725
 726
 727 Number of charts depends on mongodb version, storage engine and other features (replication):
 728
 729 1. **Read requests**:
 730  * query
 731  * getmore (operation the cursor executes to get additional data from query)
 732
 733 2. **Write requests**:
 734  * insert
 735  * delete
 736  * update
 737
 738 3. **Active clients**:
 739  * readers (number of clients with read operations in progress or queued)
 740  * writers (number of clients with write operations in progress or queued)
 741
 742 4. **Journal transactions**:
 743  * commits (count of transactions that have been written to the journal)
 744
 745 5. **Data written to the journal**:
 746  * volume (volume of data)
 747
 748 6. **Background flush** (MMAPv1):
 749  * average ms (average time taken by flushes to execute)
 750  * last ms (time taken by the last flush)
 751
 752 8. **Read tickets** (WiredTiger):
 753  * in use (number of read tickets in use)
 754  * available (number of available read tickets remaining)
 755
 756 9. **Write tickets** (WiredTiger):
 757  * in use (number of write tickets in use)
 758  * available (number of available write tickets remaining)
 759
 760 10. **Cursors**:
 761  * opened (number of cursors currently opened by MongoDB for clients)
 762  * timedOut (number of cursors that have timed)
 763  * noTimeout (number of open cursors with timeout disabled)
 764
 765 11. **Connections**:
 766  * connected (number of clients currently connected to the database server)
 767  * unused (number of unused connections available for new clients)
 768
 769 12. **Memory usage metrics**:
 770  * virtual
 771  * resident (amount of memory used by the database process)
 772  * mapped
 773  * non mapped
 774
 775 13. **Page faults**:
 776  * page faults (number of times MongoDB had to request from disk)
 777
 778 14. **Cache metrics** (WiredTiger):
 779  * percentage of bytes currently in the cache (amount of space taken by cached data)
 780  * percantage of tracked dirty bytes in the cache (amount of space taken by dirty data)
 781
 782 15. **Pages evicted from cache** (WiredTiger):
 783  * modified
 784  * unmodified
 785
 786 16. **Queued requests**:
 787  * readers (number of read request currently queued)
 788  * writers (number of write request currently queued)
 789
 790 17. **Errors**:
 791  * msg (number of message assertions raised)
 792  * warning (number of warning assertions raised)
 793  * regular (number of regular assertions raised)
 794  * user (number of assertions corresponding to errors generated by users)
 795
 796 18. **Storage metrics** (one chart for every database)
 797  * dataSize (size of all documents + padding in the database)
 798  * indexSize (size of all indexes in the database)
 799  * storageSize (size of all extents in the database)
 800
 801 19. **Documents in the database** (one chart for all databases)
 802  * documents (number of objects in the database among all the collections)
 803
 804 20. **tcmalloc metrics**
 805  * central cache free
 806  * current total thread cache
 807  * pageheap free
 808  * pageheap unmapped
 809  * thread cache free
 810  * transfer cache free
 811  * heap size
 812
 813 21. **Commands total/failed rate**
 814  * count
 815  * createIndex
 816  * delete
 817  * eval
 818  * findAndModify
 819  * insert
 820
 821 22. **Locks metrics** (acquireCount metrics - number of times the lock was acquired in the specified mode)
 822  * Global lock
 823  * Database lock
 824  * Collection lock
 825  * Metadata lock
 826  * oplog lock
 827
 828 23. **Replica set members state**
 829  * state
 830
 831 24. **Oplog window**
 832   * window (interval of time between the oldest and the latest entries in the oplog)
 833
 834 25. **Replication lag**
 835   * member (time when last entry from the oplog was applied for every member)
 836
 837 26. **Replication set member heartbeat latency**
 838   * member (time when last heartbeat was received from replica set member)
 839
 840
 841 ### configuration
 842
 843 Sample:
 844
 845 ```yaml
 846 local:
 847     name : 'local'
 848     host : '127.0.0.1'
 849     port : 27017
 850     user : 'netdata'
 851     pass : 'netdata'
 852
 853 ```
 854
 855 If no configuration is given, module will attempt to connect to mongodb daemon on `127.0.0.1:27017` address
 856
 857 ---
 858
 859
 860 # mysql
 861
 862 Module monitors one or more mysql servers
 863
 864 **Requirements:**
 865  * python library [MySQLdb](https://github.com/PyMySQL/mysqlclient-python) (faster) or [PyMySQL](https://github.com/PyMySQL/PyMySQL) (slower)
 866
 867 It will produce following charts (if data is available):
 868
 869 1. **Bandwidth** in kbps
 870  * in
 871  * out
 872
 873 2. **Queries** in queries/sec
 874  * queries
 875  * questions
 876  * slow queries
 877
 878 3. **Operations** in operations/sec
 879  * opened tables
 880  * flush
 881  * commit
 882  * delete
 883  * prepare
 884  * read first
 885  * read key
 886  * read next
 887  * read prev
 888  * read random
 889  * read random next
 890  * rollback
 891  * save point
 892  * update
 893  * write
 894
 895 4. **Table Locks** in locks/sec
 896  * immediate
 897  * waited
 898
 899 5. **Select Issues** in issues/sec
 900  * full join
 901  * full range join
 902  * range
 903  * range check
 904  * scan
 905
 906 6. **Sort Issues** in issues/sec
 907  * merge passes
 908  * range
 909  * scan
 910
 911 ### configuration
 912
 913 You can provide, per server, the following:
 914
 915 1. username which have access to database (deafults to 'root')
 916 2. password (defaults to none)
 917 3. mysql my.cnf configuration file
 918 4. mysql socket (optional)
 919 5. mysql host (ip or hostname)
 920 6. mysql port (defaults to 3306)
 921
 922 Here is an example for 3 servers:
 923
 924 ```yaml
 925 update_every : 10
 926 priority     : 90100
 927 retries      : 5
 928
 929 local:
 930   'my.cnf'   : '/etc/mysql/my.cnf'
 931   priority   : 90000
 932
 933 local_2:
 934   user     : 'root'
 935   pass : 'blablablabla'
 936   socket   : '/var/run/mysqld/mysqld.sock'
 937   update_every : 1
 938
 939 remote:
 940   user     : 'admin'
 941   pass : 'bla'
 942   host     : 'example.org'
 943   port     : 9000
 944   retries  : 20
 945 ```
 946
 947 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`
 948
 949 ---
 950
 951 # nginx
 952
 953 This module will monitor one or more nginx servers depending on configuration. Servers can be either local or remote.
 954
 955 **Requirements:**
 956  * nginx with configured 'ngx_http_stub_status_module'
 957  * 'location /stub_status'
 958
 959 Example nginx configuration can be found in 'python.d/nginx.conf'
 960
 961 It produces following charts:
 962
 963 1. **Active Connections**
 964  * active
 965
 966 2. **Requests** in requests/s
 967  * requests
 968
 969 3. **Active Connections by Status**
 970  * reading
 971  * writing
 972  * waiting
 973
 974 4. **Connections Rate** in connections/s
 975  * accepts
 976  * handled
 977
 978 ### configuration
 979
 980 Needs only `url` to server's `stub_status`
 981
 982 Here is an example for local server:
 983
 984 ```yaml
 985 update_every : 10
 986 priority     : 90100
 987
 988 local:
 989   url     : 'http://localhost/stub_status'
 990   retries : 10
 991 ```
 992
 993 Without configuration, module attempts to connect to `http://localhost/stub_status`
 994
 995 ---
 996
 997 # nsd
 998
 999 Module uses the `nsd-control stats_noreset` command to provide `nsd` statistics.
1000
1001 **Requirements:**
1002  * Version of `nsd` must be 4.0+
1003  * Netdata must have permissions to run `nsd-control stats_noreset`
1004
1005 It produces:
1006
1007 1. **Queries**
1008  * queries
1009
1010 2. **Zones**
1011  * master
1012  * slave
1013
1014 3. **Protocol**
1015  * udp
1016  * udp6
1017  * tcp
1018  * tcp6
1019
1020 4. **Query Type**
1021  * A
1022  * NS
1023  * CNAME
1024  * SOA
1025  * PTR
1026  * HINFO
1027  * MX
1028  * NAPTR
1029  * TXT
1030  * AAAA
1031  * SRV
1032  * ANY
1033
1034 5. **Transfer**
1035  * NOTIFY
1036  * AXFR
1037
1038 6. **Return Code**
1039  * NOERROR
1040  * FORMERR
1041  * SERVFAIL
1042  * NXDOMAIN
1043  * NOTIMP
1044  * REFUSED
1045  * YXDOMAIN
1046
1047
1048 Configuration is not needed.
1049
1050 ---
1051
1052 # ovpn_status_log
1053
1054 Module monitor openvpn-status log file.
1055
1056 **Requirements:**
1057
1058  * If you are running multiple OpenVPN instances out of the same directory, MAKE SURE TO EDIT DIRECTIVES which create output files
1059  so that multiple instances do not overwrite each other's output files.
1060
1061  * Make sure NETDATA USER CAN READ openvpn-status.log
1062
1063  * Update_every interval MUST MATCH interval on which OpenVPN writes operational status to log file.
1064
1065 It produces:
1066
1067 1. **Users** OpenVPN active users
1068  * users
1069
1070 2. **Traffic** OpenVPN overall bandwidth usage in kilobit/s
1071  * in
1072  * out
1073
1074 ### configuration
1075
1076 Sample:
1077
1078 ```yaml
1079 default
1080  log_path     : '/var/log/openvpn-status.log'
1081 ```
1082
1083 ---
1084
1085 # phpfpm
1086
1087 This module will monitor one or more php-fpm instances depending on configuration.
1088
1089 **Requirements:**
1090  * php-fpm with enabled `status` page
1091  * access to `status` page via web server
1092
1093 It produces following charts:
1094
1095 1. **Active Connections**
1096  * active
1097  * maxActive
1098  * idle
1099
1100 2. **Requests** in requests/s
1101  * requests
1102
1103 3. **Performance**
1104  * reached
1105  * slow
1106
1107 ### configuration
1108
1109 Needs only `url` to server's `status`
1110
1111 Here is an example for local instance:
1112
1113 ```yaml
1114 update_every : 3
1115 priority     : 90100
1116
1117 local:
1118   url     : 'http://localhost/status'
1119   retries : 10
1120 ```
1121
1122 Without configuration, module attempts to connect to `http://localhost/status`
1123
1124 ---
1125
1126 # postfix
1127
1128 Simple module executing `postfix -p` to grab postfix queue.
1129
1130 It produces only two charts:
1131
1132 1. **Postfix Queue Emails**
1133  * emails
1134
1135 2. **Postfix Queue Emails Size** in KB
1136  * size
1137
1138 Configuration is not needed.
1139
1140 ---
1141
1142 # postgres
1143
1144 Module monitors one or more postgres servers.
1145
1146 **Requirements:**
1147
1148  * `python-psycopg2` package. You have to install to manually.
1149
1150 Following charts are drawn:
1151
1152 1. **Database size** MB
1153  * size
1154
1155 2. **Current Backend Processes** processes
1156  * active
1157
1158 3. **Write-Ahead Logging Statistics** files/s
1159  * total
1160  * ready
1161  * done
1162
1163 4. **Checkpoints** writes/s
1164  * scheduled
1165  * requested
1166
1167 5. **Current connections to db** count
1168  * connections
1169
1170 6. **Tuples returned from db** tuples/s
1171  * sequential
1172  * bitmap
1173
1174 7. **Tuple reads from db** reads/s
1175  * disk
1176  * cache
1177
1178 8. **Transactions on db** transactions/s
1179  * commited
1180  * rolled back
1181
1182 9. **Tuples written to db** writes/s
1183  * inserted
1184  * updated
1185  * deleted
1186  * conflicts
1187
1188 10. **Locks on db** count per type
1189  * locks
1190
1191 ### configuration
1192
1193 ```yaml
1194 socket:
1195   name         : 'socket'
1196   user         : 'postgres'
1197   database     : 'postgres'
1198
1199 tcp:
1200   name         : 'tcp'
1201   user         : 'postgres'
1202   database     : 'postgres'
1203   host         : 'localhost'
1204   port         : 5432
1205 ```
1206
1207 When no configuration file is found, module tries to connect to TCP/IP socket: `localhost:5432`.
1208
1209 ---
1210
1211 # redis
1212
1213 Get INFO data from redis instance.
1214
1215 Following charts are drawn:
1216
1217 1. **Operations** per second
1218  * operations
1219
1220 2. **Hit rate** in percent
1221  * rate
1222
1223 3. **Memory utilization** in kilobytes
1224  * total
1225  * lua
1226
1227 4. **Database keys**
1228  * lines are creates dynamically based on how many databases are there
1229
1230 5. **Clients**
1231  * connected
1232  * blocked
1233
1234 6. **Slaves**
1235  * connected
1236
1237 ### configuration
1238
1239 ```yaml
1240 socket:
1241   name     : 'local'
1242   socket   : '/var/lib/redis/redis.sock'
1243
1244 localhost:
1245   name     : 'local'
1246   host     : 'localhost'
1247   port     : 6379
1248 ```
1249
1250 When no configuration file is found, module tries to connect to TCP/IP socket: `localhost:6379`.
1251
1252 ---
1253
1254 # sensors
1255
1256 System sensors information.
1257
1258 Charts are created dynamically.
1259
1260 ### configuration
1261
1262 For detailed configuration information please read [`sensors.conf`](https://github.com/firehol/netdata/blob/master/conf.d/python.d/sensors.conf) file.
1263
1264 ---
1265
1266 # squid
1267
1268 This module will monitor one or more squid instances depending on configuration.
1269
1270 It produces following charts:
1271
1272 1. **Client Bandwidth** in kilobits/s
1273  * in
1274  * out
1275  * hits
1276
1277 2. **Client Requests** in requests/s
1278  * requests
1279  * hits
1280  * errors
1281
1282 3. **Server Bandwidth** in kilobits/s
1283  * in
1284  * out
1285
1286 4. **Server Requests** in requests/s
1287  * requests
1288  * errors
1289
1290 ### configuration
1291
1292 ```yaml
1293 priority     : 50000
1294
1295 local:
1296   request : 'cache_object://localhost:3128/counters'
1297   host    : 'localhost'
1298   port    : 3128
1299 ```
1300
1301 Without any configuration module will try to autodetect where squid presents its `counters` data
1302
1303 ---
1304
1305 # smartd_log
1306
1307 Module monitor `smartd` log files to collect HDD/SSD S.M.A.R.T attributes.
1308
1309 It produces following charts (you can add additional attributes in the module configuration file):
1310
1311 1. **Read Error Rate** attribute 1
1312
1313 2. **Start/Stop Count** attribute 4
1314
1315 3. **Reallocated Sectors Count** attribute 5
1316
1317 4. **Seek Error Rate** attribute 7
1318
1319 5. **Power-On Hours Count** attribute 9
1320
1321 6. **Power Cycle Count** attribute 12
1322
1323 7. **Load/Unload Cycles** attribute 193
1324
1325 8. **Temperature** attribute 194
1326
1327 9. **Current Pending Sectors** attribute 197
1328
1329 10. **Off-Line Uncorrectable** attribute 198
1330
1331 11. **Write Error Rate** attribute 200
1332
1333 ### configuration
1334
1335 ```yaml
1336 local:
1337   log_path : '/var/log/smartd/'
1338 ```
1339
1340 If no configuration is given, module will attempt to read log files in /var/log/smartd/ directory.
1341
1342 ---
1343
1344 # tomcat
1345
1346 Present tomcat containers memory utilization.
1347
1348 Charts:
1349
1350 1. **Requests** per second
1351  * accesses
1352
1353 2. **Volume** in KB/s
1354  * volume
1355
1356 3. **Threads**
1357  * current
1358  * busy
1359
1360 4. **JVM Free Memory** in MB
1361  * jvm
1362
1363 ### configuration
1364
1365 ```yaml
1366 localhost:
1367   name : 'local'
1368   url  : 'http://127.0.0.1:8080/manager/status?XML=true'
1369   user : 'tomcat_username'
1370   pass : 'secret_tomcat_password'
1371 ```
1372
1373 Without configuration, module attempts to connect to `http://localhost:8080/manager/status?XML=true`, without any credentials.
1374 So it will probably fail.
1375
1376 ---
1377
1378 # varnish cache
1379
1380 Module uses the `varnishstat` command to provide varnish cache statistics.
1381
1382 It produces:
1383
1384 1. **Client metrics**
1385  * session accepted
1386  * session dropped
1387  * good client requests received
1388
1389 2. **All history hit rate ratio**
1390  * cache hits in percent
1391  * cache miss in percent
1392  * cache hits for pass percent
1393
1394 3. **Curent poll hit rate ratio**
1395  * cache hits in percent
1396  * cache miss in percent
1397  * cache hits for pass percent
1398
1399 4. **Thread-related metrics** (only for varnish version 4+)
1400  * total number of threads
1401  * threads created
1402  * threads creation failed
1403  * threads hit max
1404  * length os session queue
1405  * sessions queued for thread
1406
1407 5. **Backend health**
1408  * backend conn. success
1409  * backend conn. not attempted
1410  * backend conn. too many
1411  * backend conn. failures
1412  * backend conn. reuses
1413  * backend conn. recycles
1414  * backend conn. retry
1415  * backend requests made
1416
1417 6. **Memory usage**
1418  * memory available in megabytes
1419  * memory allocated in megabytes
1420
1421 7. **Problems summary**
1422  * session dropped
1423  * session accept failures
1424  * session pipe overflow
1425  * backend conn. not attempted
1426  * fetch failed (all causes)
1427  * backend conn. too many
1428  * threads hit max
1429  * threads destroyed
1430  * length of session queue
1431  * HTTP header overflows
1432  * ESI parse errors
1433  * ESI parse warnings
1434
1435 8. **Uptime**
1436  * varnish instance uptime in seconds
1437
1438 ### configuration
1439
1440 No configuration is needed.
1441
1442 ---
1443
1444 # web_log
1445
1446 Tails the apache/nginx/lighttpd/gunicorn log files to collect real-time web-server statistics.
1447
1448 It produces following charts:
1449
1450 1. **Response by type** requests/s
1451  * success (1xx, 2xx, 304)
1452  * error (5xx)
1453  * redirect (3xx except 304)
1454  * bad (4xx)
1455  * other (all other responses)
1456
1457 2. **Response by code family** requests/s
1458  * 1xx (informational)
1459  * 2xx (successful)
1460  * 3xx (redirect)
1461  * 4xx (bad)
1462  * 5xx (internal server errors)
1463  * other (non-standart responses)
1464  * unmatched (the lines in the log file that are not matched)
1465
1466 3. **Detailed Response Codes** requests/s (number of responses for each response code family individually)
1467
1468 4. **Bandwidth** KB/s
1469  * received (bandwidth of requests)
1470  * send (bandwidth of responses)
1471
1472 5. **Timings** ms (request processing time)
1473  * min (bandwidth of requests)
1474  * max (bandwidth of responses)
1475  * average (bandwidth of responses)
1476
1477 6. **Request per url** requests/s (configured by user)
1478
1479 7. **Http Methods** requests/s (requests per http method)
1480
1481 8. **Http Versions** requests/s (requests per http version)
1482
1483 9. **IP protocols** requests/s (requests per ip protocol version)
1484
1485 10. **Curent Poll Unique Client IPs** unique ips/s (unique client IPs per data collection iteration)
1486
1487 11. **All Time Unique Client IPs** unique ips/s (unique client IPs since the last restart of netdata)
1488
1489
1490 ### configuration
1491
1492 ```yaml
1493 nginx_log:
1494   name  : 'nginx_log'
1495   path  : '/var/log/nginx/access.log'
1496
1497 apache_log:
1498   name  : 'apache_log'
1499   path  : '/var/log/apache/other_vhosts_access.log'
1500   categories:
1501       cacti : 'cacti.*'
1502       observium : 'observium'
1503 ```
1504
1505 Module has preconfigured jobs for nginx, apache and gunicorn on various distros.
1506
1507 ---