python.d/README.md

   1 # Disclaimer
   2
   3 **Python plugin support is experimental and implementation may change in the future**
   4
   5 Every plugin should be compatible with python2 and python3.
   6 All third party libraries should be installed system-wide or in `python_modules` directory.
   7 Module configurations are written in YAML and **pyYAML is required**.
   8
   9 Every configuration file must have one of two formats:
  10
  11 - Configuration for only one job:
  12
  13 ```yaml
  14 update_every : 2 # update frequency
  15 retries      : 1 # how many failures in update() is tolerated
  16 priority     : 20000 # where it is shown on dashboard
  17
  18 other_var1   : bla  # variables passed to module
  19 other_var2   : alb
  20 ```
  21
  22 - Configuration for many jobs (ex. mysql):
  23
  24 ```yaml
  25 # module defaults:
  26 update_every : 2
  27 retries      : 1
  28 priority     : 20000
  29
  30 local:  # job name
  31   update_every : 5 # job update frequency
  32   retries      : 2 # job retries
  33   other_var1   : some_val # module specific variable
  34
  35 other_job:
  36   priority     : 5 # job position on dashboard
  37   retries      : 20 # job retries
  38   other_var2   : val # module specific variable
  39 ```
  40
  41 `update_every`, `retries`, and `priority` are always optional.
  42
  43 ---
  44
  45 The following python.d plugins are supported:
  46
  47 # mysql
  48
  49 The plugin will monitor one or more mysql servers
  50
  51 **Requirements:**
  52  * python module [MySQLdb](https://github.com/PyMySQL/mysqlclient-python) (faster) or [PyMySQL](https://github.com/PyMySQL/PyMySQL) (slower)
  53
  54 It will produce following charts (if data is available):
  55
  56 1. **Bandwidth** in kbps
  57  * in
  58  * out
  59
  60 2. **Queries** in queries/sec
  61  * queries
  62  * questions
  63  * slow queries
  64
  65 3. **Operations** in operations/sec
  66  * opened tables
  67  * flush
  68  * commit
  69  * delete
  70  * prepare
  71  * read first
  72  * read key
  73  * read next
  74  * read prev
  75  * read random
  76  * read random next
  77  * rollback
  78  * save point
  79  * update
  80  * write
  81
  82 4. **Table Locks** in locks/sec
  83  * immediate
  84  * waited
  85
  86 5. **Select Issues** in issues/sec
  87  * full join
  88  * full range join
  89  * range
  90  * range check
  91  * scan
  92
  93 6. **Sort Issues** in issues/sec
  94  * merge passes
  95  * range
  96  * scan
  97
  98 ### configuration
  99
 100 You can provide, per server, the following:
 101
 102 1. a name, anything you like, but keep it short
 103 2. username which have access to database (deafults to 'root')
 104 3. password (defaults to none)
 105 4. mysql my.cnf configuration file
 106 5. mysql socket (optional)
 107 6. mysql host (ip or hostname)
 108 7. mysql port (defaults to 3306)
 109
 110 Here is an example for 3 servers:
 111
 112 ```yaml
 113 update_every : 10
 114 priority     : 90100
 115 retries      : 5
 116
 117 local:
 118   'my.cnf'   : '/etc/mysql/my.cnf'
 119   priority   : 90000
 120
 121 local_2:
 122   user     : 'root'
 123   password : 'blablablabla'
 124   socket   : '/var/run/mysqld/mysqld.sock'
 125   update_every : 1
 126
 127 remote:
 128   user     : 'admin'
 129   password : 'bla'
 130   host     : 'example.org'
 131   port     : 9000
 132   retries  : 20
 133 ```
 134
 135 If no configuration is given, the plugin will attempt to connect to mysql server via unix socket at `/var/run/mysqld/mysqld.sock` without password and with username `root`
 136
 137 ---
 138