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
 232 # dovecot
 233
 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)
 237
 238 **Requirement:**
 239 Dovecot unix socket with R/W permissions for user netdata or dovecot with configured TCP/IP socket.
 240
 241 Module gives information with following charts:
 242
 243 1. **sessions**
 244  * active sessions
 245
 246 2. **logins**
 247  * logins
 248
 249 3. **commands** - number of IMAP commands
 250  * commands
 251
 252 4. **Faults**
 253  * minor
 254  * major
 255
 256 5. **Context Switches**
 257  * volountary
 258  * involountary
 259
 260 6. **disk** in bytes/s
 261  * read
 262  * write
 263
 264 7. **bytes** in bytes/s
 265  * read
 266  * write
 267
 268 8. **number of syscalls** in syscalls/s
 269  * read
 270  * write
 271
 272 9. **lookups** - number of lookups per second
 273  * path
 274  * attr
 275
 276 10. **hits** - number of cache hits
 277  * hits
 278
 279 11. **attempts** - authorization attemts
 280  * success
 281  * failure
 282
 283 12. **cache** - cached authorization hits
 284  * hit
 285  * miss
 286
 287 ### configuration
 288
 289 Sample:
 290
 291 ```yaml
 292 localtcpip:
 293   name     : 'local'
 294   host     : '127.0.0.1'
 295   port     : 24242
 296
 297 localsocket:
 298   name     : 'local'
 299   socket   : '/var/run/dovecot/stats'
 300 ```
 301
 302 If no configuration is given, module will attempt to connect to dovecot using unix socket localized in `/var/run/dovecot/stats`
 303
 304 ---
 305
 306 # elasticsearch
 307
 308 Module monitor elasticsearch performance and health metrics
 309
 310 **Requirements:**
 311  * python `requests` package.
 312
 313 You need to install it manually. (python-requests or python3-requests depending on the version of python).
 314
 315
 316 It produces:
 317
 318 1. **Search performance** charts:
 319  * Number of queries, fetches
 320  * Time spent on queries, fetches
 321  * Query and fetch latency
 322
 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
 327
 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
 332
 333 4. **Host metrics** charts:
 334  * Available file descriptors in percent
 335  * Opened HTTP connections
 336  * Cluster communication transport metrics
 337
 338 5. **Queues and rejections** charts:
 339  * Number of queued/rejected threads in thread pool
 340
 341 6. **Fielddata cache** charts:
 342  * Fielddata cache size
 343  * Fielddata evictions and circuit breaker tripped count
 344
 345 7. **Cluster health API** charts:
 346  * Cluster status
 347  * Nodes and tasks statistics
 348  * Shards statistics
 349
 350 8. **Cluster stats API** charts:
 351  * Nodes statistics
 352  * Query cache statistics
 353  * Docs statistics
 354  * Store statistics
 355  * Indices and shards statistics
 356
 357 ### configuration
 358
 359 Sample:
 360
 361 ```yaml
 362 local:
 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.
 367 ```
 368
 369 If no configuration is given, module will fail to run.
 370
 371 ---
 372
 373 # exim
 374
 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.
 377
 378 It produces only one chart:
 379
 380 1. **Exim Queue Emails**
 381  * emails
 382
 383 Configuration is not needed.
 384
 385 ---
 386
 387 # fail2ban
 388
 389 Module monitor fail2ban log file to show all bans for all active jails
 390
 391 **Requirements:**
 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)
 393
 394 It produces one chart with multiple lines (one line per jail)
 395
 396 ### configuration
 397
 398 Sample:
 399
 400 ```yaml
 401 local:
 402  log_path: '/var/log/fail2ban.log'
 403  conf_path: '/etc/fail2ban/jail.local'
 404  exclude: 'dropbear apache'
 405 ```
 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`.
 408
 409 ---
 410
 411 # freeradius
 412
 413 Uses the `radclient` command to provide freeradius statistics. It is not recommended to run it every second.
 414
 415 It produces:
 416
 417 1. **Authentication counters:**
 418  * access-accepts
 419  * access-rejects
 420  * auth-dropped-requests
 421  * auth-duplicate-requests
 422  * auth-invalid-requests
 423  * auth-malformed-requests
 424  * auth-unknown-types
 425
 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
 433  * acct-unknown-types
 434
 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
 443
 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
 452
 453
 454 ### configuration
 455
 456 Sample:
 457
 458 ```yaml
 459 local:
 460   host       : 'localhost'
 461   port       : '18121'
 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.
 466 ```
 467
 468 **Freeradius server configuration:**
 469
 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.
 473
 474 To do this, create a link from the sites-enabled directory to the status file in the sites-available directory:
 475  * cd sites-enabled
 476  * ln -s ../sites-available/status status
 477
 478 and restart/reload your FREERADIUS server.
 479
 480 ---
 481
 482 # haproxy
 483
 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).
 486
 487 Plugin can obtain data from url **OR** unix socket.
 488
 489 **Requirement:**
 490 Socket MUST be readable AND writable by netdata user.
 491
 492 It produces:
 493
 494 1. **Frontend** family charts
 495  * Kilobytes in/s
 496  * Kilobytes out/s
 497  * Sessions current
 498  * Sessions in queue current
 499
 500 2. **Backend** family charts
 501  * Kilobytes in/s
 502  * Kilobytes out/s
 503  * Sessions current
 504  * Sessions in queue current
 505
 506 3. **Health** chart
 507  * number of failed servers for every backend (in DOWN state)
 508
 509
 510 ### configuration
 511
 512 Sample:
 513
 514 ```yaml
 515 via_url:
 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'
 519 ```
 520
 521 OR
 522
 523 ```yaml
 524 via_socket:
 525   socket       : 'path/to/haproxy/sock'
 526 ```
 527
 528 If no configuration is given, module will fail to run.
 529
 530 ---
 531
 532 # hddtemp
 533
 534 Module monitors disk temperatures from one or more hddtemp daemons.
 535
 536 **Requirement:**
 537 Running `hddtemp` in daemonized mode with access on tcp port
 538
 539 It produces one chart **Temperature** with dynamic number of dimensions (one per disk)
 540
 541 ### configuration
 542
 543 Sample:
 544
 545 ```yaml
 546 update_every: 3
 547 host: "127.0.0.1"
 548 port: 7634
 549 ```
 550
 551 If no configuration is given, module will attempt to connect to hddtemp daemon on `127.0.0.1:7634` address
 552
 553 ---
 554
 555 # IPFS
 556
 557 Module monitors [IPFS](https://ipfs.io) basic information.
 558
 559 1. **Bandwidth** in kbits/s
 560  * in
 561  * out
 562
 563 2. **Peers**
 564  * peers
 565
 566 ### configuration
 567
 568 Only url to IPFS server is needed.
 569
 570 Sample:
 571
 572 ```yaml
 573 localhost:
 574   name : 'local'
 575   url  : 'http://localhost:5001'
 576 ```
 577
 578 ---
 579
 580 # isc_dhcpd
 581
 582 Module monitor leases database to show all active leases for given pools.
 583
 584 **Requirements:**
 585  * dhcpd leases file MUST BE readable by netdata
 586  * pools MUST BE in CIDR format
 587
 588 It produces:
 589
 590 1. **Pools utilization** Aggregate chart for all pools.
 591  * utilization in percent
 592
 593 2. **Total leases**
 594  * leases (overall number of leases for all pools)
 595
 596 3. **Active leases** for every pools
 597   * leases (number of active leases in pool)
 598
 599
 600 ### configuration
 601
 602 Sample:
 603
 604 ```yaml
 605 local:
 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'
 608 ```
 609
 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.
 612
 613 ---
 614
 615
 616 # mdstat
 617
 618 Module monitor /proc/mdstat
 619
 620 It produces:
 621
 622 1. **Health** Number of failed disks in every array (aggregate chart).
 623
 624 2. **Disks stats**
 625  * total (number of devices array ideally would have)
 626  * inuse (number of devices currently are in use)
 627
 628 3. **Current status**
 629  * resync in percent
 630  * recovery in percent
 631  * reshape in percent
 632  * check in percent
 633
 634 4. **Operation status** (if resync/recovery/reshape/check is active)
 635  * finish in minutes
 636  * speed in megabytes/s
 637
 638 ### configuration
 639 No configuration is needed.
 640
 641 ---
 642
 643 # memcached
 644
 645 Memcached monitoring module. Data grabbed from [stats interface](https://github.com/memcached/memcached/wiki/Commands#stats).
 646
 647 1. **Network** in kilobytes/s
 648  * read
 649  * written
 650
 651 2. **Connections** per second
 652  * current
 653  * rejected
 654  * total
 655
 656 3. **Items** in cluster
 657  * current
 658  * total
 659
 660 4. **Evicted and Reclaimed** items
 661  * evicted
 662  * reclaimed
 663
 664 5. **GET** requests/s
 665  * hits
 666  * misses
 667
 668 6. **GET rate** rate in requests/s
 669  * rate
 670
 671 7. **SET rate** rate in requests/s
 672  * rate
 673
 674 8. **DELETE** requests/s
 675  * hits
 676  * misses
 677
 678 9. **CAS** requests/s
 679  * hits
 680  * misses
 681  * bad value
 682
 683 10. **Increment** requests/s
 684  * hits
 685  * misses
 686
 687 11. **Decrement** requests/s
 688  * hits
 689  * misses
 690
 691 12. **Touch** requests/s
 692  * hits
 693  * misses
 694
 695 13. **Touch rate** rate in requests/s
 696  * rate
 697
 698 ### configuration
 699
 700 Sample:
 701
 702 ```yaml
 703 localtcpip:
 704   name     : 'local'
 705   host     : '127.0.0.1'
 706   port     : 24242
 707 ```
 708
 709 If no configuration is given, module will attempt to connect to memcached instance on `127.0.0.1:11211` address.
 710
 711 ---
 712
 713 # mongodb
 714
 715 Module monitor mongodb performance and health metrics
 716
 717 **Requirements:**
 718  * `python-pymongo` package.
 719
 720 You need to install it manually.
 721
 722
 723 Number of charts depends on mongodb version, storage engine and other features (replication):
 724
 725 1. **Read requests**:
 726  * query
 727  * getmore (operation the cursor executes to get additional data from query)
 728
 729 2. **Write requests**:
 730  * insert
 731  * delete
 732  * update
 733
 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)
 737
 738 4. **Journal transactions**:
 739  * commits (count of transactions that have been written to the journal)
 740
 741 5. **Data written to the journal**:
 742  * volume (volume of data)
 743
 744 6. **Background flush** (MMAPv1):
 745  * average ms (average time taken by flushes to execute)
 746  * last ms (time taken by the last flush)
 747
 748 8. **Read tickets** (WiredTiger):
 749  * in use (number of read tickets in use)
 750  * available (number of available read tickets remaining)
 751
 752 9. **Write tickets** (WiredTiger):
 753  * in use (number of write tickets in use)
 754  * available (number of available write tickets remaining)
 755
 756 10. **Cursors**:
 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)
 760
 761 11. **Connections**:
 762  * connected (number of clients currently connected to the database server)
 763  * unused (number of unused connections available for new clients)
 764
 765 12. **Memory usage metrics**:
 766  * virtual
 767  * resident (amount of memory used by the database process)
 768  * mapped
 769  * non mapped
 770
 771 13. **Page faults**:
 772  * page faults (number of times MongoDB had to request from disk)
 773
 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)
 777
 778 15. **Pages evicted from cache** (WiredTiger):
 779  * modified
 780  * unmodified
 781
 782 16. **Queued requests**:
 783  * readers (number of read request currently queued)
 784  * writers (number of write request currently queued)
 785
 786 17. **Errors**:
 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)
 791
 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)
 796
 797 19. **Documents in the database** (one chart for all databases)
 798  * documents (number of objects in the database among all the collections)
 799
 800 20. **tcmalloc metrics**
 801  * central cache free
 802  * current total thread cache
 803  * pageheap free
 804  * pageheap unmapped
 805  * thread cache free
 806  * transfer cache free
 807  * heap size
 808
 809 21. **Commands total/failed rate**
 810  * count
 811  * createIndex
 812  * delete
 813  * eval
 814  * findAndModify
 815  * insert
 816
 817 22. **Locks metrics** (acquireCount metrics - number of times the lock was acquired in the specified mode)
 818  * Global lock
 819  * Database lock
 820  * Collection lock
 821  * Metadata lock
 822  * oplog lock
 823
 824 23. **Replica set members state**
 825  * state
 826
 827 24. **Oplog window**
 828   * window (interval of time between the oldest and the latest entries in the oplog)
 829
 830 25. **Replication lag**
 831   * member (time when last entry from the oplog was applied for every member)
 832
 833 26. **Replication set member heartbeat latency**
 834   * member (time when last heartbeat was received from replica set member)
 835
 836
 837 ### configuration
 838
 839 Sample:
 840
 841 ```yaml
 842 local:
 843     name : 'local'
 844     host : '127.0.0.1'
 845     port : 27017
 846     user : 'netdata'
 847     pass : 'netdata'
 848
 849 ```
 850
 851 If no configuration is given, module will attempt to connect to mongodb daemon on `127.0.0.1:27017` address
 852
 853 ---
 854
 855
 856 # mysql
 857
 858 Module monitors one or more mysql servers
 859
 860 **Requirements:**
 861  * python library [MySQLdb](https://github.com/PyMySQL/mysqlclient-python) (faster) or [PyMySQL](https://github.com/PyMySQL/PyMySQL) (slower)
 862
 863 It will produce following charts (if data is available):
 864
 865 1. **Bandwidth** in kbps
 866  * in
 867  * out
 868
 869 2. **Queries** in queries/sec
 870  * queries
 871  * questions
 872  * slow queries
 873
 874 3. **Operations** in operations/sec
 875  * opened tables
 876  * flush
 877  * commit
 878  * delete
 879  * prepare
 880  * read first
 881  * read key
 882  * read next
 883  * read prev
 884  * read random
 885  * read random next
 886  * rollback
 887  * save point
 888  * update
 889  * write
 890
 891 4. **Table Locks** in locks/sec
 892  * immediate
 893  * waited
 894
 895 5. **Select Issues** in issues/sec
 896  * full join
 897  * full range join
 898  * range
 899  * range check
 900  * scan
 901
 902 6. **Sort Issues** in issues/sec
 903  * merge passes
 904  * range
 905  * scan
 906
 907 ### configuration
 908
 909 You can provide, per server, the following:
 910
 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)
 917
 918 Here is an example for 3 servers:
 919
 920 ```yaml
 921 update_every : 10
 922 priority     : 90100
 923 retries      : 5
 924
 925 local:
 926   'my.cnf'   : '/etc/mysql/my.cnf'
 927   priority   : 90000
 928
 929 local_2:
 930   user     : 'root'
 931   pass : 'blablablabla'
 932   socket   : '/var/run/mysqld/mysqld.sock'
 933   update_every : 1
 934
 935 remote:
 936   user     : 'admin'
 937   pass : 'bla'
 938   host     : 'example.org'
 939   port     : 9000
 940   retries  : 20
 941 ```
 942
 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`
 944
 945 ---
 946
 947 # nginx
 948
 949 This module will monitor one or more nginx servers depending on configuration. Servers can be either local or remote.
 950
 951 **Requirements:**
 952  * nginx with configured 'ngx_http_stub_status_module'
 953  * 'location /stub_status'
 954
 955 Example nginx configuration can be found in 'python.d/nginx.conf'
 956
 957 It produces following charts:
 958
 959 1. **Active Connections**
 960  * active
 961
 962 2. **Requests** in requests/s
 963  * requests
 964
 965 3. **Active Connections by Status**
 966  * reading
 967  * writing
 968  * waiting
 969
 970 4. **Connections Rate** in connections/s
 971  * accepts
 972  * handled
 973
 974 ### configuration
 975
 976 Needs only `url` to server's `stub_status`
 977
 978 Here is an example for local server:
 979
 980 ```yaml
 981 update_every : 10
 982 priority     : 90100
 983
 984 local:
 985   url     : 'http://localhost/stub_status'
 986   retries : 10
 987 ```
 988
 989 Without configuration, module attempts to connect to `http://localhost/stub_status`
 990
 991 ---
 992
 993 # nginx_log
 994
 995 Module monitors nginx access log and produces only one chart:
 996
 997 1. **nginx status codes** in requests/s
 998  * 2xx
 999  * 3xx
