src/collectd-python.pod

   1 =head1 NAME
   2
   3 collectd-python - Documentation of collectd's C<python plugin>
   4
   5 =head1 SYNOPSIS
   6
   7   <LoadPlugin python>
   8     Globals true
   9   </LoadPlugin>
  10   # ...
  11   <Plugin python>
  12     ModulePath "/path/to/your/python/modules"
  13     LogTraces true
  14     Interactive true
  15     Import "spam"
  16
  17     <Module spam>
  18       spam "wonderful" "lovely"
  19     </Module>
  20   </Plugin>
  21
  22 =head1 DESCRIPTION
  23
  24 The C<python plugin> embeds a Python-interpreter into collectd and provides an
  25 interface to collectd's plugin system. This makes it possible to write plugins
  26 for collectd in Python. This is a lot more efficient than executing a
  27 Python-script every time you want to read a value with the C<exec plugin> (see
  28 L<collectd-exec(5)>) and provides a lot more functionality, too.
  29
  30 Currently only python2 is supported and at least version 2.3 is required.
  31
  32 =head1 CONFIGURATION
  33
  34 =over 4
  35
  36 =item B<LoadPlugin> I<Plugin>
  37
  38 Loads the Python plugin I<Plugin>. Unlike most other LoadPlugin lines, this one
  39 should be a block containing the line "Globals true". This will cause collectd
  40 to export the name of all objects in the python interpreter for all plugins to
  41 see. If you don't do this or your platform does not support it, the embeded
  42 interpreter will start anywa but you won't be able to load certain python
  43 modules, e.g. "time".
  44
  45 =item B<Encoding> I<Name>
  46
  47 The default encoding for unicode objects you pass to collectd. If you obmit
  48 this option it will default to B<ascii> on python2 and B<utf-8> on python3.
  49 This is hardcoded in python and will ignore everything else, including your
  50 locale.
  51
  52 =item B<ModulePath> I<Name>
  53
  54 Appends I<Name> to B<sys.path>. You won't be able to import any scripts you
  55 wrote unless they are located in one of the directuries in this list. Please
  56 note that it only has effect on plugins loaded after this option.
  57
  58 =item B<LogTraces> I<bool>
  59
  60 If a python script throws an exception it will be logged by collectd with the
  61 name of the exception and the message. If you set this option to true it will
  62 also log the full stacktrace just like the default output of an interactive
  63 python interpreter. This should probably be set to false most of the time but
  64 is very useful for development and debugging of new modules.
  65
  66 =item B<Interactive> I<bool>
  67
  68 This option will causethe module to launch an interactive python interpreter
  69 that reads from and writes to the terminal. Note that collectd will terminate
  70 right after starting up if you try to run it as a daemon while this option is
  71 enabled to make sure to start collectd with the B<-f> option.
  72
  73 The B<collectd> module is I<not> imported into the interpreter's globals. You
  74 have to do it manually. Be sure to read the help text of the module, it can be
  75 used as a reference guide during coding.
  76
  77 This interactive session will behave slightly differently from a daemonized
  78 collectd script as well as from a normal python interpreter:
  79 1. collectd will try to import the B<readline> module to give you a decent
  80 way of entering your commmands. The daemonized collectd won't do that.
  81 2. collectd will block SIGINT. Pressing Ctrl+C will usually cause collectd to
  82 shut down. This would be problematic in an interactive session, therefore this
  83 signal will be blocked. You can still use it to interrupt syscalls like sleep
  84 and pause but it won't generate a KeyboardInterrupt exception either.
  85
  86 To quit collectd send EOF (press Ctrl+D at the beginning of a new line).
  87
  88 =item E<lt>B<Module> I<Name>E<gt> block
  89
  90 This block may be used to pass on configuration settings to a Python module.
  91 The configuration is converted into an instance of the B<Config> class which
  92 is passed to the registered configuration callback. See below for details about
  93 the B<Config> class and how to register callbacks.
  94
  95 The I<name> identifies the callback.
  96
  97 =back
  98
  99 =head1 WRITING YOUR OWN PLUGINS
 100
 101 Writing your own plugins is quite simple. collectd manages plugins by means of
 102 B<dispatch functions> which call the appropriate B<callback functions>
 103 registered by the plugins. Any plugin basically consists of the implementation
 104 of these callback functions and initializing code which registers the
 105 functions with collectd. See the section "EXAMPLES" below for a really basic
 106 example. The following types of B<callback functions> are known to collectd
 107 (all of them are optional):
 108
 109 =over 4
 110
 111 =item configuration functions
 112
 113 This type of functions is called during configuration if an appropriate
 114 B<Module> block has been encountered. It is called once for each B<Module>
 115 block which matches the name of the callback as provided with the
 116 B<register_config> method - see below.
 117
 118 Python thread support has not been initialized at this point so do not use any
 119 threading functions here!
 120
 121 =item init functions
 122
 123 This type of functions is called once after loading the module and before any
 124 calls to the read and write functions. It should be used to initialize the
 125 internal state of the plugin (e.E<nbsp>g. open sockets, ...). This is the
 126 earliest point where you may use threads.
 127
 128 =item read functions
 129
 130 This type of function is used to collect the actual data. It is called once
 131 per interval (see the B<Interval> configuration option of collectd). Usually
 132 it will call B<plugin_dispatch_values> to dispatch the values to collectd
 133 which will pass them on to all registered B<write functions>. If this function
 134 throws any kind of exception the plugin will be skipped for an increasing
 135 amount of time until it returns normally again.
 136
 137 =item write functions
 138
 139 This type of function is used to write the dispatched values. It is called
 140 once for every value that was dispatched by any plugin.
 141
 142 =item flush functions
 143
 144 This type of function is used to flush internal caches of plugins. It is
 145 usually triggered by the user only. Any plugin which caches data before
 146 writing it to disk should provide this kind of callback function.
 147
 148 =item log functions
 149
 150 This type of function is used to pass messages of plugins or the daemon itself
 151 to the user.
 152
 153 =item notification function
 154
 155 This type of function is used to act upon notifications. In general, a
 156 notification is a status message that may be associated with a data instance.
 157 Usually, a notification is generated by the daemon if a configured threshold
 158 has been exceeded (see the section "THRESHOLD CONFIGURATION" in
 159 L<collectd.conf(5)> for more details), but any plugin may dispatch
 160 notifications as well.
 161
 162 =item shutdown functions
 163
 164 This type of function is called once before the daemon shuts down. It should
 165 be used to clean up the plugin (e.g. close sockets, ...).
 166
 167 =back
 168
 169 Any function (except log functions) may set throw an exception in case of any
 170 errors. The exception will be passed on to the user using collectd's logging
 171 mechanism. If a log callback throws an exception it will be printed to stderr
 172 instead.
 173
 174 See the documentation of the various B<register_> methods in the section
 175 "FUNCTIONS" below for the number and types of arguments passed to each
 176 B<callback function>. This section also explains how to register B<callback
 177 functions> with collectd.
 178
 179 To enable a module, copy it to a place where Python can find it (i.E<nbsp>e. a
 180 directory listed in B<sys.path>) just as any other Python plugin and add
 181 an appropriate B<Import> option to the configuration file. After restarting
 182 collectd you're done.
 183
 184 =head1 CLASSES
 185
 186 The following complex types are used to pass values between the Python plugin
 187 and collectd:
 188
 189 =head2 Config
 190
 191 The Config class is an object which keeps the informations provided in the
 192 configuration file. The sequence of children keeps one entry for each
 193 configuration option. Each such entry is another Config instance, which
 194 may nest further if nested blocks are used.
 195
 196  class Config(object)
 197
 198 This represents a piece of collectd's config file. It is passed to scripts with
 199 config callbacks (see B<register_config>) and is of little use if created
 200 somewhere else.
 201
 202 It has no methods beyond the bare minimum and only exists for its data members.
 203
 204 Data descriptors defined here:
 205
 206 =over 4
 207
 208 =item parent
 209
 210 This represents the parent of this node. On the root node
 211 of the config tree it will be None.
 212
 213 =item key
 214
 215 This is the keyword of this item, ie the first word of any given line in the
 216 config file. It will always be a string.
 217
 218 =item values
 219
 220 This is a tuple (which might be empty) of all value, ie words following the
 221 keyword in any given line in the config file.
 222
 223 Every item in this tuple will be either a string or a float or a bool,
 224 depending on the contents of the configuration file.
 225
 226 =item children
 227
 228 This is a tuple of child nodes. For most nodes this will be empty. If this node
 229 represents a block instead of a single line of the config file it will contain
 230 all nodes in this block.
 231
 232 =back
 233
 234 =head2 PluginData
 235
 236 This should not be used directly but it is the base class for both Values and
 237 Notification. It is used to identify the source of a value or notification.
 238
 239  class PluginData(object)
 240
 241 This is an internal class that is the base for Values and Notification. It is
 242 pretty useless by itself and was therefore not exported to the collectd module.
 243
 244 Data descriptors defined here:
 245
 246 =over 4
 247
 248 =item host
 249
 250 The hostname of the host this value was read from. For dispatching this can be
 251 set to an empty string which means the local hostname as defined in
 252 collectd.conf.
 253
 254 =item plugin
 255
 256 The name of the plugin that read the data. Setting this member to an empty
 257 string will insert "python" upon dispatching.
 258
 259 =item plugin_instance
 260
 261 Plugin instance string. May be empty.
 262
 263 =item time
 264
 265 This is the Unix timestamp of the time this value was read. For dispatching
 266 values this can be set to zero which means "now". This means the time the value
 267 is actually dispatched, not the time it was set to 0.
 268
 269 =item type
 270
 271 The type of this value. This type has to be defined in your I<types.db>.
 272 Attempting to set it to any other value will raise a I<TypeError> exception.
 273 Assigning a type is mandatory, calling dispatch without doing so will raise a
 274 I<RuntimeError> exception.
 275
 276 =item type_instance
 277
 278 Type instance string. May be empty.
 279
 280 =back
 281
 282 =head2 Values
 283
 284 A Value is an object which features a sequence of values. It is based on then
 285 I<PluginData> type and uses its members to identify the values.
 286
 287  class Values(PluginData)
 288
 289 A Values object used for dispatching values to collectd and receiving values
 290 from write callbacks.
 291
 292 Method resolution order:
 293
 294 =over 4
 295
 296 =item Values
 297
 298 =item PluginData
 299
 300 =item object
 301
 302 =back
 303
 304 Methods defined here:
 305
 306 =over 4
 307
 308 =item B<dispatch>([type][, values][, plugin_instance][, type_instance][, plugin][, host][, time][, interval]) -> None.
 309
 310 Dispatch this instance to the collectd process. The object has members for each
 311 of the possible arguments for this method. For a detailed explanation of these
 312 parameters see the member of the same same.
 313
 314 If you do not submit a parameter the value saved in its member will be
 315 submitted. If you do provide a parameter it will be used instead, without
 316 altering the member.
 317
 318 =item B<write>([destination][, type][, values][, plugin_instance][, type_instance][, plugin][, host][, time][, interval]) -> None.
 319
 320 Write this instance to a single plugin or all plugins if "destination" is
 321 omitted. This will bypass the main collectd process and all filtering and
 322 caching. Other than that it works similar to "dispatch". In most cases
 323 "dispatch" should be used instead of "write".
 324
 325 =back
 326
 327 Data descriptors defined here:
 328
 329 =over 4
 330
 331 =item interval
 332
 333 The interval is the timespan in seconds between two submits for the same data
 334 source. This value has to be a positive integer, so you can't submit more than
 335 one value per second. If this member is set to a non-positive value, the
 336 default value as specified in the config file will be used (default: 10).
 337
 338 If you submit values more often than the specified interval, the average will
 339 be used. If you submit less values, your graphs will have gaps.
 340
 341 =item values
 342
 343 These are the actual values that get dispatched to collectd. It has to be a
 344 sequence (a tuple or list) of numbers. The size of the sequence and the type of
 345 its content depend on the type member your I<types.db> file. For more
 346 information on this read the L<types.db(5)> manual page.
 347
 348 If the sequence does not have the correct size upon dispatch a I<RuntimeError>
 349 exception will be raised. If the content of the sequence is not a number, a
 350 I<TypeError> exception will be raised.
 351
 352 =back
 353
 354 =head2 Notification
 355
 356 A notification is an object defining the severity and message of the status
 357 message as well as an identification of a data instance by means of the members
 358 of PluginData on which it is based.
 359
 360 class Notification(PluginData)
 361 The Notification class is a wrapper around the collectd notification.
 362 It can be used to notify other plugins about bad stuff happening. It works
 363 similar to Values but has a severity and a message instead of interval
 364 and time.
 365 Notifications can be dispatched at any time and can be received with
 366 register_notification.
 367
 368 Method resolution order:
 369
 370 =over 4
 371
 372 =item Notification
 373
 374 =item PluginData
 375
 376 =item object
 377
 378 =back
 379
 380 Methods defined here:
 381
 382 =over 4
 383
 384 =item B<dispatch>([type][, values][, plugin_instance][, type_instance][, plugin][, host][, time][, interval]) -> None.  Dispatch a value list.
 385
 386 Dispatch this instance to the collectd process. The object has members for each
 387 of the possible arguments for this method. For a detailed explanation of these
 388 parameters see the member of the same same.
 389
 390 If you do not submit a parameter the value saved in its member will be
 391 submitted. If you do provide a parameter it will be used instead, without
 392 altering the member.
 393
 394 =back
 395
 396 Data descriptors defined here:
 397
 398 =over 4
 399
 400 =item message
 401
 402 Some kind of description what's going on and why this Notification was
 403 generated.
 404
 405 =item severity
 406
 407 The severity of this notification. Assign or compare to I<NOTIF_FAILURE>,
 408 I<NOTIF_WARNING> or I<NOTIF_OKAY>.
 409
 410 =back
 411
 412 =head1 FUNCTIONS
 413
 414 The following functions provide the C-interface to Python-modules.
 415
 416 =over 4
 417
 418 =item B<register_*>(I<callback>[, I<data>][, I<name>]) -> identifier
 419
 420 There are eight different register functions to get callback for eight
 421 different events. With one exception all of them are called as shown above.
 422
 423 =over 4
 424
 425 =item
 426
 427 I<callback> is a callable object that will be called every time the event is
 428 triggered.
 429
 430 =item
 431
 432 I<data> is an optional object that will be passed back to the callback function
 433 every time it is called. If you obmit this parameter no object is passed back
 434 to your callback, not even None.
 435
 436 =item
 437
 438 I<name> is an optional identifier for this callback. The default name is
 439 B<python>.I<module>. I<module> is taken from the B<__module__> attribute of
 440 your callback function. Every callback needs a unique identifier, so if you
 441 want to register the same callback multiple time in the same module you need to
 442 specify a name here. Otherwise it's save to ignore this parameter I<identifier>
 443 is the full identifier assigned to this callback.
 444
 445 =back
 446
 447 These functions are called in the various stages of the daemon (see the section
 448 L<"WRITING YOUR OWN PLUGINS"> above) and are passed the following arguments:
 449
 450 =over 4
 451
 452 =item register_config
 453
 454 The only argument passed is a I<Config> object. See above for the layout of this
 455 data type.
 456 Note that you can not receive the whole config files this way, only B<Module>
 457 blocks inside the Python configuration block. Additionally you will only
 458 receive blocks where your callback identifier matches B<python.>I<blockname>.
 459
 460 =item register_init
 461
 462 The callback will be called without arguments.
 463
 464 =item register_read(callback[, interval][, data][, name]) -> identifier
 465
 466 This function takes an additional parameter: I<interval>. It specifies the
 467 time between calls to the callback function.
 468
 469 The callback will be called without arguments.
 470
 471 =item register_shutdown
 472
 473 The callback will be called without arguments.
 474
 475 =item register_write
 476
 477 The callback function will be called with one arguments passed, which will be a
 478 I<Values> object. For the layout of I<Values> see above.
 479 If this callback function throws an exception the next call will be delayed by
 480 an increasing interval.
 481
 482 =item register_flush
 483
 484 Like B<register_config> is important for this callbavk because it determines
 485 what flush requests the plugin will receive.
 486
 487 The arguments passed are I<timeout> and I<identifier>. I<timeout> indicates
 488 that only data older than I<timeout> seconds is to be flushed. I<identifier>
 489 specifies which values are to be flushed.
 490
 491 =item register_log
 492
 493 The arguments are I<severity> and I<message>. The severity is an integer and
 494 small for important messages and high for less important messages. The least
 495 important level is B<LOG_DEBUG>, the most important level is B<LOG_ERR>. In
 496 between there are (from least to most important): B<LOG_INFO>, B<LOG_NOTICE>,
 497 and B<LOG_WARNING>. I<message> is simply a string B<without> a newline at the
 498 end.
 499
 500 If this callback throws an exception it will B<not> be logged. It will just be
 501 printed to sys.stderr which usually means silently ignored.
 502
 503 =item register_notification
 504
 505 The only argument passed is a I<Notification> object. See above for the layout of this
 506 data type.
 507
 508 =back
 509
 510 =item B<unregister_*>(I<identifier>) -> None
 511
 512 Removes a callback or data-set from collectd's internal list of callback
 513 functions. Every register_* function has an unregister_* function. I<identifier>
 514 is either the string that was returned by the register function or a callback
 515 function. The identifier will be constructed in the same way as for the
 516 register functions.
 517
 518 =item B<flush>(I<plugin[, I<timeout>][, I<identifier>]) -> None
 519
 520 Flush one or all plugins. I<timeout> and the specified I<identifiers> are
 521 passed on to the registered flush-callbacks. If omitted, the timeout defaults
 522 to C<-1>. The identifier defaults to None. If the B<plugin> argument has been
 523 specified, only named plugin will be flushed.
 524
 525 =item B<error>, B<warning>, B<notice>, B<info>, B<debug>(I<message>)
 526
 527 Log a message with the specified severity.
 528
 529 =back
 530
 531 =head1 EXAMPLES
 532
 533 Any Python module will start similar to:
 534
 535   import collectd
 536
 537 A very simple read function might look like:
 538
 539   def read(data=None):
 540     vl = collectd.Values(type='gauge')
 541     vl.plugin='python.spam'
 542     vl.dispatch(values=[random.random() * 100])
 543
 544 A very simple write function might look like:
 545
 546   def write(vl, data=None):
 547     for i in vl.values:
 548       print "%s (%s): %f" % (vl.plugin, vl.type, i)
 549
 550 To register those functions with collectd:
 551
 552   collectd.register_read(read);
 553   collectd.register_write(write);
 554
 555 See the section L<"CLASSES"> above for a complete documentation of the data
 556 types used by the read, write and match functions.
 557
 558 =head1 NOTES
 559
 560 =over 4
 561
 562 =item
 563
 564 Please feel free to send in new plugins to collectd's mailinglist at
 565 E<lt>collectdE<nbsp>atE<nbsp>verplant.orgE<gt> for review and, possibly,
 566 inclusion in the main distribution. In the latter case, we will take care of
 567 keeping the plugin up to date and adapting it to new versions of collectd.
 568
 569 Before submitting your plugin, please take a look at
 570 L<http://collectd.org/dev-info.shtml>.
 571
 572 =back
 573
 574 =head1 CAVEATS
 575
 576 =over 4
 577
 578 =item
 579
 580 collectd is heavily multi-threaded. Each collectd thread accessing the python
 581 plugin will be mapped to a Python interpreter thread. Any such thread will be
 582 created and destroyed transparently and on-the-fly.
 583
 584 Hence, any plugin has to be thread-safe if it provides several entry points
 585 from collectd (i.E<nbsp>e. if it registers more than one callback or if a
 586 registered callback may be called more than once in parallel).
 587
 588 =item
 589
 590 The Python thread module is initialized just before calling the init callbacks.
 591 This means you must not use Python's threading module prior to this point. This
 592 includes all config and possibly other callback as well.
 593
 594 =item
 595
 596 The python plugin exports the internal API of collectd which is considered
 597 unstable and subject to change at any time. We try hard to not break backwards
 598 compatibility in the Python API during the life cycle of one major release.
 599 However, this cannot be guaranteed at all times. Watch out for warnings
 600 dispatched by the python plugin after upgrades.
 601
 602 =back
 603
 604 =head1 KNOWN BUGS
 605
 606 =over 4
 607
 608 =item
 609
 610 This plugin is not compatible with python3. Trying to complie it with python3
 611 will fail because of the ways string, unicode and bytearray bahavior was
 612 changed.
 613
 614 Not all aspects of the collectd API are accessable from python. This includes
 615 but is not limited to meta-data, filters and data sets.
 616
 617 =back
 618
 619 =head1 SEE ALSO
 620
 621 L<collectd(1)>,
 622 L<collectd.conf(5)>,
 623 L<collectd-perl(5)>,
 624 L<collectd-exec(5)>,
 625 L<types.db(5)>,
 626 L<python(1)>,
 627
 628 =head1 AUTHOR
 629
 630 The C<python plugin> has been written by Sebastian Harl
 631 E<lt>shE<nbsp>atE<nbsp>tokkee.orgE<gt>.
 632
 633 This manpage has been written by Florian Forster
 634 E<lt>octoE<nbsp>atE<nbsp>verplant.orgE<gt> and Sebastian Harl
 635 E<lt>shE<nbsp>atE<nbsp>tokkee.orgE<gt>.
 636
 637 =cut
 638