python.d/README.md

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