1000  * 4xx
1001  * 5xx
1002
1003 ### configuration
1004
1005 Sample for two vhosts:
1006
1007 ```yaml
1008 site_A:
1009   path: '/var/log/nginx/access-A.log'
1010
1011 site_B:
1012   name: 'local'
1013   path: '/var/log/nginx/access-B.log'
1014 ```
1015
1016 When no configuration file is found, module tries to parse `/var/log/nginx/access.log` file.
1017
1018 ---
1019
1020 # nsd
1021
1022 Module uses the `nsd-control stats_noreset` command to provide `nsd` statistics.
1023
1024 **Requirements:**
1025  * Version of `nsd` must be 4.0+
1026  * Netdata must have permissions to run `nsd-control stats_noreset`
1027
1028 It produces:
1029
1030 1. **Queries**
1031  * queries
1032
1033 2. **Zones**
1034  * master
1035  * slave
1036
1037 3. **Protocol**
1038  * udp
1039  * udp6
1040  * tcp
1041  * tcp6
1042
1043 4. **Query Type**
1044  * A
1045  * NS
1046  * CNAME
1047  * SOA
1048  * PTR
1049  * HINFO
1050  * MX
1051  * NAPTR
1052  * TXT
1053  * AAAA
1054  * SRV
1055  * ANY
1056
1057 5. **Transfer**
1058  * NOTIFY
1059  * AXFR
1060
1061 6. **Return Code**
1062  * NOERROR
1063  * FORMERR
1064  * SERVFAIL
1065  * NXDOMAIN
1066  * NOTIMP
1067  * REFUSED
1068  * YXDOMAIN
1069
1070
1071 Configuration is not needed.
1072
1073 ---
1074
1075 # ovpn_status_log
1076
1077 Module monitor openvpn-status log file.
1078
1079 **Requirements:**
1080
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.
1083
1084  * Make sure NETDATA USER CAN READ openvpn-status.log
1085
1086  * Update_every interval MUST MATCH interval on which OpenVPN writes operational status to log file.
1087
1088 It produces:
1089
1090 1. **Users** OpenVPN active users
1091  * users
1092
1093 2. **Traffic** OpenVPN overall bandwidth usage in kilobit/s
1094  * in
1095  * out
1096
1097 ### configuration
1098
1099 Sample:
1100
1101 ```yaml
1102 default
1103  log_path     : '/var/log/openvpn-status.log'
1104 ```
1105
1106 ---
1107
1108 # phpfpm
1109
1110 This module will monitor one or more php-fpm instances depending on configuration.
1111
1112 **Requirements:**
1113  * php-fpm with enabled `status` page
1114  * access to `status` page via web server
1115
1116 It produces following charts:
1117
1118 1. **Active Connections**
1119  * active
1120  * maxActive
1121  * idle
1122
1123 2. **Requests** in requests/s
1124  * requests
1125
1126 3. **Performance**
1127  * reached
1128  * slow
1129
1130 ### configuration
1131
1132 Needs only `url` to server's `status`
1133
1134 Here is an example for local instance:
1135
1136 ```yaml
1137 update_every : 3
1138 priority     : 90100
1139
1140 local:
1141   url     : 'http://localhost/status'
1142   retries : 10
1143 ```
1144
1145 Without configuration, module attempts to connect to `http://localhost/status`
1146
1147 ---
1148
1149 # postfix
1150
1151 Simple module executing `postfix -p` to grab postfix queue.
1152
1153 It produces only two charts:
1154
1155 1. **Postfix Queue Emails**
1156  * emails
1157
1158 2. **Postfix Queue Emails Size** in KB
1159  * size
1160
1161 Configuration is not needed.
1162
1163 ---
1164
1165 # redis
1166
1167 Get INFO data from redis instance.
1168
1169 Following charts are drawn:
1170
1171 1. **Operations** per second
1172  * operations
1173
1174 2. **Hit rate** in percent
1175  * rate
1176
1177 3. **Memory utilization** in kilobytes
1178  * total
1179  * lua
1180
1181 4. **Database keys**
1182  * lines are creates dynamically based on how many databases are there
1183
1184 5. **Clients**
1185  * connected
1186  * blocked
1187
1188 6. **Slaves**
1189  * connected
1190
1191 ### configuration
1192
1193 ```yaml
1194 socket:
1195   name     : 'local'
1196   socket   : '/var/lib/redis/redis.sock'
1197
1198 localhost:
1199   name     : 'local'
1200   host     : 'localhost'
1201   port     : 6379
1202 ```
1203
1204 When no configuration file is found, module tries to connect to TCP/IP socket: `localhost:6379`.
1205
1206 ---
1207
1208 # sensors
1209
1210 System sensors information.
1211
1212 Charts are created dynamically.
1213
1214 ### configuration
1215
1216 For detailed configuration information please read [`sensors.conf`](https://github.com/firehol/netdata/blob/master/conf.d/python.d/sensors.conf) file.
1217
1218 ---
1219
1220 # squid
1221
1222 This module will monitor one or more squid instances depending on configuration.
1223
1224 It produces following charts:
1225
1226 1. **Client Bandwidth** in kilobits/s
1227  * in
1228  * out
1229  * hits
1230
1231 2. **Client Requests** in requests/s
1232  * requests
1233  * hits
1234  * errors
1235
1236 3. **Server Bandwidth** in kilobits/s
1237  * in
1238  * out
1239
1240 4. **Server Requests** in requests/s
1241  * requests
1242  * errors
1243
1244 ### configuration
1245
1246 ```yaml
1247 priority     : 50000
1248
1249 local:
1250   request : 'cache_object://localhost:3128/counters'
1251   host    : 'localhost'
1252   port    : 3128
1253 ```
1254
1255 Without any configuration module will try to autodetect where squid presents its `counters` data
1256
1257 ---
1258
1259 # tomcat
1260
1261 Present tomcat containers memory utilization.
1262
1263 Charts:
1264
1265 1. **Requests** per second
1266  * accesses
1267
1268 2. **Volume** in KB/s
1269  * volume
1270
1271 3. **Threads**
1272  * current
1273  * busy
1274
1275 4. **JVM Free Memory** in MB
1276  * jvm
1277
1278 ### configuration
1279
1280 ```yaml
1281 localhost:
1282   name : 'local'
1283   url  : 'http://127.0.0.1:8080/manager/status?XML=true'
1284   user : 'tomcat_username'
1285   pass : 'secret_tomcat_password'
1286 ```
1287
1288 Without configuration, module attempts to connect to `http://localhost:8080/manager/status?XML=true`, without any credentials.
1289 So it will probably fail.
1290
1291 ---
1292
1293 # varnish cache
1294
1295 Module uses the `varnishstat` command to provide varnish cache statistics.
1296
1297 It produces:
1298
1299 1. **Client metrics**
1300  * session accepted
1301  * session dropped
1302  * good client requests received
1303
1304 2. **All history hit rate ratio**
1305  * cache hits in percent
1306  * cache miss in percent
1307  * cache hits for pass percent
1308
1309 3. **Curent poll hit rate ratio**
1310  * cache hits in percent
1311  * cache miss in percent
1312  * cache hits for pass percent
1313
1314 4. **Thread-related metrics** (only for varnish version 4+)
1315  * total number of threads
1316  * threads created
1317  * threads creation failed
1318  * threads hit max
1319  * length os session queue
1320  * sessions queued for thread
1321
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
1331
1332 6. **Memory usage**
1333  * memory available in megabytes
1334  * memory allocated in megabytes
1335
1336 7. **Problems summary**
1337  * session dropped
1338  * session accept failures
1339  * session pipe overflow
1340  * backend conn. not attempted
1341  * fetch failed (all causes)
1342  * backend conn. too many
1343  * threads hit max
1344  * threads destroyed
1345  * length of session queue
1346  * HTTP header overflows
1347  * ESI parse errors
1348  * ESI parse warnings
1349
1350 8. **Uptime**
1351  * varnish instance uptime in seconds
1352
1353 ### configuration
1354
1355 No configuration is needed.
1356
1357 ---