python.d/README.md

   1 # Disclaimer
   2
   3 **Python support is experimental and implementation may change in the future**
   4
   5 Every module 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   other_var1   : some_val # module specific variable
  33
  34 other_job:
  35   priority     : 5 # job position on dashboard
  36   retries      : 20 # job retries
  37   other_var2   : val # module specific variable
  38 ```
  39
  40 `update_every`, `retries`, and `priority` are always optional.
  41
  42 ---
  43
  44 The following python.d modules are supported:
  45
  46 # apache
  47
  48 This module will monitor one or more apache servers depending on configuration.
  49
  50 **Requirements:**
  51  * apache with enabled `mod_status`
  52
  53 It produces following charts:
  54
  55 1. **Requests** in requests/s
  56  * requests
  57
  58 2. **Connections**
  59  * connections
  60
  61 3. **Async Connections**
  62  * keepalive
  63  * closing
  64  * writing
  65
  66 4. **Bandwidth** in kilobytes/s
  67  * sent
  68
  69 5. **Workers**
  70  * idle
  71  * busy
  72
  73 6. **Lifetime Avg. Requests/s** in requests/s
  74  * requests_sec
  75
  76 7. **Lifetime Avg. Bandwidth/s** in kilobytes/s
  77  * size_sec
  78
  79 8. **Lifetime Avg. Response Size** in bytes/request
  80  * size_req
  81
  82 ### configuration
  83
  84 Needs only `url` to server's `server-status?auto`
  85
  86 Here is an example for 2 servers:
  87
  88 ```yaml
  89 update_every : 10
  90 priority     : 90100
  91
  92 local:
  93   url      : 'http://localhost/server-status?auto'
  94   retries  : 20
  95
  96 remote:
  97   url          : 'http://www.apache.org/server-status?auto'
  98   update_every : 5
  99   retries      : 4
 100 ```
 101
 102 Without configuration, module attempts to connect to `http://localhost/server-status?auto`
 103
 104 ---
 105
 106 # apache_cache
 107
 108 Module monitors apache mod_cache log and produces only one chart:
 109
 110 **cached responses** in percent cached
 111  * hit
 112  * miss
 113  * other
 114
 115 ### configuration
 116
 117 Sample:
 118
 119 ```yaml
 120 update_every : 10
 121 priority     : 120000
 122 retries      : 5
 123 log_path     : '/var/log/apache2/cache.log'
 124 ```
 125
 126 If no configuration is given, module will attempt to read log file at `/var/log/apache2/cache.log`
 127
 128 ---
 129
 130 # hddtemp
 131
 132 Module monitors disk temperatures from one or more hddtemp daemons
 133
 134 **Requirement:**
 135 Running `hddtemp` in daemonized mode with access on tcp port
 136
 137 It produces one chart **Temperature** with dynamic number of dimensions (one per disk)
 138
 139 ### configuration
 140
 141 Sample:
 142
 143 ```yaml
 144 update_every: 3
 145 host: "127.0.0.1"
 146 port: 7634
 147 ```
 148
 149 If no configuration is given, module will attempt to connect to hddtemp daemon on `127.0.0.1:7634` address
 150
 151 ---
 152
 153 # mysql
 154
 155 Module monitors one or more mysql servers
 156
 157 **Requirements:**
 158  * python library [MySQLdb](https://github.com/PyMySQL/mysqlclient-python) (faster) or [PyMySQL](https://github.com/PyMySQL/PyMySQL) (slower)
 159
 160 It will produce following charts (if data is available):
 161
 162 1. **Bandwidth** in kbps
 163  * in
 164  * out
 165
 166 2. **Queries** in queries/sec
 167  * queries
 168  * questions
 169  * slow queries
 170
 171 3. **Operations** in operations/sec
 172  * opened tables
 173  * flush
 174  * commit
 175  * delete
 176  * prepare
 177  * read first
 178  * read key
 179  * read next
 180  * read prev
 181  * read random
 182  * read random next
 183  * rollback
 184  * save point
 185  * update
 186  * write
 187
 188 4. **Table Locks** in locks/sec
 189  * immediate
 190  * waited
 191
 192 5. **Select Issues** in issues/sec
 193  * full join
 194  * full range join
 195  * range
 196  * range check
 197  * scan
 198
 199 6. **Sort Issues** in issues/sec
 200  * merge passes
 201  * range
 202  * scan
 203
 204 ### configuration
 205
 206 You can provide, per server, the following:
 207
 208 1. username which have access to database (deafults to 'root')
 209 2. password (defaults to none)
 210 3. mysql my.cnf configuration file
 211 4. mysql socket (optional)
 212 5. mysql host (ip or hostname)
 213 6. mysql port (defaults to 3306)
 214
 215 Here is an example for 3 servers:
 216
 217 ```yaml
 218 update_every : 10
 219 priority     : 90100
 220 retries      : 5
 221
 222 local:
 223   'my.cnf'   : '/etc/mysql/my.cnf'
 224   priority   : 90000
 225
 226 local_2:
 227   user     : 'root'
 228   password : 'blablablabla'
 229   socket   : '/var/run/mysqld/mysqld.sock'
 230   update_every : 1
 231
 232 remote:
 233   user     : 'admin'
 234   password : 'bla'
 235   host     : 'example.org'
 236   port     : 9000
 237   retries  : 20
 238 ```
 239
 240 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`
 241
 242 ---
 243
 244 # nginx
 245
 246 This module will monitor one or more nginx servers depending on configuration.
 247
 248 **Requirements:**
 249  * nginx with configured `stub_status`
 250
 251 It produces following charts:
 252
 253 1. **Active Connections**
 254  * active
 255
 256 2. **Requests** in requests/s
 257  * requests
 258
 259 3. **Active Connections by Status**
 260  * reading
 261  * writing
 262  * waiting
 263
 264 4. **Connections Rate** in connections/s
 265  * accepts
 266  * handled
 267
 268 ### configuration
 269
 270 Needs only `url` to server's `stub_status`
 271
 272 Here is an example for local server:
 273
 274 ```yaml
 275 update_every : 10
 276 priority     : 90100
 277
 278 local:
 279   url     : 'http://localhost/stub_status'
 280   retries : 10
 281 ```
 282
 283 Without configuration, module attempts to connect to `http://localhost/stub_status`
 284
 285 ---
 286
 287 # phpfpm
 288
 289 This module will monitor one or more php-fpm instances depending on configuration.
 290
 291 **Requirements:**
 292  * php-fpm with enabled `status` page
 293  * access to `status` page via web server
 294
 295 It produces following charts:
 296
 297 1. **Active Connections**
 298  * active
 299  * maxActive
 300  * idle
 301
 302 2. **Requests** in requests/s
 303  * requests
 304
 305 3. **Performance**
 306  * reached
 307  * slow
 308
 309 ### configuration
 310
 311 Needs only `url` to server's `status`
 312
 313 Here is an example for local instance:
 314
 315 ```yaml
 316 update_every : 3
 317 priority     : 90100
 318
 319 local:
 320   url     : 'http://localhost/status'
 321   retries : 10
 322 ```
 323
 324 Without configuration, module attempts to connect to `http://localhost/status`
 325
 326 ---
 327
 328 # squid
 329
 330 This module will monitor one or more squid instances depending on configuration.
 331
 332 It produces following charts:
 333
 334 1. **Client Bandwidth** in kilobits/s
 335  * in
 336  * out
 337  * hits
 338
 339 2. **Client Requests** in requests/s
 340  * requests
 341  * hits
 342  * errors
 343
 344 3. **Server Bandwidth** in kilobits/s
 345  * in
 346  * out
 347
 348 4. **Server Requests** in requests/s
 349  * requests
 350  * errors
 351
 352 ### configuration
 353
 354 ```yaml
 355 priority     : 50000
 356
 357 local:
 358   request : 'cache_object://localhost:3128/counters'
 359   host    : 'localhost'
 360   port    : 3128
 361 ```
 362
 363 Without any configuration module will try to autodetect where squid presents its `counters` data
 364
 365 ---