├── CHANGELOG.txt
├── LICENSE.txt
├── MANIFEST.in
├── README.txt
├── collectd.py
├── dist
    ├── collectd-1.0.1.tar.gz
    └── collectd-1.0.2.tar.gz
├── docs
    ├── .buildinfo
    ├── _sources
    │   └── index.txt
    ├── _static
    │   ├── basic.css
    │   ├── default.css
    │   ├── doctools.js
    │   ├── file.png
    │   ├── jquery.js
    │   ├── minus.png
    │   ├── plus.png
    │   ├── pygments.css
    │   ├── searchtools.js
    │   ├── sidebar.js
    │   └── underscore.js
    ├── genindex.html
    ├── index.html
    ├── objects.inv
    ├── search.html
    └── searchindex.js
├── examples
    ├── basic.py
    └── primes.py
├── setup.py
├── sphinx
    ├── Makefile
    ├── build
    │   └── doctrees
    │   │   ├── environment.pickle
    │   │   └── index.doctree
    ├── conf.py
    └── index.rst
└── unit_tests.py


/CHANGELOG.txt:
--------------------------------------------------------------------------------
 1 | 
 2 | WHAT'S NEW IN 1.0.2
 3 | -------------------
 4 | bugfix: Counter.record and Counter.set_exact now accept unicode values
 5 |     https://github.com/appliedsec/collectd/issues/2
 6 | 
 7 | feature: collectd.__version__ and collectd.__version_info__ are now defined
 8 | 
 9 | 
10 | 
11 | WHAT'S NEW IN 1.0.1
12 | -------------------
13 | hosting: collectd is now hosted on Github
14 |     https://github.com/appliedsec/collectd
15 | 
16 | bugfix: re-instantiating a Connection object causes __init__ to be called again
17 |     https://github.com/appliedsec/collectd/issues/1
18 | 
19 | feature: plugin name is now settable per Connection, "any" is still the default
20 |          (patch provided by Charles Hooper)
21 |     https://github.com/appliedsec/collectd/issues/2
22 | 


--------------------------------------------------------------------------------
/LICENSE.txt:
--------------------------------------------------------------------------------
 1 | Copyright (c) Eli Courtwright and other individual contributors.
 2 | All rights reserved.
 3 | 
 4 | Redistribution and use in source and binary forms, with or without modification,
 5 | are permitted provided that the following conditions are met:
 6 | 
 7 |     1. Redistributions of source code must retain the above copyright notice, 
 8 |        this list of conditions and the following disclaimer.
 9 |     
10 |     2. Redistributions in binary form must reproduce the above copyright 
11 |        notice, this list of conditions and the following disclaimer in the
12 |        documentation and/or other materials provided with the distribution.
13 | 
14 |     3. Neither the name of Eli Courtwright nor the names of other contributors
15 |        may be used to endorse or promote products derived from this software
16 |        without specific prior written permission.
17 | 
18 | THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
19 | ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
20 | WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
21 | DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
22 | ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
23 | (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
24 | LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
25 | ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
26 | (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
27 | SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
28 | 


--------------------------------------------------------------------------------
/MANIFEST.in:
--------------------------------------------------------------------------------
1 | include README.txt LICENSE.txt unit_tests.py
2 | recursive-include docs *
3 | recursive-include examples *.py
4 | 


--------------------------------------------------------------------------------
/README.txt:
--------------------------------------------------------------------------------
1 | This Python module implements the binary protocol used by the collectd Network 
2 | plugin to let you send arbitrary numeric data to collectd servers. Other than 
3 | turning on the Network plugin on the destination collectd server, no 
4 | configuration is needed.
5 | 
6 | Documentation may be found locally in the docs/ directory or online at
7 | http://packages.python.org/collectd/
8 | 


--------------------------------------------------------------------------------
/collectd.py:
--------------------------------------------------------------------------------
  1 | import re
  2 | import time
  3 | import socket
  4 | import struct
  5 | import logging
  6 | import traceback
  7 | from functools import wraps
  8 | from Queue import Queue, Empty
  9 | from collections import defaultdict
 10 | from threading import RLock, Thread, Semaphore
 11 | 
 12 | 
 13 | __all__ = ["Connection", "start_threads"]
 14 | 
 15 | __version_info__ = (1, 0, 2, "final", 0)
 16 | __version__ = "{0}.{1}.{2}".format(*__version_info__)
 17 | 
 18 | logger = logging.getLogger("collectd")
 19 | 
 20 | SEND_INTERVAL = 10      # seconds
 21 | MAX_PACKET_SIZE = 1024  # bytes
 22 | 
 23 | PLUGIN_TYPE = "gauge"
 24 | 
 25 | TYPE_HOST            = 0x0000
 26 | TYPE_TIME            = 0x0001
 27 | TYPE_PLUGIN          = 0x0002
 28 | TYPE_PLUGIN_INSTANCE = 0x0003
 29 | TYPE_TYPE            = 0x0004
 30 | TYPE_TYPE_INSTANCE   = 0x0005
 31 | TYPE_VALUES          = 0x0006
 32 | TYPE_INTERVAL        = 0x0007
 33 | LONG_INT_CODES = [TYPE_TIME, TYPE_INTERVAL]
 34 | STRING_CODES = [TYPE_HOST, TYPE_PLUGIN, TYPE_PLUGIN_INSTANCE, TYPE_TYPE, TYPE_TYPE_INSTANCE]
 35 | 
 36 | VALUE_COUNTER  = 0
 37 | VALUE_GAUGE    = 1
 38 | VALUE_DERIVE   = 2
 39 | VALUE_ABSOLUTE = 3
 40 | VALUE_CODES = {
 41 |     VALUE_COUNTER:  "!Q",
 42 |     VALUE_GAUGE:    "<d",
 43 |     VALUE_DERIVE:   "!q",
 44 |     VALUE_ABSOLUTE: "!Q"
 45 | }
 46 | 
 47 | 
 48 | def pack_numeric(type_code, number):
 49 |     return struct.pack("!HHq", type_code, 12, number)
 50 | 
 51 | def pack_string(type_code, string):
 52 |     return struct.pack("!HH", type_code, 5 + len(string)) + string + "\0"
 53 | 
 54 | def pack_value(name, value):
 55 |     return "".join([
 56 |         pack(TYPE_TYPE_INSTANCE, name),
 57 |         struct.pack("!HHH", TYPE_VALUES, 15, 1),
 58 |         struct.pack("<Bd", VALUE_GAUGE, value)
 59 |     ])
 60 | 
 61 | def pack(id, value):
 62 |     if isinstance(id, basestring):
 63 |         return pack_value(id, value)
 64 |     elif id in LONG_INT_CODES:
 65 |         return pack_numeric(id, value)
 66 |     elif id in STRING_CODES:
 67 |         return pack_string(id, value)
 68 |     else:
 69 |         raise AssertionError("invalid type code " + str(id))
 70 | 
 71 | def message_start(when=None, host=socket.gethostname(), plugin_inst="", plugin_name="any"):
 72 |     return "".join([
 73 |         pack(TYPE_HOST, host),
 74 |         pack(TYPE_TIME, when or time.time()),
 75 |         pack(TYPE_PLUGIN, plugin_name),
 76 |         pack(TYPE_PLUGIN_INSTANCE, plugin_inst),
 77 |         pack(TYPE_TYPE, PLUGIN_TYPE),
 78 |         pack(TYPE_INTERVAL, SEND_INTERVAL)
 79 |     ])
 80 | 
 81 | def messages(counts, when=None, host=socket.gethostname(), plugin_inst="", plugin_name="any"):
 82 |     packets = []
 83 |     start = message_start(when, host, plugin_inst, plugin_name)
 84 |     parts = [pack(name, count) for name,count in counts.items()]
 85 |     parts = [p for p in parts if len(start) + len(p) <= MAX_PACKET_SIZE]
 86 |     if parts:
 87 |         curr, curr_len = [start], len(start)
 88 |         for part in parts:
 89 |             if curr_len + len(part) > MAX_PACKET_SIZE:
 90 |                 packets.append("".join(curr))
 91 |                 curr, curr_len = [start], len(start)
 92 |             curr.append(part)
 93 |             curr_len += len(part)
 94 |         packets.append("".join(curr))
 95 |     return packets
 96 | 
 97 | 
 98 | 
 99 | def sanitize(s):
100 |     return re.sub(r"[^a-zA-Z0-9]+", "_", s).strip("_")
101 | 
102 | def swallow_errors(func):
103 |     @wraps(func)
104 |     def wrapped(*args, **kwargs):
105 |         try:
106 |             return func(*args, **kwargs)
107 |         except:
108 |             try:
109 |                 logger.error("unexpected error", exc_info = True)
110 |             except:
111 |                 pass
112 |     return wrapped
113 | 
114 | def synchronized(method):
115 |     @wraps(method)
116 |     def wrapped(self, *args, **kwargs):
117 |         with self._lock:
118 |             return method(self, *args, **kwargs)
119 |     return wrapped
120 | 
121 | class Counter(object):
122 |     def __init__(self, category):
123 |         self.category = category
124 |         self._lock = RLock()
125 |         self.counts = defaultdict(lambda: defaultdict(float))
126 |     
127 |     @swallow_errors
128 |     @synchronized
129 |     def record(self, *args, **kwargs):
130 |         for specific in list(args) + [""]:
131 |             assert isinstance(specific, basestring)
132 |             for stat, value in kwargs.items():
133 |                 assert isinstance(value, (int, float))
134 |                 self.counts[str(specific)][str(stat)] += value
135 |     
136 |     @swallow_errors
137 |     @synchronized
138 |     def set_exact(self, **kwargs):
139 |         for stat, value in kwargs.items():
140 |             assert isinstance(value, (int, float))
141 |             self.counts[""][str(stat)] = value
142 |     
143 |     @synchronized
144 |     def snapshot(self):
145 |         totals = {}
146 |         for specific,counts in self.counts.items():
147 |             for stat in counts:
148 |                 name_parts = map(sanitize, [self.category, specific, stat])
149 |                 name = "-".join(name_parts).replace("--", "-")
150 |                 totals[name] = counts[stat]
151 |                 counts[stat] = 0.0
152 |         return totals
153 | 
154 | class Connection(object):
155 |     _lock = RLock() # class-level lock, only used for __new__
156 |     instances = {}
157 |     
158 |     @synchronized
159 |     def __new__(cls, hostname = socket.gethostname(),
160 |                      collectd_host = "localhost", collectd_port = 25826,
161 |                      plugin_inst = "", plugin_name = "any"):
162 |         id = (hostname, collectd_host, collectd_port, plugin_inst, plugin_name)
163 |         if id in cls.instances:
164 |             return cls.instances[id]
165 |         else:
166 |             inst = object.__new__(cls)
167 |             cls.instances[id] = inst
168 |             return inst
169 |     
170 |     def __init__(self, hostname = socket.gethostname(),
171 |                        collectd_host = "localhost", collectd_port = 25826,
172 |                        plugin_inst = "", plugin_name = "any"):
173 |         if "_counters" not in self.__dict__:
174 |             self._lock = RLock()
175 |             self._counters = {}
176 |             self._plugin_inst = plugin_inst
177 |             self._plugin_name = plugin_name
178 |             self._hostname = hostname
179 |             self._collectd_addr = (collectd_host, collectd_port)
180 |     
181 |     @synchronized
182 |     def __getattr__(self, name):
183 |         if name.startswith("_"):
184 |             raise AttributeError("{0} object has no attribute {1!r}".format(self.__class__.__name__, name))
185 |         
186 |         if name not in self._counters:
187 |             self._counters[name] = Counter(name)
188 |         return self._counters[name]
189 |     
190 |     @synchronized
191 |     def _snapshot(self):
192 |         return [c.snapshot() for c in self._counters.values() if c.counts]
193 | 
194 | 
195 | 
196 | snaps = Queue()
197 | sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
198 | 
199 | def take_snapshots():
200 |     for conn in Connection.instances.values():
201 |         snapshots = conn._snapshot()
202 |         if snapshots:
203 |             stats = {}
204 |             for snapshot in snapshots:
205 |                 stats.update(snapshot)
206 |             snaps.put([int(time.time()), stats, conn])
207 | 
208 | def send_stats(raise_on_empty = False):
209 |     try:
210 |         when, stats, conn = snaps.get(timeout = 0.1)
211 |         for message in messages(stats, when, conn._hostname, conn._plugin_inst, conn._plugin_name):
212 |             sock.sendto(message, conn._collectd_addr)
213 |     except Empty:
214 |         if raise_on_empty:
215 |             raise
216 | 
217 | def daemonize(func, sleep_for = 0):
218 |     @wraps(func)
219 |     def wrapped():
220 |         while True:
221 |             try:
222 |                 func()
223 |             except:
224 |                 try:
225 |                     logger.error("unexpected error", exc_info = True)
226 |                 except:
227 |                     traceback.print_exc()
228 |             time.sleep(sleep_for)
229 |     
230 |     t = Thread(target = wrapped)
231 |     t.daemon = True
232 |     t.start()
233 | 
234 | single_start = Semaphore()
235 | def start_threads():
236 |     assert single_start.acquire(blocking = False)
237 |     daemonize(take_snapshots, sleep_for = SEND_INTERVAL)
238 |     daemonize(send_stats)
239 | 


--------------------------------------------------------------------------------
/dist/collectd-1.0.1.tar.gz:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/appliedsec/collectd/7b51edfd08e055149b446e9839c4dc0bc7c834ce/dist/collectd-1.0.1.tar.gz


--------------------------------------------------------------------------------
/dist/collectd-1.0.2.tar.gz:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/appliedsec/collectd/7b51edfd08e055149b446e9839c4dc0bc7c834ce/dist/collectd-1.0.2.tar.gz


--------------------------------------------------------------------------------
/docs/.buildinfo:
--------------------------------------------------------------------------------
1 | # Sphinx build info version 1
2 | # This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
3 | config: b152c99d1b53df289c844bb312cc7c8d
4 | tags: fbb0d17656682115ca4d033fb2f83ba1
5 | 


--------------------------------------------------------------------------------
/docs/_sources/index.txt:
--------------------------------------------------------------------------------
  1 | .. toctree::
  2 |     :maxdepth: 1
  3 | 
  4 | 
  5 | collectd - Send statistics over UDP to collectd servers
  6 | =======================================================
  7 | 
  8 | This module implements the
  9 | `binary protocol <http://collectd.org/wiki/index.php/Binary_protocol>`_
 10 | used by the
 11 | `Network plugin <http://collectd.org/wiki/index.php/Plugin:Network>`_
 12 | to let you send arbitrary numeric data to collectd servers.  Other than turning
 13 | on the Network plugin on the destination collectd server, no configuration is
 14 | needed.
 15 | 
 16 | Although you can configure your collectd server to do anything with your
 17 | statistics, most people use the
 18 | `RRDtool plugin <http://collectd.org/wiki/index.php/Plugin:RRDtool>`_
 19 | to efficiently store large quantities of data.  Therefore, this tutorial
 20 | will discuss the output files generated by the RRDtool plugin, even though
 21 | this module sends destination-agnostic statistics messages to your collectd
 22 | server.
 23 | 
 24 | Here's an example of sending statistics:
 25 | 
 26 | .. literalinclude:: ../examples/basic.py
 27 | 
 28 | If you run this script (which is ``examples/basic.py`` in your source package)
 29 | then your collectd server will create an RRD file for each statistic you are
 30 | tracking.  These files are typically stored under one central location on the
 31 | filesysem, such as ``/var/lib/collectd/rrd`` and organized by the hostname of
 32 | where the statistics came from and the name of the plugin that generated them.
 33 | 
 34 | This module identifies itself with the plugin name ``any``, so if you ran
 35 | the above script, it would create a ``localhost/any`` directory with the
 36 | following files:
 37 | 
 38 | * ``gauge-some_category-another_stat.rrd``
 39 | * ``gauge-some_category-some_counter.rrd``
 40 | * ``gauge-coin_stats-heads-flips.rrd``
 41 | * ``gauge-coin_stats-tails-flips.rrd``
 42 | * ``gauge-coin_stats-flips.rrd`` (contains the sum of heads and tails flips)
 43 | 
 44 | Each call to ``record()`` increments the statistics you provide.  Periodically
 45 | the sums of these statistics are sent to the collectd server and then reset.
 46 | Therefore, if you displayed a graph of one of these statistics files, each
 47 | data point on the graph would represent the sum of all ``record()`` values
 48 | over that time increment.
 49 | 
 50 | 
 51 | 
 52 | Installation
 53 | ============
 54 | This module is free for use under the BSD license.  It requires Python 2.6 or 
 55 | Python 2.7 and has no other dependencies.
 56 | 
 57 | You may `click here <https://github.com/downloads/appliedsec/collectd/collectd-1.0.1.tar.gz>`_
 58 | to  download the collectd module. You may also run ``easy_install collectd``
 59 | if you have `EasyInstall <http://peak.telecommunity.com/DevCenter/EasyInstall>`_
 60 | on your system.  The project page for collectd in the Cheese Shop (aka the Python
 61 | Package Index or PyPI) `may be found here <http://pypi.python.org/pypi/collectd/>`_.
 62 | 
 63 | You may also check out the development version of collectd with this command:
 64 | 
 65 | ``git clone https://github.com/appliedsec/collectd.git``
 66 | 
 67 | 
 68 | Functions and Classes
 69 | =====================
 70 | 
 71 | .. function:: start_threads()
 72 | 
 73 |     This function starts two daemon threads.  The first takes snapshots of your
 74 |     counters and resets them periodically.  The other serializes the statistics
 75 |     into protocol messages understood by the collectd Network plugin and sends
 76 |     them in appropriately-sized UDP packets.
 77 |     
 78 |     You must call this function when your program starts, or else this module
 79 |     will never actually send any data to any collectd servers.  Calling this
 80 |     function more than once throws an exception.
 81 | 
 82 | 
 83 | 
 84 | .. class:: Connection(hostname = socket.gethostname(), collectd_host = "localhost", collectd_port = 25826, plugin_inst = "", plugin_name = "any")
 85 | 
 86 |     Connection objects may be instantiated with 5 optional arguments:
 87 |     
 88 |     * ``hostname``: the hostname you use to identify yourself to the collectd server; if omitted, this defaults to the result of ``socket.gethostname()``
 89 |     * ``collectd_host``: the hostname or ip address of the collectd server to which we will send statistics
 90 |     * ``collectd_port``: the port to which you will send statistics messages
 91 |     * ``plugin_inst``: the plugin instance name which will be sent to the collectd server; this mostly affects the directory name used by the collectd rrdtool plugin
 92 |     * ``plugin_name``: the name of the plugin with which the collectd server will associate your statistics; this mostly affects the directory tree used by the collectd rrdtool plugin
 93 |     
 94 |     Connection objects with identical parameters are singletons; in other
 95 |     words, ``Connection("foo") is Connection("foo")`` but
 96 |     ``Connection("foo") is not Connection("bar")``.
 97 |     
 98 |     .. method:: __getattr__(name)
 99 |     
100 |         Statistics are recorded through ``Counter`` objects, which are
101 |         dynamically generated by accessing fields on ``Connection`` instances.
102 |         So saying ``conn.foo`` creates a ``Counter`` object.
103 |         
104 |         These objects are distinct but cached, so ``conn.foo is conn.foo`` but
105 |         ``conn.foo is not conn.bar``.
106 | 
107 | 
108 | 
109 | .. class:: Counter(category)
110 | 
111 |     You shouldn't directly instantiate this class; instead ``Counter`` objects
112 |     are automatically created by accessing attributes of ``Connection`` objects
113 |     such that ``conn.foo`` will cache and return ``Counter("foo")``.
114 |     
115 |     Both of the following methods swallow and log all possible exceptions, so
116 |     you never need to worry about an error being thrown by calls to either of
117 |     these methods.  These functions are also synchronized, so you can safely
118 |     call them simultaneously from different threads.
119 |     
120 |     .. method:: record(*specific, **stats)
121 |     
122 |         Each keyword argument to this method is interpreted as a statistic,
123 |         whose name is the argument name, and whose value is incrementd by
124 |         the argument value.
125 |         
126 |         You may pass one or more string identifiers as positional arguments
127 |         to this method.  If you do so, then separate statistic counts will
128 |         be maintained for this identifier.  These counts are always added
129 |         to the base count for each statistic.
130 |         
131 |         For example, if you ran the following code
132 |         
133 |         .. code-block:: python
134 |         
135 |             conn = collectd.Connection()
136 |             conn.example.record(baz = 1)
137 |             conn.example.record("foo", baz = 2)
138 |             conn.example.record("bar", baz = 3)
139 |         
140 |         and then statistics were sent to the collectd server, it would result
141 |         in the following files:
142 |         
143 |         * ``gauge-example-baz.rrd`` (with a value of 6 for this time increment)
144 |         * ``gauge-example-foo-baz.rrd`` (with a value of 2 for this time increment)
145 |         * ``gauge-example-bar-baz.rrd`` (with a value of 3 for this time increment)
146 |     
147 |     
148 |     .. method:: set_exact(**stats)
149 |     
150 |         Each keyword argument to this method is interpreted as a statistic,
151 |         whose name is the argument name, and whose value is set to the exact
152 |         value of the argument.  Use this method when you have values which you
153 |         wish to update to a specific value rather than increment.
154 | 
155 | 
156 | 
157 | .. warning::
158 | 
159 |     All names are sanitized to contain only alphanumeric characters separated
160 |     by underscores.  In other words, if you did something like
161 |     
162 |     .. code-block:: python
163 |     
164 |         conn = collectd.Connection()
165 |         counter = getattr(conn, "^@#@foo%$&&*")
166 |         stat = {"*()#@spam!@$^&*": 1}
167 |         counter.record("()#@bar&*()baz$^_+", **stat)
168 |     
169 |     then the resulting files would be named ``gauge-foo-spam.rrd`` and
170 |     ``gauge-foo-bar_baz-spam.rrd``. Although this behavior is generally
171 |     desirable, it could lead to your statistics becoming merged.  For example,
172 |     the ``foo-bar`` and ``foo/bar`` statistics in the following code would be
173 |     combined into a single ``foo_bar`` statistic:
174 |     
175 |     .. code-block:: python
176 |     
177 |         conn = collectd.Connection()
178 |         conn.foo.record("foo-bar", baz = 2)
179 |         conn.foo.record("foo/bar", baz = 3)
180 | 
181 | 
182 | 
183 | Logging
184 | =======
185 | As mentioned above, collectd swallows exceptions so that you never have to
186 | worry about calling a function from this module and triggering an exception.
187 | However, any exceptions which do occur are logged using the
188 | `logging <http://docs.python.org/library/logging.html>`_ module from the
189 | standard library, specifically to the `collectd` logger.  No other logging
190 | is performed.
191 | 
192 | However, this module defines no handlers for the `collectd` logger, so by
193 | default nothing is done with any of these log messages.
194 | 
195 | 
196 | 
197 | A More Complex Example
198 | ======================
199 | The following code is available in the ``examples/primes.py`` file in your
200 | source distribution:
201 | 
202 | .. literalinclude:: ../examples/primes.py
203 | 
204 | Here's a list of files generated by this code, along with an explanation of
205 | the counter which each file contains for each time interval:
206 | 
207 | * ``gauge-queue-size.rrd``: a snapshot of the size of the numbers queue
208 | * ``gauge-producer-too_small.rrd``: a count of the random numbers generated by the producer thread which were discarded for being too small
209 | * ``gauge-producer-too_big.rrd``: a count of the random numbers generated by the producer thread which were discarded for being too large
210 | * ``gauge-producer-just_right.rrd``: a count of the random numbers generated by the producer thread which were sent to the consumer thread for factoring
211 | * ``gauge-consumer-count.rrd``: an overall count of the numbers factored by the consumer thread
212 | * ``gauge-consumer-composite-count.rrd``: a count of the numbers factored by the consumer thread which turned out to be non-prime
213 | * ``gauge-consumer-prime-count.rrd``: a count of the numbers factored by the consumer thread which turned out to be prime
214 | * ``gauge-consumer-time.rrd``: the amount of wallclock time elapsed while factoring numbers
215 | * ``gauge-consumer-composite-time.rrd``: the amount of wallclock time elapsed while factoring numbers which turned out to be non-prime
216 | * ``gauge-consumer-prime-time.rrd``: the amount of wallclock time elapsed while factoring numbers which turned out to be prime
217 | 
218 | TODO: add graphs to this example to demonstrate what the data looks like
219 | 
220 | 
221 | 
222 | A Utility for Graphing RRD Data
223 | ===============================
224 | This is forthcoming; we'd like a simple script for generating the complex
225 | command-line arguments understood by ``rrdtool graph`` commands.
226 | 
227 | At some point we may also want a web interface similar to the existing
228 | collectd cgi script which dynamically lets you select and generate graphs,
229 | but with awareness of the semantics of the files generated by this module,
230 | which would allow users to start with a high-level overview and drill-down
231 | into specific data, combine data from different sources into one graph, etc.
232 | 


--------------------------------------------------------------------------------
/docs/_static/basic.css:
--------------------------------------------------------------------------------
  1 | /*
  2 |  * basic.css
  3 |  * ~~~~~~~~~
  4 |  *
  5 |  * Sphinx stylesheet -- basic theme.
  6 |  *
  7 |  * :copyright: Copyright 2007-2010 by the Sphinx team, see AUTHORS.
  8 |  * :license: BSD, see LICENSE for details.
  9 |  *
 10 |  */
 11 | 
 12 | /* -- main layout ----------------------------------------------------------- */
 13 | 
 14 | div.clearer {
 15 |     clear: both;
 16 | }
 17 | 
 18 | /* -- relbar ---------------------------------------------------------------- */
 19 | 
 20 | div.related {
 21 |     width: 100%;
 22 |     font-size: 90%;
 23 | }
 24 | 
 25 | div.related h3 {
 26 |     display: none;
 27 | }
 28 | 
 29 | div.related ul {
 30 |     margin: 0;
 31 |     padding: 0 0 0 10px;
 32 |     list-style: none;
 33 | }
 34 | 
 35 | div.related li {
 36 |     display: inline;
 37 | }
 38 | 
 39 | div.related li.right {
 40 |     float: right;
 41 |     margin-right: 5px;
 42 | }
 43 | 
 44 | /* -- sidebar --------------------------------------------------------------- */
 45 | 
 46 | div.sphinxsidebarwrapper {
 47 |     padding: 10px 5px 0 10px;
 48 | }
 49 | 
 50 | div.sphinxsidebar {
 51 |     float: left;
 52 |     width: 230px;
 53 |     margin-left: -100%;
 54 |     font-size: 90%;
 55 | }
 56 | 
 57 | div.sphinxsidebar ul {
 58 |     list-style: none;
 59 | }
 60 | 
 61 | div.sphinxsidebar ul ul,
 62 | div.sphinxsidebar ul.want-points {
 63 |     margin-left: 20px;
 64 |     list-style: square;
 65 | }
 66 | 
 67 | div.sphinxsidebar ul ul {
 68 |     margin-top: 0;
 69 |     margin-bottom: 0;
 70 | }
 71 | 
 72 | div.sphinxsidebar form {
 73 |     margin-top: 10px;
 74 | }
 75 | 
 76 | div.sphinxsidebar input {
 77 |     border: 1px solid #98dbcc;
 78 |     font-family: sans-serif;
 79 |     font-size: 1em;
 80 | }
 81 | 
 82 | img {
 83 |     border: 0;
 84 | }
 85 | 
 86 | /* -- search page ----------------------------------------------------------- */
 87 | 
 88 | ul.search {
 89 |     margin: 10px 0 0 20px;
 90 |     padding: 0;
 91 | }
 92 | 
 93 | ul.search li {
 94 |     padding: 5px 0 5px 20px;
 95 |     background-image: url(file.png);
 96 |     background-repeat: no-repeat;
 97 |     background-position: 0 7px;
 98 | }
 99 | 
100 | ul.search li a {
101 |     font-weight: bold;
102 | }
103 | 
104 | ul.search li div.context {
105 |     color: #888;
106 |     margin: 2px 0 0 30px;
107 |     text-align: left;
108 | }
109 | 
110 | ul.keywordmatches li.goodmatch a {
111 |     font-weight: bold;
112 | }
113 | 
114 | /* -- index page ------------------------------------------------------------ */
115 | 
116 | table.contentstable {
117 |     width: 90%;
118 | }
119 | 
120 | table.contentstable p.biglink {
121 |     line-height: 150%;
122 | }
123 | 
124 | a.biglink {
125 |     font-size: 1.3em;
126 | }
127 | 
128 | span.linkdescr {
129 |     font-style: italic;
130 |     padding-top: 5px;
131 |     font-size: 90%;
132 | }
133 | 
134 | /* -- general index --------------------------------------------------------- */
135 | 
136 | table.indextable {
137 |     width: 100%;
138 | }
139 | 
140 | table.indextable td {
141 |     text-align: left;
142 |     vertical-align: top;
143 | }
144 | 
145 | table.indextable dl, table.indextable dd {
146 |     margin-top: 0;
147 |     margin-bottom: 0;
148 | }
149 | 
150 | table.indextable tr.pcap {
151 |     height: 10px;
152 | }
153 | 
154 | table.indextable tr.cap {
155 |     margin-top: 10px;
156 |     background-color: #f2f2f2;
157 | }
158 | 
159 | img.toggler {
160 |     margin-right: 3px;
161 |     margin-top: 3px;
162 |     cursor: pointer;
163 | }
164 | 
165 | div.modindex-jumpbox {
166 |     border-top: 1px solid #ddd;
167 |     border-bottom: 1px solid #ddd;
168 |     margin: 1em 0 1em 0;
169 |     padding: 0.4em;
170 | }
171 | 
172 | div.genindex-jumpbox {
173 |     border-top: 1px solid #ddd;
174 |     border-bottom: 1px solid #ddd;
175 |     margin: 1em 0 1em 0;
176 |     padding: 0.4em;
177 | }
178 | 
179 | /* -- general body styles --------------------------------------------------- */
180 | 
181 | a.headerlink {
182 |     visibility: hidden;
183 | }
184 | 
185 | h1:hover > a.headerlink,
186 | h2:hover > a.headerlink,
187 | h3:hover > a.headerlink,
188 | h4:hover > a.headerlink,
189 | h5:hover > a.headerlink,
190 | h6:hover > a.headerlink,
191 | dt:hover > a.headerlink {
192 |     visibility: visible;
193 | }
194 | 
195 | div.body p.caption {
196 |     text-align: inherit;
197 | }
198 | 
199 | div.body td {
200 |     text-align: left;
201 | }
202 | 
203 | .field-list ul {
204 |     padding-left: 1em;
205 | }
206 | 
207 | .first {
208 |     margin-top: 0 !important;
209 | }
210 | 
211 | p.rubric {
212 |     margin-top: 30px;
213 |     font-weight: bold;
214 | }
215 | 
216 | .align-left {
217 |     text-align: left;
218 | }
219 | 
220 | .align-center {
221 |     clear: both;
222 |     text-align: center;
223 | }
224 | 
225 | .align-right {
226 |     text-align: right;
227 | }
228 | 
229 | /* -- sidebars -------------------------------------------------------------- */
230 | 
231 | div.sidebar {
232 |     margin: 0 0 0.5em 1em;
233 |     border: 1px solid #ddb;
234 |     padding: 7px 7px 0 7px;
235 |     background-color: #ffe;
236 |     width: 40%;
237 |     float: right;
238 | }
239 | 
240 | p.sidebar-title {
241 |     font-weight: bold;
242 | }
243 | 
244 | /* -- topics ---------------------------------------------------------------- */
245 | 
246 | div.topic {
247 |     border: 1px solid #ccc;
248 |     padding: 7px 7px 0 7px;
249 |     margin: 10px 0 10px 0;
250 | }
251 | 
252 | p.topic-title {
253 |     font-size: 1.1em;
254 |     font-weight: bold;
255 |     margin-top: 10px;
256 | }
257 | 
258 | /* -- admonitions ----------------------------------------------------------- */
259 | 
260 | div.admonition {
261 |     margin-top: 10px;
262 |     margin-bottom: 10px;
263 |     padding: 7px;
264 | }
265 | 
266 | div.admonition dt {
267 |     font-weight: bold;
268 | }
269 | 
270 | div.admonition dl {
271 |     margin-bottom: 0;
272 | }
273 | 
274 | p.admonition-title {
275 |     margin: 0px 10px 5px 0px;
276 |     font-weight: bold;
277 | }
278 | 
279 | div.body p.centered {
280 |     text-align: center;
281 |     margin-top: 25px;
282 | }
283 | 
284 | /* -- tables ---------------------------------------------------------------- */
285 | 
286 | table.docutils {
287 |     border: 0;
288 |     border-collapse: collapse;
289 | }
290 | 
291 | table.docutils td, table.docutils th {
292 |     padding: 1px 8px 1px 5px;
293 |     border-top: 0;
294 |     border-left: 0;
295 |     border-right: 0;
296 |     border-bottom: 1px solid #aaa;
297 | }
298 | 
299 | table.field-list td, table.field-list th {
300 |     border: 0 !important;
301 | }
302 | 
303 | table.footnote td, table.footnote th {
304 |     border: 0 !important;
305 | }
306 | 
307 | th {
308 |     text-align: left;
309 |     padding-right: 5px;
310 | }
311 | 
312 | table.citation {
313 |     border-left: solid 1px gray;
314 |     margin-left: 1px;
315 | }
316 | 
317 | table.citation td {
318 |     border-bottom: none;
319 | }
320 | 
321 | /* -- other body styles ----------------------------------------------------- */
322 | 
323 | ol.arabic {
324 |     list-style: decimal;
325 | }
326 | 
327 | ol.loweralpha {
328 |     list-style: lower-alpha;
329 | }
330 | 
331 | ol.upperalpha {
332 |     list-style: upper-alpha;
333 | }
334 | 
335 | ol.lowerroman {
336 |     list-style: lower-roman;
337 | }
338 | 
339 | ol.upperroman {
340 |     list-style: upper-roman;
341 | }
342 | 
343 | dl {
344 |     margin-bottom: 15px;
345 | }
346 | 
347 | dd p {
348 |     margin-top: 0px;
349 | }
350 | 
351 | dd ul, dd table {
352 |     margin-bottom: 10px;
353 | }
354 | 
355 | dd {
356 |     margin-top: 3px;
357 |     margin-bottom: 10px;
358 |     margin-left: 30px;
359 | }
360 | 
361 | dt:target, .highlighted {
362 |     background-color: #fbe54e;
363 | }
364 | 
365 | dl.glossary dt {
366 |     font-weight: bold;
367 |     font-size: 1.1em;
368 | }
369 | 
370 | .field-list ul {
371 |     margin: 0;
372 |     padding-left: 1em;
373 | }
374 | 
375 | .field-list p {
376 |     margin: 0;
377 | }
378 | 
379 | .refcount {
380 |     color: #060;
381 | }
382 | 
383 | .optional {
384 |     font-size: 1.3em;
385 | }
386 | 
387 | .versionmodified {
388 |     font-style: italic;
389 | }
390 | 
391 | .system-message {
392 |     background-color: #fda;
393 |     padding: 5px;
394 |     border: 3px solid red;
395 | }
396 | 
397 | .footnote:target  {
398 |     background-color: #ffa
399 | }
400 | 
401 | .line-block {
402 |     display: block;
403 |     margin-top: 1em;
404 |     margin-bottom: 1em;
405 | }
406 | 
407 | .line-block .line-block {
408 |     margin-top: 0;
409 |     margin-bottom: 0;
410 |     margin-left: 1.5em;
411 | }
412 | 
413 | .guilabel, .menuselection {
414 |     font-family: sans-serif;
415 | }
416 | 
417 | .accelerator {
418 |     text-decoration: underline;
419 | }
420 | 
421 | .classifier {
422 |     font-style: oblique;
423 | }
424 | 
425 | /* -- code displays --------------------------------------------------------- */
426 | 
427 | pre {
428 |     overflow: auto;
429 | }
430 | 
431 | td.linenos pre {
432 |     padding: 5px 0px;
433 |     border: 0;
434 |     background-color: transparent;
435 |     color: #aaa;
436 | }
437 | 
438 | table.highlighttable {
439 |     margin-left: 0.5em;
440 | }
441 | 
442 | table.highlighttable td {
443 |     padding: 0 0.5em 0 0.5em;
444 | }
445 | 
446 | tt.descname {
447 |     background-color: transparent;
448 |     font-weight: bold;
449 |     font-size: 1.2em;
450 | }
451 | 
452 | tt.descclassname {
453 |     background-color: transparent;
454 | }
455 | 
456 | tt.xref, a tt {
457 |     background-color: transparent;
458 |     font-weight: bold;
459 | }
460 | 
461 | h1 tt, h2 tt, h3 tt, h4 tt, h5 tt, h6 tt {
462 |     background-color: transparent;
463 | }
464 | 
465 | .viewcode-link {
466 |     float: right;
467 | }
468 | 
469 | .viewcode-back {
470 |     float: right;
471 |     font-family: sans-serif;
472 | }
473 | 
474 | div.viewcode-block:target {
475 |     margin: -1px -10px;
476 |     padding: 0 10px;
477 | }
478 | 
479 | /* -- math display ---------------------------------------------------------- */
480 | 
481 | img.math {
482 |     vertical-align: middle;
483 | }
484 | 
485 | div.body div.math p {
486 |     text-align: center;
487 | }
488 | 
489 | span.eqno {
490 |     float: right;
491 | }
492 | 
493 | /* -- printout stylesheet --------------------------------------------------- */
494 | 
495 | @media print {
496 |     div.document,
497 |     div.documentwrapper,
498 |     div.bodywrapper {
499 |         margin: 0 !important;
500 |         width: 100%;
501 |     }
502 | 
503 |     div.sphinxsidebar,
504 |     div.related,
505 |     div.footer,
506 |     #top-link {
507 |         display: none;
508 |     }
509 | }
510 | 


--------------------------------------------------------------------------------
/docs/_static/default.css:
--------------------------------------------------------------------------------
  1 | /*
  2 |  * default.css_t
  3 |  * ~~~~~~~~~~~~~
  4 |  *
  5 |  * Sphinx stylesheet -- default theme.
  6 |  *
  7 |  * :copyright: Copyright 2007-2010 by the Sphinx team, see AUTHORS.
  8 |  * :license: BSD, see LICENSE for details.
  9 |  *
 10 |  */
 11 | 
 12 | @import url("basic.css");
 13 | 
 14 | /* -- page layout ----------------------------------------------------------- */
 15 | 
 16 | body {
 17 |     font-family: sans-serif;
 18 |     font-size: 100%;
 19 |     background-color: #11303d;
 20 |     color: #000;
 21 |     margin: 0;
 22 |     padding: 0;
 23 | }
 24 | 
 25 | div.document {
 26 |     background-color: #1c4e63;
 27 | }
 28 | 
 29 | div.documentwrapper {
 30 |     float: left;
 31 |     width: 100%;
 32 | }
 33 | 
 34 | div.bodywrapper {
 35 |     margin: 0 0 0 230px;
 36 | }
 37 | 
 38 | div.body {
 39 |     background-color: #ffffff;
 40 |     color: #000000;
 41 |     padding: 0 20px 30px 20px;
 42 | }
 43 | 
 44 | div.footer {
 45 |     color: #ffffff;
 46 |     width: 100%;
 47 |     padding: 9px 0 9px 0;
 48 |     text-align: center;
 49 |     font-size: 75%;
 50 | }
 51 | 
 52 | div.footer a {
 53 |     color: #ffffff;
 54 |     text-decoration: underline;
 55 | }
 56 | 
 57 | div.related {
 58 |     background-color: #133f52;
 59 |     line-height: 30px;
 60 |     color: #ffffff;
 61 | }
 62 | 
 63 | div.related a {
 64 |     color: #ffffff;
 65 | }
 66 | 
 67 | div.sphinxsidebar {
 68 | }
 69 | 
 70 | div.sphinxsidebar h3 {
 71 |     font-family: 'Trebuchet MS', sans-serif;
 72 |     color: #ffffff;
 73 |     font-size: 1.4em;
 74 |     font-weight: normal;
 75 |     margin: 0;
 76 |     padding: 0;
 77 | }
 78 | 
 79 | div.sphinxsidebar h3 a {
 80 |     color: #ffffff;
 81 | }
 82 | 
 83 | div.sphinxsidebar h4 {
 84 |     font-family: 'Trebuchet MS', sans-serif;
 85 |     color: #ffffff;
 86 |     font-size: 1.3em;
 87 |     font-weight: normal;
 88 |     margin: 5px 0 0 0;
 89 |     padding: 0;
 90 | }
 91 | 
 92 | div.sphinxsidebar p {
 93 |     color: #ffffff;
 94 | }
 95 | 
 96 | div.sphinxsidebar p.topless {
 97 |     margin: 5px 10px 10px 10px;
 98 | }
 99 | 
100 | div.sphinxsidebar ul {
101 |     margin: 10px;
102 |     padding: 0;
103 |     color: #ffffff;
104 | }
105 | 
106 | div.sphinxsidebar a {
107 |     color: #98dbcc;
108 | }
109 | 
110 | div.sphinxsidebar input {
111 |     border: 1px solid #98dbcc;
112 |     font-family: sans-serif;
113 |     font-size: 1em;
114 | }
115 | 
116 | 
117 | /* -- hyperlink styles ------------------------------------------------------ */
118 | 
119 | a {
120 |     color: #355f7c;
121 |     text-decoration: none;
122 | }
123 | 
124 | a:visited {
125 |     color: #355f7c;
126 |     text-decoration: none;
127 | }
128 | 
129 | a:hover {
130 |     text-decoration: underline;
131 | }
132 | 
133 | 
134 | 
135 | /* -- body styles ----------------------------------------------------------- */
136 | 
137 | div.body h1,
138 | div.body h2,
139 | div.body h3,
140 | div.body h4,
141 | div.body h5,
142 | div.body h6 {
143 |     font-family: 'Trebuchet MS', sans-serif;
144 |     background-color: #f2f2f2;
145 |     font-weight: normal;
146 |     color: #20435c;
147 |     border-bottom: 1px solid #ccc;
148 |     margin: 20px -20px 10px -20px;
149 |     padding: 3px 0 3px 10px;
150 | }
151 | 
152 | div.body h1 { margin-top: 0; font-size: 200%; }
153 | div.body h2 { font-size: 160%; }
154 | div.body h3 { font-size: 140%; }
155 | div.body h4 { font-size: 120%; }
156 | div.body h5 { font-size: 110%; }
157 | div.body h6 { font-size: 100%; }
158 | 
159 | a.headerlink {
160 |     color: #c60f0f;
161 |     font-size: 0.8em;
162 |     padding: 0 4px 0 4px;
163 |     text-decoration: none;
164 | }
165 | 
166 | a.headerlink:hover {
167 |     background-color: #c60f0f;
168 |     color: white;
169 | }
170 | 
171 | div.body p, div.body dd, div.body li {
172 |     text-align: justify;
173 |     line-height: 130%;
174 | }
175 | 
176 | div.admonition p.admonition-title + p {
177 |     display: inline;
178 | }
179 | 
180 | div.admonition p {
181 |     margin-bottom: 5px;
182 | }
183 | 
184 | div.admonition pre {
185 |     margin-bottom: 5px;
186 | }
187 | 
188 | div.admonition ul, div.admonition ol {
189 |     margin-bottom: 5px;
190 | }
191 | 
192 | div.note {
193 |     background-color: #eee;
194 |     border: 1px solid #ccc;
195 | }
196 | 
197 | div.seealso {
198 |     background-color: #ffc;
199 |     border: 1px solid #ff6;
200 | }
201 | 
202 | div.topic {
203 |     background-color: #eee;
204 | }
205 | 
206 | div.warning {
207 |     background-color: #ffe4e4;
208 |     border: 1px solid #f66;
209 | }
210 | 
211 | p.admonition-title {
212 |     display: inline;
213 | }
214 | 
215 | p.admonition-title:after {
216 |     content: ":";
217 | }
218 | 
219 | pre {
220 |     padding: 5px;
221 |     background-color: #eeffcc;
222 |     color: #333333;
223 |     line-height: 120%;
224 |     border: 1px solid #ac9;
225 |     border-left: none;
226 |     border-right: none;
227 | }
228 | 
229 | tt {
230 |     background-color: #ecf0f3;
231 |     padding: 0 1px 0 1px;
232 |     font-size: 0.95em;
233 | }
234 | 
235 | th {
236 |     background-color: #ede;
237 | }
238 | 
239 | .warning tt {
240 |     background: #efc2c2;
241 | }
242 | 
243 | .note tt {
244 |     background: #d6d6d6;
245 | }
246 | 
247 | .viewcode-back {
248 |     font-family: sans-serif;
249 | }
250 | 
251 | div.viewcode-block:target {
252 |     background-color: #f4debf;
253 |     border-top: 1px solid #ac9;
254 |     border-bottom: 1px solid #ac9;
255 | }


--------------------------------------------------------------------------------
/docs/_static/doctools.js:
--------------------------------------------------------------------------------
  1 | /*
  2 |  * doctools.js
  3 |  * ~~~~~~~~~~~
  4 |  *
  5 |  * Sphinx JavaScript utilties for all documentation.
  6 |  *
  7 |  * :copyright: Copyright 2007-2010 by the Sphinx team, see AUTHORS.
  8 |  * :license: BSD, see LICENSE for details.
  9 |  *
 10 |  */
 11 | 
 12 | /**
 13 |  * select a different prefix for underscore
 14 |  */
 15 | $u = _.noConflict();
 16 | 
 17 | /**
 18 |  * make the code below compatible with browsers without
 19 |  * an installed firebug like debugger
 20 | if (!window.console || !console.firebug) {
 21 |   var names = ["log", "debug", "info", "warn", "error", "assert", "dir",
 22 |     "dirxml", "group", "groupEnd", "time", "timeEnd", "count", "trace",
 23 |     "profile", "profileEnd"];
 24 |   window.console = {};
 25 |   for (var i = 0; i < names.length; ++i)
 26 |     window.console[names[i]] = function() {};
 27 | }
 28 |  */
 29 | 
 30 | /**
 31 |  * small helper function to urldecode strings
 32 |  */
 33 | jQuery.urldecode = function(x) {
 34 |   return decodeURIComponent(x).replace(/\+/g, ' ');
 35 | }
 36 | 
 37 | /**
 38 |  * small helper function to urlencode strings
 39 |  */
 40 | jQuery.urlencode = encodeURIComponent;
 41 | 
 42 | /**
 43 |  * This function returns the parsed url parameters of the
 44 |  * current request. Multiple values per key are supported,
 45 |  * it will always return arrays of strings for the value parts.
 46 |  */
 47 | jQuery.getQueryParameters = function(s) {
 48 |   if (typeof s == 'undefined')
 49 |     s = document.location.search;
 50 |   var parts = s.substr(s.indexOf('?') + 1).split('&');
 51 |   var result = {};
 52 |   for (var i = 0; i < parts.length; i++) {
 53 |     var tmp = parts[i].split('=', 2);
 54 |     var key = jQuery.urldecode(tmp[0]);
 55 |     var value = jQuery.urldecode(tmp[1]);
 56 |     if (key in result)
 57 |       result[key].push(value);
 58 |     else
 59 |       result[key] = [value];
 60 |   }
 61 |   return result;
 62 | };
 63 | 
 64 | /**
 65 |  * small function to check if an array contains
 66 |  * a given item.
 67 |  */
 68 | jQuery.contains = function(arr, item) {
 69 |   for (var i = 0; i < arr.length; i++) {
 70 |     if (arr[i] == item)
 71 |       return true;
 72 |   }
 73 |   return false;
 74 | };
 75 | 
 76 | /**
 77 |  * highlight a given string on a jquery object by wrapping it in
 78 |  * span elements with the given class name.
 79 |  */
 80 | jQuery.fn.highlightText = function(text, className) {
 81 |   function highlight(node) {
 82 |     if (node.nodeType == 3) {
 83 |       var val = node.nodeValue;
 84 |       var pos = val.toLowerCase().indexOf(text);
 85 |       if (pos >= 0 && !jQuery(node.parentNode).hasClass(className)) {
 86 |         var span = document.createElement("span");
 87 |         span.className = className;
 88 |         span.appendChild(document.createTextNode(val.substr(pos, text.length)));
 89 |         node.parentNode.insertBefore(span, node.parentNode.insertBefore(
 90 |           document.createTextNode(val.substr(pos + text.length)),
 91 |           node.nextSibling));
 92 |         node.nodeValue = val.substr(0, pos);
 93 |       }
 94 |     }
 95 |     else if (!jQuery(node).is("button, select, textarea")) {
 96 |       jQuery.each(node.childNodes, function() {
 97 |         highlight(this);
 98 |       });
 99 |     }
100 |   }
101 |   return this.each(function() {
102 |     highlight(this);
103 |   });
104 | };
105 | 
106 | /**
107 |  * Small JavaScript module for the documentation.
108 |  */
109 | var Documentation = {
110 | 
111 |   init : function() {
112 |     this.fixFirefoxAnchorBug();
113 |     this.highlightSearchWords();
114 |     this.initIndexTable();
115 |   },
116 | 
117 |   /**
118 |    * i18n support
119 |    */
120 |   TRANSLATIONS : {},
121 |   PLURAL_EXPR : function(n) { return n == 1 ? 0 : 1; },
122 |   LOCALE : 'unknown',
123 | 
124 |   // gettext and ngettext don't access this so that the functions
125 |   // can safely bound to a different name (_ = Documentation.gettext)
126 |   gettext : function(string) {
127 |     var translated = Documentation.TRANSLATIONS[string];
128 |     if (typeof translated == 'undefined')
129 |       return string;
130 |     return (typeof translated == 'string') ? translated : translated[0];
131 |   },
132 | 
133 |   ngettext : function(singular, plural, n) {
134 |     var translated = Documentation.TRANSLATIONS[singular];
135 |     if (typeof translated == 'undefined')
136 |       return (n == 1) ? singular : plural;
137 |     return translated[Documentation.PLURALEXPR(n)];
138 |   },
139 | 
140 |   addTranslations : function(catalog) {
141 |     for (var key in catalog.messages)
142 |       this.TRANSLATIONS[key] = catalog.messages[key];
143 |     this.PLURAL_EXPR = new Function('n', 'return +(' + catalog.plural_expr + ')');
144 |     this.LOCALE = catalog.locale;
145 |   },
146 | 
147 |   /**
148 |    * add context elements like header anchor links
149 |    */
150 |   addContextElements : function() {
151 |     $('div[id] > :header:first').each(function() {
152 |       $('<a class="headerlink">\u00B6</a>').
153 |       attr('href', '#' + this.id).
154 |       attr('title', _('Permalink to this headline')).
155 |       appendTo(this);
156 |     });
157 |     $('dt[id]').each(function() {
158 |       $('<a class="headerlink">\u00B6</a>').
159 |       attr('href', '#' + this.id).
160 |       attr('title', _('Permalink to this definition')).
161 |       appendTo(this);
162 |     });
163 |   },
164 | 
165 |   /**
166 |    * workaround a firefox stupidity
167 |    */
168 |   fixFirefoxAnchorBug : function() {
169 |     if (document.location.hash && $.browser.mozilla)
170 |       window.setTimeout(function() {
171 |         document.location.href += '';
172 |       }, 10);
173 |   },
174 | 
175 |   /**
176 |    * highlight the search words provided in the url in the text
177 |    */
178 |   highlightSearchWords : function() {
179 |     var params = $.getQueryParameters();
180 |     var terms = (params.highlight) ? params.highlight[0].split(/\s+/) : [];
181 |     if (terms.length) {
182 |       var body = $('div.body');
183 |       window.setTimeout(function() {
184 |         $.each(terms, function() {
185 |           body.highlightText(this.toLowerCase(), 'highlighted');
186 |         });
187 |       }, 10);
188 |       $('<li class="highlight-link"><a href="javascript:Documentation.' +
189 |         'hideSearchWords()">' + _('Hide Search Matches') + '</a></li>')
190 |           .appendTo($('.sidebar .this-page-menu'));
191 |     }
192 |   },
193 | 
194 |   /**
195 |    * init the domain index toggle buttons
196 |    */
197 |   initIndexTable : function() {
198 |     var togglers = $('img.toggler').click(function() {
199 |       var src = $(this).attr('src');
200 |       var idnum = $(this).attr('id').substr(7);
201 |       $('tr.cg-' + idnum).toggle();
202 |       if (src.substr(-9) == 'minus.png')
203 |         $(this).attr('src', src.substr(0, src.length-9) + 'plus.png');
204 |       else
205 |         $(this).attr('src', src.substr(0, src.length-8) + 'minus.png');
206 |     }).css('display', '');
207 |     if (DOCUMENTATION_OPTIONS.COLLAPSE_INDEX) {
208 |         togglers.click();
209 |     }
210 |   },
211 | 
212 |   /**
213 |    * helper function to hide the search marks again
214 |    */
215 |   hideSearchWords : function() {
216 |     $('.sidebar .this-page-menu li.highlight-link').fadeOut(300);
217 |     $('span.highlighted').removeClass('highlighted');
218 |   },
219 | 
220 |   /**
221 |    * make the url absolute
222 |    */
223 |   makeURL : function(relativeURL) {
224 |     return DOCUMENTATION_OPTIONS.URL_ROOT + '/' + relativeURL;
225 |   },
226 | 
227 |   /**
228 |    * get the current relative url
229 |    */
230 |   getCurrentURL : function() {
231 |     var path = document.location.pathname;
232 |     var parts = path.split(/\//);
233 |     $.each(DOCUMENTATION_OPTIONS.URL_ROOT.split(/\//), function() {
234 |       if (this == '..')
235 |         parts.pop();
236 |     });
237 |     var url = parts.join('/');
238 |     return path.substring(url.lastIndexOf('/') + 1, path.length - 1);
239 |   }
240 | };
241 | 
242 | // quick alias for translations
243 | _ = Documentation.gettext;
244 | 
245 | $(document).ready(function() {
246 |   Documentation.init();
247 | });
248 | 


--------------------------------------------------------------------------------
/docs/_static/file.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/appliedsec/collectd/7b51edfd08e055149b446e9839c4dc0bc7c834ce/docs/_static/file.png


--------------------------------------------------------------------------------
/docs/_static/minus.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/appliedsec/collectd/7b51edfd08e055149b446e9839c4dc0bc7c834ce/docs/_static/minus.png


--------------------------------------------------------------------------------
/docs/_static/plus.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/appliedsec/collectd/7b51edfd08e055149b446e9839c4dc0bc7c834ce/docs/_static/plus.png


--------------------------------------------------------------------------------
/docs/_static/pygments.css:
--------------------------------------------------------------------------------
 1 | .hll { background-color: #ffffcc }
 2 | .c { color: #408090; font-style: italic } /* Comment */
 3 | .err { border: 1px solid #FF0000 } /* Error */
 4 | .k { color: #007020; font-weight: bold } /* Keyword */
 5 | .o { color: #666666 } /* Operator */
 6 | .cm { color: #408090; font-style: italic } /* Comment.Multiline */
 7 | .cp { color: #007020 } /* Comment.Preproc */
 8 | .c1 { color: #408090; font-style: italic } /* Comment.Single */
 9 | .cs { color: #408090; background-color: #fff0f0 } /* Comment.Special */
10 | .gd { color: #A00000 } /* Generic.Deleted */
11 | .ge { font-style: italic } /* Generic.Emph */
12 | .gr { color: #FF0000 } /* Generic.Error */
13 | .gh { color: #000080; font-weight: bold } /* Generic.Heading */
14 | .gi { color: #00A000 } /* Generic.Inserted */
15 | .go { color: #303030 } /* Generic.Output */
16 | .gp { color: #c65d09; font-weight: bold } /* Generic.Prompt */
17 | .gs { font-weight: bold } /* Generic.Strong */
18 | .gu { color: #800080; font-weight: bold } /* Generic.Subheading */
19 | .gt { color: #0040D0 } /* Generic.Traceback */
20 | .kc { color: #007020; font-weight: bold } /* Keyword.Constant */
21 | .kd { color: #007020; font-weight: bold } /* Keyword.Declaration */
22 | .kn { color: #007020; font-weight: bold } /* Keyword.Namespace */
23 | .kp { color: #007020 } /* Keyword.Pseudo */
24 | .kr { color: #007020; font-weight: bold } /* Keyword.Reserved */
25 | .kt { color: #902000 } /* Keyword.Type */
26 | .m { color: #208050 } /* Literal.Number */
27 | .s { color: #4070a0 } /* Literal.String */
28 | .na { color: #4070a0 } /* Name.Attribute */
29 | .nb { color: #007020 } /* Name.Builtin */
30 | .nc { color: #0e84b5; font-weight: bold } /* Name.Class */
31 | .no { color: #60add5 } /* Name.Constant */
32 | .nd { color: #555555; font-weight: bold } /* Name.Decorator */
33 | .ni { color: #d55537; font-weight: bold } /* Name.Entity */
34 | .ne { color: #007020 } /* Name.Exception */
35 | .nf { color: #06287e } /* Name.Function */
36 | .nl { color: #002070; font-weight: bold } /* Name.Label */
37 | .nn { color: #0e84b5; font-weight: bold } /* Name.Namespace */
38 | .nt { color: #062873; font-weight: bold } /* Name.Tag */
39 | .nv { color: #bb60d5 } /* Name.Variable */
40 | .ow { color: #007020; font-weight: bold } /* Operator.Word */
41 | .w { color: #bbbbbb } /* Text.Whitespace */
42 | .mf { color: #208050 } /* Literal.Number.Float */
43 | .mh { color: #208050 } /* Literal.Number.Hex */
44 | .mi { color: #208050 } /* Literal.Number.Integer */
45 | .mo { color: #208050 } /* Literal.Number.Oct */
46 | .sb { color: #4070a0 } /* Literal.String.Backtick */
47 | .sc { color: #4070a0 } /* Literal.String.Char */
48 | .sd { color: #4070a0; font-style: italic } /* Literal.String.Doc */
49 | .s2 { color: #4070a0 } /* Literal.String.Double */
50 | .se { color: #4070a0; font-weight: bold } /* Literal.String.Escape */
51 | .sh { color: #4070a0 } /* Literal.String.Heredoc */
52 | .si { color: #70a0d0; font-style: italic } /* Literal.String.Interpol */
53 | .sx { color: #c65d09 } /* Literal.String.Other */
54 | .sr { color: #235388 } /* Literal.String.Regex */
55 | .s1 { color: #4070a0 } /* Literal.String.Single */
56 | .ss { color: #517918 } /* Literal.String.Symbol */
57 | .bp { color: #007020 } /* Name.Builtin.Pseudo */
58 | .vc { color: #bb60d5 } /* Name.Variable.Class */
59 | .vg { color: #bb60d5 } /* Name.Variable.Global */
60 | .vi { color: #bb60d5 } /* Name.Variable.Instance */
61 | .il { color: #208050 } /* Literal.Number.Integer.Long */


--------------------------------------------------------------------------------
/docs/_static/searchtools.js:
--------------------------------------------------------------------------------
  1 | /*
  2 |  * searchtools.js
  3 |  * ~~~~~~~~~~~~~~
  4 |  *
  5 |  * Sphinx JavaScript utilties for the full-text search.
  6 |  *
  7 |  * :copyright: Copyright 2007-2010 by the Sphinx team, see AUTHORS.
  8 |  * :license: BSD, see LICENSE for details.
  9 |  *
 10 |  */
 11 | 
 12 | /**
 13 |  * helper function to return a node containing the
 14 |  * search summary for a given text. keywords is a list
 15 |  * of stemmed words, hlwords is the list of normal, unstemmed
 16 |  * words. the first one is used to find the occurance, the
 17 |  * latter for highlighting it.
 18 |  */
 19 | 
 20 | jQuery.makeSearchSummary = function(text, keywords, hlwords) {
 21 |   var textLower = text.toLowerCase();
 22 |   var start = 0;
 23 |   $.each(keywords, function() {
 24 |     var i = textLower.indexOf(this.toLowerCase());
 25 |     if (i > -1)
 26 |       start = i;
 27 |   });
 28 |   start = Math.max(start - 120, 0);
 29 |   var excerpt = ((start > 0) ? '...' : '') +
 30 |   $.trim(text.substr(start, 240)) +
 31 |   ((start + 240 - text.length) ? '...' : '');
 32 |   var rv = $('<div class="context"></div>').text(excerpt);
 33 |   $.each(hlwords, function() {
 34 |     rv = rv.highlightText(this, 'highlighted');
 35 |   });
 36 |   return rv;
 37 | }
 38 | 
 39 | /**
 40 |  * Porter Stemmer
 41 |  */
 42 | var PorterStemmer = function() {
 43 | 
 44 |   var step2list = {
 45 |     ational: 'ate',
 46 |     tional: 'tion',
 47 |     enci: 'ence',
 48 |     anci: 'ance',
 49 |     izer: 'ize',
 50 |     bli: 'ble',
 51 |     alli: 'al',
 52 |     entli: 'ent',
 53 |     eli: 'e',
 54 |     ousli: 'ous',
 55 |     ization: 'ize',
 56 |     ation: 'ate',
 57 |     ator: 'ate',
 58 |     alism: 'al',
 59 |     iveness: 'ive',
 60 |     fulness: 'ful',
 61 |     ousness: 'ous',
 62 |     aliti: 'al',
 63 |     iviti: 'ive',
 64 |     biliti: 'ble',
 65 |     logi: 'log'
 66 |   };
 67 | 
 68 |   var step3list = {
 69 |     icate: 'ic',
 70 |     ative: '',
 71 |     alize: 'al',
 72 |     iciti: 'ic',
 73 |     ical: 'ic',
 74 |     ful: '',
 75 |     ness: ''
 76 |   };
 77 | 
 78 |   var c = "[^aeiou]";          // consonant
 79 |   var v = "[aeiouy]";          // vowel
 80 |   var C = c + "[^aeiouy]*";    // consonant sequence
 81 |   var V = v + "[aeiou]*";      // vowel sequence
 82 | 
 83 |   var mgr0 = "^(" + C + ")?" + V + C;                      // [C]VC... is m>0
 84 |   var meq1 = "^(" + C + ")?" + V + C + "(" + V + ")?$";    // [C]VC[V] is m=1
 85 |   var mgr1 = "^(" + C + ")?" + V + C + V + C;              // [C]VCVC... is m>1
 86 |   var s_v   = "^(" + C + ")?" + v;                         // vowel in stem
 87 | 
 88 |   this.stemWord = function (w) {
 89 |     var stem;
 90 |     var suffix;
 91 |     var firstch;
 92 |     var origword = w;
 93 | 
 94 |     if (w.length < 3)
 95 |       return w;
 96 | 
 97 |     var re;
 98 |     var re2;
 99 |     var re3;
100 |     var re4;
101 | 
102 |     firstch = w.substr(0,1);
103 |     if (firstch == "y")
104 |       w = firstch.toUpperCase() + w.substr(1);
105 | 
106 |     // Step 1a
107 |     re = /^(.+?)(ss|i)es$/;
108 |     re2 = /^(.+?)([^s])s$/;
109 | 
110 |     if (re.test(w))
111 |       w = w.replace(re,"$1$2");
112 |     else if (re2.test(w))
113 |       w = w.replace(re2,"$1$2");
114 | 
115 |     // Step 1b
116 |     re = /^(.+?)eed$/;
117 |     re2 = /^(.+?)(ed|ing)$/;
118 |     if (re.test(w)) {
119 |       var fp = re.exec(w);
120 |       re = new RegExp(mgr0);
121 |       if (re.test(fp[1])) {
122 |         re = /.$/;
123 |         w = w.replace(re,"");
124 |       }
125 |     }
126 |     else if (re2.test(w)) {
127 |       var fp = re2.exec(w);
128 |       stem = fp[1];
129 |       re2 = new RegExp(s_v);
130 |       if (re2.test(stem)) {
131 |         w = stem;
132 |         re2 = /(at|bl|iz)$/;
133 |         re3 = new RegExp("([^aeiouylsz])\\1$");
134 |         re4 = new RegExp("^" + C + v + "[^aeiouwxy]$");
135 |         if (re2.test(w))
136 |           w = w + "e";
137 |         else if (re3.test(w)) {
138 |           re = /.$/;
139 |           w = w.replace(re,"");
140 |         }
141 |         else if (re4.test(w))
142 |           w = w + "e";
143 |       }
144 |     }
145 | 
146 |     // Step 1c
147 |     re = /^(.+?)y$/;
148 |     if (re.test(w)) {
149 |       var fp = re.exec(w);
150 |       stem = fp[1];
151 |       re = new RegExp(s_v);
152 |       if (re.test(stem))
153 |         w = stem + "i";
154 |     }
155 | 
156 |     // Step 2
157 |     re = /^(.+?)(ational|tional|enci|anci|izer|bli|alli|entli|eli|ousli|ization|ation|ator|alism|iveness|fulness|ousness|aliti|iviti|biliti|logi)$/;
158 |     if (re.test(w)) {
159 |       var fp = re.exec(w);
160 |       stem = fp[1];
161 |       suffix = fp[2];
162 |       re = new RegExp(mgr0);
163 |       if (re.test(stem))
164 |         w = stem + step2list[suffix];
165 |     }
166 | 
167 |     // Step 3
168 |     re = /^(.+?)(icate|ative|alize|iciti|ical|ful|ness)$/;
169 |     if (re.test(w)) {
170 |       var fp = re.exec(w);
171 |       stem = fp[1];
172 |       suffix = fp[2];
173 |       re = new RegExp(mgr0);
174 |       if (re.test(stem))
175 |         w = stem + step3list[suffix];
176 |     }
177 | 
178 |     // Step 4
179 |     re = /^(.+?)(al|ance|ence|er|ic|able|ible|ant|ement|ment|ent|ou|ism|ate|iti|ous|ive|ize)$/;
180 |     re2 = /^(.+?)(s|t)(ion)$/;
181 |     if (re.test(w)) {
182 |       var fp = re.exec(w);
183 |       stem = fp[1];
184 |       re = new RegExp(mgr1);
185 |       if (re.test(stem))
186 |         w = stem;
187 |     }
188 |     else if (re2.test(w)) {
189 |       var fp = re2.exec(w);
190 |       stem = fp[1] + fp[2];
191 |       re2 = new RegExp(mgr1);
192 |       if (re2.test(stem))
193 |         w = stem;
194 |     }
195 | 
196 |     // Step 5
197 |     re = /^(.+?)e$/;
198 |     if (re.test(w)) {
199 |       var fp = re.exec(w);
200 |       stem = fp[1];
201 |       re = new RegExp(mgr1);
202 |       re2 = new RegExp(meq1);
203 |       re3 = new RegExp("^" + C + v + "[^aeiouwxy]$");
204 |       if (re.test(stem) || (re2.test(stem) && !(re3.test(stem))))
205 |         w = stem;
206 |     }
207 |     re = /ll$/;
208 |     re2 = new RegExp(mgr1);
209 |     if (re.test(w) && re2.test(w)) {
210 |       re = /.$/;
211 |       w = w.replace(re,"");
212 |     }
213 | 
214 |     // and turn initial Y back to y
215 |     if (firstch == "y")
216 |       w = firstch.toLowerCase() + w.substr(1);
217 |     return w;
218 |   }
219 | }
220 | 
221 | 
222 | /**
223 |  * Search Module
224 |  */
225 | var Search = {
226 | 
227 |   _index : null,
228 |   _queued_query : null,
229 |   _pulse_status : -1,
230 | 
231 |   init : function() {
232 |       var params = $.getQueryParameters();
233 |       if (params.q) {
234 |           var query = params.q[0];
235 |           $('input[name="q"]')[0].value = query;
236 |           this.performSearch(query);
237 |       }
238 |   },
239 | 
240 |   loadIndex : function(url) {
241 |     $.ajax({type: "GET", url: url, data: null, success: null,
242 |             dataType: "script", cache: true});
243 |   },
244 | 
245 |   setIndex : function(index) {
246 |     var q;
247 |     this._index = index;
248 |     if ((q = this._queued_query) !== null) {
249 |       this._queued_query = null;
250 |       Search.query(q);
251 |     }
252 |   },
253 | 
254 |   hasIndex : function() {
255 |       return this._index !== null;
256 |   },
257 | 
258 |   deferQuery : function(query) {
259 |       this._queued_query = query;
260 |   },
261 | 
262 |   stopPulse : function() {
263 |       this._pulse_status = 0;
264 |   },
265 | 
266 |   startPulse : function() {
267 |     if (this._pulse_status >= 0)
268 |         return;
269 |     function pulse() {
270 |       Search._pulse_status = (Search._pulse_status + 1) % 4;
271 |       var dotString = '';
272 |       for (var i = 0; i < Search._pulse_status; i++)
273 |         dotString += '.';
274 |       Search.dots.text(dotString);
275 |       if (Search._pulse_status > -1)
276 |         window.setTimeout(pulse, 500);
277 |     };
278 |     pulse();
279 |   },
280 | 
281 |   /**
282 |    * perform a search for something
283 |    */
284 |   performSearch : function(query) {
285 |     // create the required interface elements
286 |     this.out = $('#search-results');
287 |     this.title = $('<h2>' + _('Searching') + '</h2>').appendTo(this.out);
288 |     this.dots = $('<span></span>').appendTo(this.title);
289 |     this.status = $('<p style="display: none"></p>').appendTo(this.out);
290 |     this.output = $('<ul class="search"/>').appendTo(this.out);
291 | 
292 |     $('#search-progress').text(_('Preparing search...'));
293 |     this.startPulse();
294 | 
295 |     // index already loaded, the browser was quick!
296 |     if (this.hasIndex())
297 |       this.query(query);
298 |     else
299 |       this.deferQuery(query);
300 |   },
301 | 
302 |   query : function(query) {
303 |     var stopwords = ['and', 'then', 'into', 'it', 'as', 'are', 'in',
304 |                      'if', 'for', 'no', 'there', 'their', 'was', 'is',
305 |                      'be', 'to', 'that', 'but', 'they', 'not', 'such',
306 |                      'with', 'by', 'a', 'on', 'these', 'of', 'will',
307 |                      'this', 'near', 'the', 'or', 'at'];
308 | 
309 |     // stem the searchterms and add them to the correct list
310 |     var stemmer = new PorterStemmer();
311 |     var searchterms = [];
312 |     var excluded = [];
313 |     var hlterms = [];
314 |     var tmp = query.split(/\s+/);
315 |     var object = (tmp.length == 1) ? tmp[0].toLowerCase() : null;
316 |     for (var i = 0; i < tmp.length; i++) {
317 |       if ($u.indexOf(stopwords, tmp[i]) != -1 || tmp[i].match(/^\d+$/) ||
318 |           tmp[i] == "") {
319 |         // skip this "word"
320 |         continue;
321 |       }
322 |       // stem the word
323 |       var word = stemmer.stemWord(tmp[i]).toLowerCase();
324 |       // select the correct list
325 |       if (word[0] == '-') {
326 |         var toAppend = excluded;
327 |         word = word.substr(1);
328 |       }
329 |       else {
330 |         var toAppend = searchterms;
331 |         hlterms.push(tmp[i].toLowerCase());
332 |       }
333 |       // only add if not already in the list
334 |       if (!$.contains(toAppend, word))
335 |         toAppend.push(word);
336 |     };
337 |     var highlightstring = '?highlight=' + $.urlencode(hlterms.join(" "));
338 | 
339 |     // console.debug('SEARCH: searching for:');
340 |     // console.info('required: ', searchterms);
341 |     // console.info('excluded: ', excluded);
342 | 
343 |     // prepare search
344 |     var filenames = this._index.filenames;
345 |     var titles = this._index.titles;
346 |     var terms = this._index.terms;
347 |     var objects = this._index.objects;
348 |     var objtypes = this._index.objtypes;
349 |     var objnames = this._index.objnames;
350 |     var fileMap = {};
351 |     var files = null;
352 |     // different result priorities
353 |     var importantResults = [];
354 |     var objectResults = [];
355 |     var regularResults = [];
356 |     var unimportantResults = [];
357 |     $('#search-progress').empty();
358 | 
359 |     // lookup as object
360 |     if (object != null) {
361 |       for (var prefix in objects) {
362 |         for (var name in objects[prefix]) {
363 |           var fullname = (prefix ? prefix + '.' : '') + name;
364 |           if (fullname.toLowerCase().indexOf(object) > -1) {
365 |             match = objects[prefix][name];
366 |             descr = objnames[match[1]] + _(', in ') + titles[match[0]];
367 |             // XXX the generated anchors are not generally correct
368 |             // XXX there may be custom prefixes
369 |             result = [filenames[match[0]], fullname, '#'+fullname, descr];
370 |             switch (match[2]) {
371 |             case 1: objectResults.push(result); break;
372 |             case 0: importantResults.push(result); break;
373 |             case 2: unimportantResults.push(result); break;
374 |             }
375 |           }
376 |         }
377 |       }
378 |     }
379 | 
380 |     // sort results descending
381 |     objectResults.sort(function(a, b) {
382 |       return (a[1] > b[1]) ? -1 : ((a[1] < b[1]) ? 1 : 0);
383 |     });
384 | 
385 |     importantResults.sort(function(a, b) {
386 |       return (a[1] > b[1]) ? -1 : ((a[1] < b[1]) ? 1 : 0);
387 |     });
388 | 
389 |     unimportantResults.sort(function(a, b) {
390 |       return (a[1] > b[1]) ? -1 : ((a[1] < b[1]) ? 1 : 0);
391 |     });
392 | 
393 | 
394 |     // perform the search on the required terms
395 |     for (var i = 0; i < searchterms.length; i++) {
396 |       var word = searchterms[i];
397 |       // no match but word was a required one
398 |       if ((files = terms[word]) == null)
399 |         break;
400 |       if (files.length == undefined) {
401 |         files = [files];
402 |       }
403 |       // create the mapping
404 |       for (var j = 0; j < files.length; j++) {
405 |         var file = files[j];
406 |         if (file in fileMap)
407 |           fileMap[file].push(word);
408 |         else
409 |           fileMap[file] = [word];
410 |       }
411 |     }
412 | 
413 |     // now check if the files don't contain excluded terms
414 |     for (var file in fileMap) {
415 |       var valid = true;
416 | 
417 |       // check if all requirements are matched
418 |       if (fileMap[file].length != searchterms.length)
419 |         continue;
420 | 
421 |       // ensure that none of the excluded terms is in the
422 |       // search result.
423 |       for (var i = 0; i < excluded.length; i++) {
424 |         if (terms[excluded[i]] == file ||
425 |             $.contains(terms[excluded[i]] || [], file)) {
426 |           valid = false;
427 |           break;
428 |         }
429 |       }
430 | 
431 |       // if we have still a valid result we can add it
432 |       // to the result list
433 |       if (valid)
434 |         regularResults.push([filenames[file], titles[file], '', null]);
435 |     }
436 | 
437 |     // delete unused variables in order to not waste
438 |     // memory until list is retrieved completely
439 |     delete filenames, titles, terms;
440 | 
441 |     // now sort the regular results descending by title
442 |     regularResults.sort(function(a, b) {
443 |       var left = a[1].toLowerCase();
444 |       var right = b[1].toLowerCase();
445 |       return (left > right) ? -1 : ((left < right) ? 1 : 0);
446 |     });
447 | 
448 |     // combine all results
449 |     var results = unimportantResults.concat(regularResults)
450 |       .concat(objectResults).concat(importantResults);
451 | 
452 |     // print the results
453 |     var resultCount = results.length;
454 |     function displayNextItem() {
455 |       // results left, load the summary and display it
456 |       if (results.length) {
457 |         var item = results.pop();
458 |         var listItem = $('<li style="display:none"></li>');
459 |         if (DOCUMENTATION_OPTIONS.FILE_SUFFIX == '') {
460 |           // dirhtml builder
461 |           var dirname = item[0] + '/';
462 |           if (dirname.match(/\/index\/$/)) {
463 |             dirname = dirname.substring(0, dirname.length-6);
464 |           } else if (dirname == 'index/') {
465 |             dirname = '';
466 |           }
467 |           listItem.append($('<a/>').attr('href',
468 |             DOCUMENTATION_OPTIONS.URL_ROOT + dirname +
469 |             highlightstring + item[2]).html(item[1]));
470 |         } else {
471 |           // normal html builders
472 |           listItem.append($('<a/>').attr('href',
473 |             item[0] + DOCUMENTATION_OPTIONS.FILE_SUFFIX +
474 |             highlightstring + item[2]).html(item[1]));
475 |         }
476 |         if (item[3]) {
477 |           listItem.append($('<span> (' + item[3] + ')</span>'));
478 |           Search.output.append(listItem);
479 |           listItem.slideDown(5, function() {
480 |             displayNextItem();
481 |           });
482 |         } else if (DOCUMENTATION_OPTIONS.HAS_SOURCE) {
483 |           $.get(DOCUMENTATION_OPTIONS.URL_ROOT + '_sources/' +
484 |                 item[0] + '.txt', function(data) {
485 |             if (data != '') {
486 |               listItem.append($.makeSearchSummary(data, searchterms, hlterms));
487 |               Search.output.append(listItem);
488 |             }
489 |             listItem.slideDown(5, function() {
490 |               displayNextItem();
491 |             });
492 |           });
493 |         } else {
494 |           // no source available, just display title
495 |           Search.output.append(listItem);
496 |           listItem.slideDown(5, function() {
497 |             displayNextItem();
498 |           });
499 |         }
500 |       }
501 |       // search finished, update title and status message
502 |       else {
503 |         Search.stopPulse();
504 |         Search.title.text(_('Search Results'));
505 |         if (!resultCount)
506 |           Search.status.text(_('Your search did not match any documents. Please make sure that all words are spelled correctly and that you\'ve selected enough categories.'));
507 |         else
508 |             Search.status.text(_('Search finished, found %s page(s) matching the search query.').replace('%s', resultCount));
509 |         Search.status.fadeIn(500);
510 |       }
511 |     }
512 |     displayNextItem();
513 |   }
514 | }
515 | 
516 | $(document).ready(function() {
517 |   Search.init();
518 | });
519 | 


--------------------------------------------------------------------------------
/docs/_static/sidebar.js:
--------------------------------------------------------------------------------
  1 | /*
  2 |  * sidebar.js
  3 |  * ~~~~~~~~~~
  4 |  *
  5 |  * This script makes the Sphinx sidebar collapsible.
  6 |  *
  7 |  * .sphinxsidebar contains .sphinxsidebarwrapper.  This script adds
  8 |  * in .sphixsidebar, after .sphinxsidebarwrapper, the #sidebarbutton
  9 |  * used to collapse and expand the sidebar.
 10 |  *
 11 |  * When the sidebar is collapsed the .sphinxsidebarwrapper is hidden
 12 |  * and the width of the sidebar and the margin-left of the document
 13 |  * are decreased. When the sidebar is expanded the opposite happens.
 14 |  * This script saves a per-browser/per-session cookie used to
 15 |  * remember the position of the sidebar among the pages.
 16 |  * Once the browser is closed the cookie is deleted and the position
 17 |  * reset to the default (expanded).
 18 |  *
 19 |  * :copyright: Copyright 2007-2010 by the Sphinx team, see AUTHORS.
 20 |  * :license: BSD, see LICENSE for details.
 21 |  *
 22 |  */
 23 | 
 24 | $(function() {
 25 |   // global elements used by the functions.
 26 |   // the 'sidebarbutton' element is defined as global after its
 27 |   // creation, in the add_sidebar_button function
 28 |   var bodywrapper = $('.bodywrapper');
 29 |   var sidebar = $('.sphinxsidebar');
 30 |   var sidebarwrapper = $('.sphinxsidebarwrapper');
 31 | 
 32 |   // original margin-left of the bodywrapper and width of the sidebar
 33 |   // with the sidebar expanded
 34 |   var bw_margin_expanded = bodywrapper.css('margin-left');
 35 |   var ssb_width_expanded = sidebar.width();
 36 | 
 37 |   // margin-left of the bodywrapper and width of the sidebar
 38 |   // with the sidebar collapsed
 39 |   var bw_margin_collapsed = '.8em';
 40 |   var ssb_width_collapsed = '.8em';
 41 | 
 42 |   // colors used by the current theme
 43 |   var dark_color = $('.related').css('background-color');
 44 |   var light_color = $('.document').css('background-color');
 45 | 
 46 |   function sidebar_is_collapsed() {
 47 |     return sidebarwrapper.is(':not(:visible)');
 48 |   }
 49 | 
 50 |   function toggle_sidebar() {
 51 |     if (sidebar_is_collapsed())
 52 |       expand_sidebar();
 53 |     else
 54 |       collapse_sidebar();
 55 |   }
 56 | 
 57 |   function collapse_sidebar() {
 58 |     sidebarwrapper.hide();
 59 |     sidebar.css('width', ssb_width_collapsed);
 60 |     bodywrapper.css('margin-left', bw_margin_collapsed);
 61 |     sidebarbutton.css({
 62 |         'margin-left': '0',
 63 |         'height': bodywrapper.height()
 64 |     });
 65 |     sidebarbutton.find('span').text('»');
 66 |     sidebarbutton.attr('title', _('Expand sidebar'));
 67 |     document.cookie = 'sidebar=collapsed';
 68 |   }
 69 | 
 70 |   function expand_sidebar() {
 71 |     bodywrapper.css('margin-left', bw_margin_expanded);
 72 |     sidebar.css('width', ssb_width_expanded);
 73 |     sidebarwrapper.show();
 74 |     sidebarbutton.css({
 75 |         'margin-left': ssb_width_expanded-12,
 76 |         'height': bodywrapper.height()
 77 |     });
 78 |     sidebarbutton.find('span').text('«');
 79 |     sidebarbutton.attr('title', _('Collapse sidebar'));
 80 |     document.cookie = 'sidebar=expanded';
 81 |   }
 82 | 
 83 |   function add_sidebar_button() {
 84 |     sidebarwrapper.css({
 85 |         'float': 'left',
 86 |         'margin-right': '0',
 87 |         'width': ssb_width_expanded - 28
 88 |     });
 89 |     // create the button
 90 |     sidebar.append(
 91 |         '<div id="sidebarbutton"><span>&laquo;</span></div>'
 92 |     );
 93 |     var sidebarbutton = $('#sidebarbutton');
 94 |     // find the height of the viewport to center the '<<' in the page
 95 |     var viewport_height;
 96 |     if (window.innerHeight)
 97 |  	  viewport_height = window.innerHeight;
 98 |     else
 99 | 	  viewport_height = $(window).height();
100 |     sidebarbutton.find('span').css({
101 |         'display': 'block',
102 |         'margin-top': (viewport_height - sidebar.position().top - 20) / 2
103 |     });
104 | 
105 |     sidebarbutton.click(toggle_sidebar);
106 |     sidebarbutton.attr('title', _('Collapse sidebar'));
107 |     sidebarbutton.css({
108 |         'color': '#FFFFFF',
109 |         'border-left': '1px solid ' + dark_color,
110 |         'font-size': '1.2em',
111 |         'cursor': 'pointer',
112 |         'height': bodywrapper.height(),
113 |         'padding-top': '1px',
114 |         'margin-left': ssb_width_expanded - 12
115 |     });
116 | 
117 |     sidebarbutton.hover(
118 |       function () {
119 |           $(this).css('background-color', dark_color);
120 |       },
121 |       function () {
122 |           $(this).css('background-color', light_color);
123 |       }
124 |     );
125 |   }
126 | 
127 |   function set_position_from_cookie() {
128 |     if (!document.cookie)
129 |       return;
130 |     var items = document.cookie.split(';');
131 |     for(var k=0; k<items.length; k++) {
132 |       var key_val = items[k].split('=');
133 |       var key = key_val[0];
134 |       if (key == 'sidebar') {
135 |         var value = key_val[1];
136 |         if ((value == 'collapsed') && (!sidebar_is_collapsed()))
137 |           collapse_sidebar();
138 |         else if ((value == 'expanded') && (sidebar_is_collapsed()))
139 |           expand_sidebar();
140 |       }
141 |     }
142 |   }
143 | 
144 |   add_sidebar_button();
145 |   var sidebarbutton = $('#sidebarbutton');
146 |   set_position_from_cookie();
147 | });


--------------------------------------------------------------------------------
/docs/_static/underscore.js:
--------------------------------------------------------------------------------
 1 | (function(){var j=this,n=j._,i=function(a){this._wrapped=a},m=typeof StopIteration!=="undefined"?StopIteration:"__break__",b=j._=function(a){return new i(a)};if(typeof exports!=="undefined")exports._=b;var k=Array.prototype.slice,o=Array.prototype.unshift,p=Object.prototype.toString,q=Object.prototype.hasOwnProperty,r=Object.prototype.propertyIsEnumerable;b.VERSION="0.5.5";b.each=function(a,c,d){try{if(a.forEach)a.forEach(c,d);else if(b.isArray(a)||b.isArguments(a))for(var e=0,f=a.length;e<f;e++)c.call(d,
 2 | a[e],e,a);else{var g=b.keys(a);f=g.length;for(e=0;e<f;e++)c.call(d,a[g[e]],g[e],a)}}catch(h){if(h!=m)throw h;}return a};b.map=function(a,c,d){if(a&&b.isFunction(a.map))return a.map(c,d);var e=[];b.each(a,function(f,g,h){e.push(c.call(d,f,g,h))});return e};b.reduce=function(a,c,d,e){if(a&&b.isFunction(a.reduce))return a.reduce(b.bind(d,e),c);b.each(a,function(f,g,h){c=d.call(e,c,f,g,h)});return c};b.reduceRight=function(a,c,d,e){if(a&&b.isFunction(a.reduceRight))return a.reduceRight(b.bind(d,e),c);
 3 | var f=b.clone(b.toArray(a)).reverse();b.each(f,function(g,h){c=d.call(e,c,g,h,a)});return c};b.detect=function(a,c,d){var e;b.each(a,function(f,g,h){if(c.call(d,f,g,h)){e=f;b.breakLoop()}});return e};b.select=function(a,c,d){if(a&&b.isFunction(a.filter))return a.filter(c,d);var e=[];b.each(a,function(f,g,h){c.call(d,f,g,h)&&e.push(f)});return e};b.reject=function(a,c,d){var e=[];b.each(a,function(f,g,h){!c.call(d,f,g,h)&&e.push(f)});return e};b.all=function(a,c,d){c=c||b.identity;if(a&&b.isFunction(a.every))return a.every(c,
 4 | d);var e=true;b.each(a,function(f,g,h){(e=e&&c.call(d,f,g,h))||b.breakLoop()});return e};b.any=function(a,c,d){c=c||b.identity;if(a&&b.isFunction(a.some))return a.some(c,d);var e=false;b.each(a,function(f,g,h){if(e=c.call(d,f,g,h))b.breakLoop()});return e};b.include=function(a,c){if(b.isArray(a))return b.indexOf(a,c)!=-1;var d=false;b.each(a,function(e){if(d=e===c)b.breakLoop()});return d};b.invoke=function(a,c){var d=b.rest(arguments,2);return b.map(a,function(e){return(c?e[c]:e).apply(e,d)})};b.pluck=
 5 | function(a,c){return b.map(a,function(d){return d[c]})};b.max=function(a,c,d){if(!c&&b.isArray(a))return Math.max.apply(Math,a);var e={computed:-Infinity};b.each(a,function(f,g,h){g=c?c.call(d,f,g,h):f;g>=e.computed&&(e={value:f,computed:g})});return e.value};b.min=function(a,c,d){if(!c&&b.isArray(a))return Math.min.apply(Math,a);var e={computed:Infinity};b.each(a,function(f,g,h){g=c?c.call(d,f,g,h):f;g<e.computed&&(e={value:f,computed:g})});return e.value};b.sortBy=function(a,c,d){return b.pluck(b.map(a,
 6 | function(e,f,g){return{value:e,criteria:c.call(d,e,f,g)}}).sort(function(e,f){e=e.criteria;f=f.criteria;return e<f?-1:e>f?1:0}),"value")};b.sortedIndex=function(a,c,d){d=d||b.identity;for(var e=0,f=a.length;e<f;){var g=e+f>>1;d(a[g])<d(c)?(e=g+1):(f=g)}return e};b.toArray=function(a){if(!a)return[];if(a.toArray)return a.toArray();if(b.isArray(a))return a;if(b.isArguments(a))return k.call(a);return b.values(a)};b.size=function(a){return b.toArray(a).length};b.first=function(a,c,d){return c&&!d?k.call(a,
 7 | 0,c):a[0]};b.rest=function(a,c,d){return k.call(a,b.isUndefined(c)||d?1:c)};b.last=function(a){return a[a.length-1]};b.compact=function(a){return b.select(a,function(c){return!!c})};b.flatten=function(a){return b.reduce(a,[],function(c,d){if(b.isArray(d))return c.concat(b.flatten(d));c.push(d);return c})};b.without=function(a){var c=b.rest(arguments);return b.select(a,function(d){return!b.include(c,d)})};b.uniq=function(a,c){return b.reduce(a,[],function(d,e,f){if(0==f||(c===true?b.last(d)!=e:!b.include(d,
 8 | e)))d.push(e);return d})};b.intersect=function(a){var c=b.rest(arguments);return b.select(b.uniq(a),function(d){return b.all(c,function(e){return b.indexOf(e,d)>=0})})};b.zip=function(){for(var a=b.toArray(arguments),c=b.max(b.pluck(a,"length")),d=new Array(c),e=0;e<c;e++)d[e]=b.pluck(a,String(e));return d};b.indexOf=function(a,c){if(a.indexOf)return a.indexOf(c);for(var d=0,e=a.length;d<e;d++)if(a[d]===c)return d;return-1};b.lastIndexOf=function(a,c){if(a.lastIndexOf)return a.lastIndexOf(c);for(var d=
 9 | a.length;d--;)if(a[d]===c)return d;return-1};b.range=function(a,c,d){var e=b.toArray(arguments),f=e.length<=1;a=f?0:e[0];c=f?e[0]:e[1];d=e[2]||1;e=Math.ceil((c-a)/d);if(e<=0)return[];e=new Array(e);f=a;for(var g=0;1;f+=d){if((d>0?f-c:c-f)>=0)return e;e[g++]=f}};b.bind=function(a,c){var d=b.rest(arguments,2);return function(){return a.apply(c||j,d.concat(b.toArray(arguments)))}};b.bindAll=function(a){var c=b.rest(arguments);if(c.length==0)c=b.functions(a);b.each(c,function(d){a[d]=b.bind(a[d],a)});
10 | return a};b.delay=function(a,c){var d=b.rest(arguments,2);return setTimeout(function(){return a.apply(a,d)},c)};b.defer=function(a){return b.delay.apply(b,[a,1].concat(b.rest(arguments)))};b.wrap=function(a,c){return function(){var d=[a].concat(b.toArray(arguments));return c.apply(c,d)}};b.compose=function(){var a=b.toArray(arguments);return function(){for(var c=b.toArray(arguments),d=a.length-1;d>=0;d--)c=[a[d].apply(this,c)];return c[0]}};b.keys=function(a){if(b.isArray(a))return b.range(0,a.length);
11 | var c=[];for(var d in a)q.call(a,d)&&c.push(d);return c};b.values=function(a){return b.map(a,b.identity)};b.functions=function(a){return b.select(b.keys(a),function(c){return b.isFunction(a[c])}).sort()};b.extend=function(a,c){for(var d in c)a[d]=c[d];return a};b.clone=function(a){if(b.isArray(a))return a.slice(0);return b.extend({},a)};b.tap=function(a,c){c(a);return a};b.isEqual=function(a,c){if(a===c)return true;var d=typeof a;if(d!=typeof c)return false;if(a==c)return true;if(!a&&c||a&&!c)return false;
12 | if(a.isEqual)return a.isEqual(c);if(b.isDate(a)&&b.isDate(c))return a.getTime()===c.getTime();if(b.isNaN(a)&&b.isNaN(c))return true;if(b.isRegExp(a)&&b.isRegExp(c))return a.source===c.source&&a.global===c.global&&a.ignoreCase===c.ignoreCase&&a.multiline===c.multiline;if(d!=="object")return false;if(a.length&&a.length!==c.length)return false;d=b.keys(a);var e=b.keys(c);if(d.length!=e.length)return false;for(var f in a)if(!b.isEqual(a[f],c[f]))return false;return true};b.isEmpty=function(a){return b.keys(a).length==
13 | 0};b.isElement=function(a){return!!(a&&a.nodeType==1)};b.isArray=function(a){return!!(a&&a.concat&&a.unshift)};b.isArguments=function(a){return a&&b.isNumber(a.length)&&!b.isArray(a)&&!r.call(a,"length")};b.isFunction=function(a){return!!(a&&a.constructor&&a.call&&a.apply)};b.isString=function(a){return!!(a===""||a&&a.charCodeAt&&a.substr)};b.isNumber=function(a){return p.call(a)==="[object Number]"};b.isDate=function(a){return!!(a&&a.getTimezoneOffset&&a.setUTCFullYear)};b.isRegExp=function(a){return!!(a&&
14 | a.test&&a.exec&&(a.ignoreCase||a.ignoreCase===false))};b.isNaN=function(a){return b.isNumber(a)&&isNaN(a)};b.isNull=function(a){return a===null};b.isUndefined=function(a){return typeof a=="undefined"};b.noConflict=function(){j._=n;return this};b.identity=function(a){return a};b.breakLoop=function(){throw m;};var s=0;b.uniqueId=function(a){var c=s++;return a?a+c:c};b.template=function(a,c){a=new Function("obj","var p=[],print=function(){p.push.apply(p,arguments);};with(obj){p.push('"+a.replace(/[\r\t\n]/g,
15 | " ").replace(/'(?=[^%]*%>)/g,"\t").split("'").join("\\'").split("\t").join("'").replace(/<%=(.+?)%>/g,"',$1,'").split("<%").join("');").split("%>").join("p.push('")+"');}return p.join('');");return c?a(c):a};b.forEach=b.each;b.foldl=b.inject=b.reduce;b.foldr=b.reduceRight;b.filter=b.select;b.every=b.all;b.some=b.any;b.head=b.first;b.tail=b.rest;b.methods=b.functions;var l=function(a,c){return c?b(a).chain():a};b.each(b.functions(b),function(a){var c=b[a];i.prototype[a]=function(){var d=b.toArray(arguments);
16 | o.call(d,this._wrapped);return l(c.apply(b,d),this._chain)}});b.each(["pop","push","reverse","shift","sort","splice","unshift"],function(a){var c=Array.prototype[a];i.prototype[a]=function(){c.apply(this._wrapped,arguments);return l(this._wrapped,this._chain)}});b.each(["concat","join","slice"],function(a){var c=Array.prototype[a];i.prototype[a]=function(){return l(c.apply(this._wrapped,arguments),this._chain)}});i.prototype.chain=function(){this._chain=true;return this};i.prototype.value=function(){return this._wrapped}})();
17 | 


--------------------------------------------------------------------------------
/docs/genindex.html:
--------------------------------------------------------------------------------
  1 | 
  2 | 
  3 | <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  4 |   "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
  5 | 
  6 | <html xmlns="http://www.w3.org/1999/xhtml">
  7 |   <head>
  8 |     <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
  9 |     
 10 |     <title>Index &mdash; collectd v1.0.2 documentation</title>
 11 |     <link rel="stylesheet" href="_static/default.css" type="text/css" />
 12 |     <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
 13 |     <script type="text/javascript">
 14 |       var DOCUMENTATION_OPTIONS = {
 15 |         URL_ROOT:    '',
 16 |         VERSION:     '1.0.2',
 17 |         COLLAPSE_INDEX: false,
 18 |         FILE_SUFFIX: '.html',
 19 |         HAS_SOURCE:  true
 20 |       };
 21 |     </script>
 22 |     <script type="text/javascript" src="_static/jquery.js"></script>
 23 |     <script type="text/javascript" src="_static/underscore.js"></script>
 24 |     <script type="text/javascript" src="_static/doctools.js"></script>
 25 |     <link rel="top" title="collectd v1.0.2 documentation" href="index.html" /> 
 26 |   </head>
 27 |   <body>
 28 |     <div class="related">
 29 |       <h3>Navigation</h3>
 30 |       <ul>
 31 |         <li class="right" style="margin-right: 10px">
 32 |           <a href="#" title="General Index"
 33 |              accesskey="I">index</a></li>
 34 |         <li><a href="index.html">collectd v1.0.2 documentation</a> &raquo;</li> 
 35 |       </ul>
 36 |     </div>  
 37 | 
 38 |     <div class="document">
 39 |       <div class="documentwrapper">
 40 |         <div class="bodywrapper">
 41 |           <div class="body">
 42 |             
 43 | 
 44 |    <h1 id="index">Index</h1>
 45 | 
 46 |    <div class="genindex-jumpbox">
 47 |    <a href="#_"><strong>_</strong></a> | <a href="#C"><strong>C</strong></a> | <a href="#R"><strong>R</strong></a> | <a href="#S"><strong>S</strong></a> 
 48 |    </div>
 49 | <h2 id="_">_</h2>
 50 | <table width="100%" class="indextable genindextable"><tr>
 51 |   <td width="33%" valign="top"><dl>
 52 |     <dt><a href="index.html#Connection.__getattr__">__getattr__() (Connection method)</a></dt>
 53 | </dl></td>
 54 | </tr></table>
 55 | 
 56 | <h2 id="C">C</h2>
 57 | <table width="100%" class="indextable genindextable"><tr>
 58 |   <td width="33%" valign="top"><dl>
 59 |     <dt><a href="index.html#Connection">Connection (built-in class)</a></dt>
 60 | </dl></td>
 61 |   <td width="33%" valign="top"><dl>
 62 |     <dt><a href="index.html#Counter">Counter (built-in class)</a></dt>
 63 | </dl></td>
 64 | </tr></table>
 65 | 
 66 | <h2 id="R">R</h2>
 67 | <table width="100%" class="indextable genindextable"><tr>
 68 |   <td width="33%" valign="top"><dl>
 69 |     <dt><a href="index.html#Counter.record">record() (Counter method)</a></dt>
 70 | </dl></td>
 71 | </tr></table>
 72 | 
 73 | <h2 id="S">S</h2>
 74 | <table width="100%" class="indextable genindextable"><tr>
 75 |   <td width="33%" valign="top"><dl>
 76 |     <dt><a href="index.html#Counter.set_exact">set_exact() (Counter method)</a></dt>
 77 | </dl></td>
 78 |   <td width="33%" valign="top"><dl>
 79 |     <dt><a href="index.html#start_threads">start_threads() (built-in function)</a></dt>
 80 | </dl></td>
 81 | </tr></table>
 82 | 
 83 | 
 84 | 
 85 |           </div>
 86 |         </div>
 87 |       </div>
 88 |       <div class="sphinxsidebar">
 89 |         <div class="sphinxsidebarwrapper">
 90 | 
 91 |    
 92 | 
 93 | <div id="searchbox" style="display: none">
 94 |   <h3>Quick search</h3>
 95 |     <form class="search" action="search.html" method="get">
 96 |       <input type="text" name="q" size="18" />
 97 |       <input type="submit" value="Go" />
 98 |       <input type="hidden" name="check_keywords" value="yes" />
 99 |       <input type="hidden" name="area" value="default" />
100 |     </form>
101 |     <p class="searchtip" style="font-size: 90%">
102 |     Enter search terms or a module, class or function name.
103 |     </p>
104 | </div>
105 | <script type="text/javascript">$('#searchbox').show(0);</script>
106 |         </div>
107 |       </div>
108 |       <div class="clearer"></div>
109 |     </div>
110 |     <div class="related">
111 |       <h3>Navigation</h3>
112 |       <ul>
113 |         <li class="right" style="margin-right: 10px">
114 |           <a href="#" title="General Index"
115 |              >index</a></li>
116 |         <li><a href="index.html">collectd v1.0.2 documentation</a> &raquo;</li> 
117 |       </ul>
118 |     </div>
119 |     <div class="footer">
120 |         &copy; Copyright 2012, Eli Courtwright.
121 |       Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0.1.
122 |     </div>
123 |   </body>
124 | </html>


--------------------------------------------------------------------------------
/docs/index.html:
--------------------------------------------------------------------------------
  1 | 
  2 | 
  3 | <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  4 |   "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
  5 | 
  6 | <html xmlns="http://www.w3.org/1999/xhtml">
  7 |   <head>
  8 |     <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
  9 |     
 10 |     <title>collectd - Send statistics over UDP to collectd servers &mdash; collectd v1.0.2 documentation</title>
 11 |     <link rel="stylesheet" href="_static/default.css" type="text/css" />
 12 |     <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
 13 |     <script type="text/javascript">
 14 |       var DOCUMENTATION_OPTIONS = {
 15 |         URL_ROOT:    '',
 16 |         VERSION:     '1.0.2',
 17 |         COLLAPSE_INDEX: false,
 18 |         FILE_SUFFIX: '.html',
 19 |         HAS_SOURCE:  true
 20 |       };
 21 |     </script>
 22 |     <script type="text/javascript" src="_static/jquery.js"></script>
 23 |     <script type="text/javascript" src="_static/underscore.js"></script>
 24 |     <script type="text/javascript" src="_static/doctools.js"></script>
 25 |     <link rel="top" title="collectd v1.0.2 documentation" href="#" /> 
 26 |   </head>
 27 |   <body>
 28 |     <div class="related">
 29 |       <h3>Navigation</h3>
 30 |       <ul>
 31 |         <li class="right" style="margin-right: 10px">
 32 |           <a href="genindex.html" title="General Index"
 33 |              accesskey="I">index</a></li>
 34 |         <li><a href="#">collectd v1.0.2 documentation</a> &raquo;</li> 
 35 |       </ul>
 36 |     </div>  
 37 | 
 38 |     <div class="document">
 39 |       <div class="documentwrapper">
 40 |         <div class="bodywrapper">
 41 |           <div class="body">
 42 |             
 43 |   <div class="toctree-wrapper compound">
 44 | <ul class="simple">
 45 | </ul>
 46 | </div>
 47 | <div class="section" id="collectd-send-statistics-over-udp-to-collectd-servers">
 48 | <h1>collectd - Send statistics over UDP to collectd servers<a class="headerlink" href="#collectd-send-statistics-over-udp-to-collectd-servers" title="Permalink to this headline">¶</a></h1>
 49 | <p>This module implements the
 50 | <a class="reference external" href="http://collectd.org/wiki/index.php/Binary_protocol">binary protocol</a>
 51 | used by the
 52 | <a class="reference external" href="http://collectd.org/wiki/index.php/Plugin:Network">Network plugin</a>
 53 | to let you send arbitrary numeric data to collectd servers.  Other than turning
 54 | on the Network plugin on the destination collectd server, no configuration is
 55 | needed.</p>
 56 | <p>Although you can configure your collectd server to do anything with your
 57 | statistics, most people use the
 58 | <a class="reference external" href="http://collectd.org/wiki/index.php/Plugin:RRDtool">RRDtool plugin</a>
 59 | to efficiently store large quantities of data.  Therefore, this tutorial
 60 | will discuss the output files generated by the RRDtool plugin, even though
 61 | this module sends destination-agnostic statistics messages to your collectd
 62 | server.</p>
 63 | <p>Here&#8217;s an example of sending statistics:</p>
 64 | <div class="highlight-python"><div class="highlight"><pre><span class="kn">import</span> <span class="nn">time</span><span class="o">,</span> <span class="nn">random</span>
 65 | 
 66 | <span class="kn">import</span> <span class="nn">collectd</span>
 67 | 
 68 | <span class="n">collectd</span><span class="o">.</span><span class="n">start_threads</span><span class="p">()</span>
 69 | <span class="n">conn</span> <span class="o">=</span> <span class="n">collectd</span><span class="o">.</span><span class="n">Connection</span><span class="p">()</span>
 70 | 
 71 | <span class="k">while</span> <span class="bp">True</span><span class="p">:</span>
 72 |     <span class="n">conn</span><span class="o">.</span><span class="n">some_category</span><span class="o">.</span><span class="n">record</span><span class="p">(</span><span class="n">some_counter</span> <span class="o">=</span> <span class="mi">1</span><span class="p">,</span> <span class="n">another_stat</span> <span class="o">=</span> <span class="n">random</span><span class="o">.</span><span class="n">random</span><span class="p">())</span>
 73 |     <span class="k">if</span> <span class="n">random</span><span class="o">.</span><span class="n">randrange</span><span class="p">(</span><span class="mi">2</span><span class="p">):</span>
 74 |         <span class="n">conn</span><span class="o">.</span><span class="n">coin_stats</span><span class="o">.</span><span class="n">record</span><span class="p">(</span><span class="s">&quot;heads&quot;</span><span class="p">,</span> <span class="n">flips</span> <span class="o">=</span> <span class="mi">1</span><span class="p">)</span>
 75 |     <span class="k">else</span><span class="p">:</span>
 76 |         <span class="n">conn</span><span class="o">.</span><span class="n">coin_stats</span><span class="o">.</span><span class="n">record</span><span class="p">(</span><span class="s">&quot;tails&quot;</span><span class="p">,</span> <span class="n">flips</span> <span class="o">=</span> <span class="mi">1</span><span class="p">)</span>
 77 |     
 78 |     <span class="n">time</span><span class="o">.</span><span class="n">sleep</span><span class="p">(</span><span class="n">random</span><span class="o">.</span><span class="n">randint</span><span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="mi">4</span><span class="p">))</span>
 79 | </pre></div>
 80 | </div>
 81 | <p>If you run this script (which is <tt class="docutils literal"><span class="pre">examples/basic.py</span></tt> in your source package)
 82 | then your collectd server will create an RRD file for each statistic you are
 83 | tracking.  These files are typically stored under one central location on the
 84 | filesysem, such as <tt class="docutils literal"><span class="pre">/var/lib/collectd/rrd</span></tt> and organized by the hostname of
 85 | where the statistics came from and the name of the plugin that generated them.</p>
 86 | <p>This module identifies itself with the plugin name <tt class="docutils literal"><span class="pre">any</span></tt>, so if you ran
 87 | the above script, it would create a <tt class="docutils literal"><span class="pre">localhost/any</span></tt> directory with the
 88 | following files:</p>
 89 | <ul class="simple">
 90 | <li><tt class="docutils literal"><span class="pre">gauge-some_category-another_stat.rrd</span></tt></li>
 91 | <li><tt class="docutils literal"><span class="pre">gauge-some_category-some_counter.rrd</span></tt></li>
 92 | <li><tt class="docutils literal"><span class="pre">gauge-coin_stats-heads-flips.rrd</span></tt></li>
 93 | <li><tt class="docutils literal"><span class="pre">gauge-coin_stats-tails-flips.rrd</span></tt></li>
 94 | <li><tt class="docutils literal"><span class="pre">gauge-coin_stats-flips.rrd</span></tt> (contains the sum of heads and tails flips)</li>
 95 | </ul>
 96 | <p>Each call to <tt class="docutils literal"><span class="pre">record()</span></tt> increments the statistics you provide.  Periodically
 97 | the sums of these statistics are sent to the collectd server and then reset.
 98 | Therefore, if you displayed a graph of one of these statistics files, each
 99 | data point on the graph would represent the sum of all <tt class="docutils literal"><span class="pre">record()</span></tt> values
100 | over that time increment.</p>
101 | </div>
102 | <div class="section" id="installation">
103 | <h1>Installation<a class="headerlink" href="#installation" title="Permalink to this headline">¶</a></h1>
104 | <p>This module is free for use under the BSD license.  It requires Python 2.6 or
105 | Python 2.7 and has no other dependencies.</p>
106 | <p>You may <a class="reference external" href="https://github.com/downloads/appliedsec/collectd/collectd-1.0.1.tar.gz">click here</a>
107 | to  download the collectd module. You may also run <tt class="docutils literal"><span class="pre">easy_install</span> <span class="pre">collectd</span></tt>
108 | if you have <a class="reference external" href="http://peak.telecommunity.com/DevCenter/EasyInstall">EasyInstall</a>
109 | on your system.  The project page for collectd in the Cheese Shop (aka the Python
110 | Package Index or PyPI) <a class="reference external" href="http://pypi.python.org/pypi/collectd/">may be found here</a>.</p>
111 | <p>You may also check out the development version of collectd with this command:</p>
112 | <p><tt class="docutils literal"><span class="pre">git</span> <span class="pre">clone</span> <span class="pre">https://github.com/appliedsec/collectd.git</span></tt></p>
113 | </div>
114 | <div class="section" id="functions-and-classes">
115 | <h1>Functions and Classes<a class="headerlink" href="#functions-and-classes" title="Permalink to this headline">¶</a></h1>
116 | <dl class="function">
117 | <dt id="start_threads">
118 | <tt class="descname">start_threads</tt><big>(</big><big>)</big><a class="headerlink" href="#start_threads" title="Permalink to this definition">¶</a></dt>
119 | <dd><p>This function starts two daemon threads.  The first takes snapshots of your
120 | counters and resets them periodically.  The other serializes the statistics
121 | into protocol messages understood by the collectd Network plugin and sends
122 | them in appropriately-sized UDP packets.</p>
123 | <p>You must call this function when your program starts, or else this module
124 | will never actually send any data to any collectd servers.  Calling this
125 | function more than once throws an exception.</p>
126 | </dd></dl>
127 | 
128 | <dl class="class">
129 | <dt id="Connection">
130 | <em class="property">class </em><tt class="descname">Connection</tt><big>(</big><em>hostname = socket.gethostname()</em>, <em>collectd_host = &quot;localhost&quot;</em>, <em>collectd_port = 25826</em>, <em>plugin_inst = &quot;&quot;</em>, <em>plugin_name = &quot;any&quot;</em><big>)</big><a class="headerlink" href="#Connection" title="Permalink to this definition">¶</a></dt>
131 | <dd><p>Connection objects may be instantiated with 5 optional arguments:</p>
132 | <ul class="simple">
133 | <li><tt class="docutils literal"><span class="pre">hostname</span></tt>: the hostname you use to identify yourself to the collectd server; if omitted, this defaults to the result of <tt class="docutils literal"><span class="pre">socket.gethostname()</span></tt></li>
134 | <li><tt class="docutils literal"><span class="pre">collectd_host</span></tt>: the hostname or ip address of the collectd server to which we will send statistics</li>
135 | <li><tt class="docutils literal"><span class="pre">collectd_port</span></tt>: the port to which you will send statistics messages</li>
136 | <li><tt class="docutils literal"><span class="pre">plugin_inst</span></tt>: the plugin instance name which will be sent to the collectd server; this mostly affects the directory name used by the collectd rrdtool plugin</li>
137 | <li><tt class="docutils literal"><span class="pre">plugin_name</span></tt>: the name of the plugin with which the collectd server will associate your statistics; this mostly affects the directory tree used by the collectd rrdtool plugin</li>
138 | </ul>
139 | <p>Connection objects with identical parameters are singletons; in other
140 | words, <tt class="docutils literal"><span class="pre">Connection(&quot;foo&quot;)</span> <span class="pre">is</span> <span class="pre">Connection(&quot;foo&quot;)</span></tt> but
141 | <tt class="docutils literal"><span class="pre">Connection(&quot;foo&quot;)</span> <span class="pre">is</span> <span class="pre">not</span> <span class="pre">Connection(&quot;bar&quot;)</span></tt>.</p>
142 | <dl class="method">
143 | <dt id="Connection.__getattr__">
144 | <tt class="descname">__getattr__</tt><big>(</big><em>name</em><big>)</big><a class="headerlink" href="#Connection.__getattr__" title="Permalink to this definition">¶</a></dt>
145 | <dd><p>Statistics are recorded through <tt class="docutils literal"><span class="pre">Counter</span></tt> objects, which are
146 | dynamically generated by accessing fields on <tt class="docutils literal"><span class="pre">Connection</span></tt> instances.
147 | So saying <tt class="docutils literal"><span class="pre">conn.foo</span></tt> creates a <tt class="docutils literal"><span class="pre">Counter</span></tt> object.</p>
148 | <p>These objects are distinct but cached, so <tt class="docutils literal"><span class="pre">conn.foo</span> <span class="pre">is</span> <span class="pre">conn.foo</span></tt> but
149 | <tt class="docutils literal"><span class="pre">conn.foo</span> <span class="pre">is</span> <span class="pre">not</span> <span class="pre">conn.bar</span></tt>.</p>
150 | </dd></dl>
151 | 
152 | </dd></dl>
153 | 
154 | <dl class="class">
155 | <dt id="Counter">
156 | <em class="property">class </em><tt class="descname">Counter</tt><big>(</big><em>category</em><big>)</big><a class="headerlink" href="#Counter" title="Permalink to this definition">¶</a></dt>
157 | <dd><p>You shouldn&#8217;t directly instantiate this class; instead <tt class="docutils literal"><span class="pre">Counter</span></tt> objects
158 | are automatically created by accessing attributes of <tt class="docutils literal"><span class="pre">Connection</span></tt> objects
159 | such that <tt class="docutils literal"><span class="pre">conn.foo</span></tt> will cache and return <tt class="docutils literal"><span class="pre">Counter(&quot;foo&quot;)</span></tt>.</p>
160 | <p>Both of the following methods swallow and log all possible exceptions, so
161 | you never need to worry about an error being thrown by calls to either of
162 | these methods.  These functions are also synchronized, so you can safely
163 | call them simultaneously from different threads.</p>
164 | <dl class="method">
165 | <dt id="Counter.record">
166 | <tt class="descname">record</tt><big>(</big><em>*specific</em>, <em>**stats</em><big>)</big><a class="headerlink" href="#Counter.record" title="Permalink to this definition">¶</a></dt>
167 | <dd><p>Each keyword argument to this method is interpreted as a statistic,
168 | whose name is the argument name, and whose value is incrementd by
169 | the argument value.</p>
170 | <p>You may pass one or more string identifiers as positional arguments
171 | to this method.  If you do so, then separate statistic counts will
172 | be maintained for this identifier.  These counts are always added
173 | to the base count for each statistic.</p>
174 | <p>For example, if you ran the following code</p>
175 | <div class="highlight-python"><div class="highlight"><pre><span class="n">conn</span> <span class="o">=</span> <span class="n">collectd</span><span class="o">.</span><span class="n">Connection</span><span class="p">()</span>
176 | <span class="n">conn</span><span class="o">.</span><span class="n">example</span><span class="o">.</span><span class="n">record</span><span class="p">(</span><span class="n">baz</span> <span class="o">=</span> <span class="mi">1</span><span class="p">)</span>
177 | <span class="n">conn</span><span class="o">.</span><span class="n">example</span><span class="o">.</span><span class="n">record</span><span class="p">(</span><span class="s">&quot;foo&quot;</span><span class="p">,</span> <span class="n">baz</span> <span class="o">=</span> <span class="mi">2</span><span class="p">)</span>
178 | <span class="n">conn</span><span class="o">.</span><span class="n">example</span><span class="o">.</span><span class="n">record</span><span class="p">(</span><span class="s">&quot;bar&quot;</span><span class="p">,</span> <span class="n">baz</span> <span class="o">=</span> <span class="mi">3</span><span class="p">)</span>
179 | </pre></div>
180 | </div>
181 | <p>and then statistics were sent to the collectd server, it would result
182 | in the following files:</p>
183 | <ul class="simple">
184 | <li><tt class="docutils literal"><span class="pre">gauge-example-baz.rrd</span></tt> (with a value of 6 for this time increment)</li>
185 | <li><tt class="docutils literal"><span class="pre">gauge-example-foo-baz.rrd</span></tt> (with a value of 2 for this time increment)</li>
186 | <li><tt class="docutils literal"><span class="pre">gauge-example-bar-baz.rrd</span></tt> (with a value of 3 for this time increment)</li>
187 | </ul>
188 | </dd></dl>
189 | 
190 | <dl class="method">
191 | <dt id="Counter.set_exact">
192 | <tt class="descname">set_exact</tt><big>(</big><em>**stats</em><big>)</big><a class="headerlink" href="#Counter.set_exact" title="Permalink to this definition">¶</a></dt>
193 | <dd><p>Each keyword argument to this method is interpreted as a statistic,
194 | whose name is the argument name, and whose value is set to the exact
195 | value of the argument.  Use this method when you have values which you
196 | wish to update to a specific value rather than increment.</p>
197 | </dd></dl>
198 | 
199 | </dd></dl>
200 | 
201 | <div class="admonition warning">
202 | <p class="first admonition-title">Warning</p>
203 | <p>All names are sanitized to contain only alphanumeric characters separated
204 | by underscores.  In other words, if you did something like</p>
205 | <div class="highlight-python"><div class="highlight"><pre><span class="n">conn</span> <span class="o">=</span> <span class="n">collectd</span><span class="o">.</span><span class="n">Connection</span><span class="p">()</span>
206 | <span class="n">counter</span> <span class="o">=</span> <span class="nb">getattr</span><span class="p">(</span><span class="n">conn</span><span class="p">,</span> <span class="s">&quot;^@#@foo%$&amp;&amp;*&quot;</span><span class="p">)</span>
207 | <span class="n">stat</span> <span class="o">=</span> <span class="p">{</span><span class="s">&quot;*()#@spam!@$^&amp;*&quot;</span><span class="p">:</span> <span class="mi">1</span><span class="p">}</span>
208 | <span class="n">counter</span><span class="o">.</span><span class="n">record</span><span class="p">(</span><span class="s">&quot;()#@bar&amp;*()baz$^_+&quot;</span><span class="p">,</span> <span class="o">**</span><span class="n">stat</span><span class="p">)</span>
209 | </pre></div>
210 | </div>
211 | <p>then the resulting files would be named <tt class="docutils literal"><span class="pre">gauge-foo-spam.rrd</span></tt> and
212 | <tt class="docutils literal"><span class="pre">gauge-foo-bar_baz-spam.rrd</span></tt>. Although this behavior is generally
213 | desirable, it could lead to your statistics becoming merged.  For example,
214 | the <tt class="docutils literal"><span class="pre">foo-bar</span></tt> and <tt class="docutils literal"><span class="pre">foo/bar</span></tt> statistics in the following code would be
215 | combined into a single <tt class="docutils literal"><span class="pre">foo_bar</span></tt> statistic:</p>
216 | <div class="last highlight-python"><div class="highlight"><pre><span class="n">conn</span> <span class="o">=</span> <span class="n">collectd</span><span class="o">.</span><span class="n">Connection</span><span class="p">()</span>
217 | <span class="n">conn</span><span class="o">.</span><span class="n">foo</span><span class="o">.</span><span class="n">record</span><span class="p">(</span><span class="s">&quot;foo-bar&quot;</span><span class="p">,</span> <span class="n">baz</span> <span class="o">=</span> <span class="mi">2</span><span class="p">)</span>
218 | <span class="n">conn</span><span class="o">.</span><span class="n">foo</span><span class="o">.</span><span class="n">record</span><span class="p">(</span><span class="s">&quot;foo/bar&quot;</span><span class="p">,</span> <span class="n">baz</span> <span class="o">=</span> <span class="mi">3</span><span class="p">)</span>
219 | </pre></div>
220 | </div>
221 | </div>
222 | </div>
223 | <div class="section" id="logging">
224 | <h1>Logging<a class="headerlink" href="#logging" title="Permalink to this headline">¶</a></h1>
225 | <p>As mentioned above, collectd swallows exceptions so that you never have to
226 | worry about calling a function from this module and triggering an exception.
227 | However, any exceptions which do occur are logged using the
228 | <a class="reference external" href="http://docs.python.org/library/logging.html">logging</a> module from the
229 | standard library, specifically to the <cite>collectd</cite> logger.  No other logging
230 | is performed.</p>
231 | <p>However, this module defines no handlers for the <cite>collectd</cite> logger, so by
232 | default nothing is done with any of these log messages.</p>
233 | </div>
234 | <div class="section" id="a-more-complex-example">
235 | <h1>A More Complex Example<a class="headerlink" href="#a-more-complex-example" title="Permalink to this headline">¶</a></h1>
236 | <p>The following code is available in the <tt class="docutils literal"><span class="pre">examples/primes.py</span></tt> file in your
237 | source distribution:</p>
238 | <div class="highlight-python"><div class="highlight"><pre><span class="kn">import</span> <span class="nn">time</span>
239 | <span class="kn">from</span> <span class="nn">Queue</span> <span class="kn">import</span> <span class="n">Queue</span>
240 | <span class="kn">from</span> <span class="nn">threading</span> <span class="kn">import</span> <span class="n">Thread</span>
241 | <span class="kn">from</span> <span class="nn">random</span> <span class="kn">import</span> <span class="n">normalvariate</span>
242 | 
243 | <span class="kn">import</span> <span class="nn">collectd</span>
244 | 
245 | <span class="n">numbers</span> <span class="o">=</span> <span class="n">Queue</span><span class="p">()</span>
246 | <span class="n">conn</span> <span class="o">=</span> <span class="n">collectd</span><span class="o">.</span><span class="n">Connection</span><span class="p">()</span>
247 | 
248 | <span class="k">def</span> <span class="nf">is_prime</span><span class="p">(</span><span class="n">n</span><span class="p">):</span>
249 |     <span class="k">for</span> <span class="n">i</span> <span class="ow">in</span> <span class="nb">xrange</span><span class="p">(</span><span class="mi">2</span><span class="p">,</span> <span class="n">n</span><span class="p">):</span>
250 |         <span class="k">if</span> <span class="n">n</span> <span class="o">%</span> <span class="n">i</span> <span class="o">==</span> <span class="mi">0</span><span class="p">:</span>
251 |             <span class="k">return</span> <span class="bp">False</span>
252 |     <span class="k">return</span> <span class="bp">True</span>
253 | 
254 | <span class="k">def</span> <span class="nf">watch_queue</span><span class="p">():</span>
255 |     <span class="k">while</span> <span class="bp">True</span><span class="p">:</span>
256 |         <span class="n">conn</span><span class="o">.</span><span class="n">queue</span><span class="o">.</span><span class="n">set_exact</span><span class="p">(</span><span class="n">size</span> <span class="o">=</span> <span class="n">numbers</span><span class="o">.</span><span class="n">qsize</span><span class="p">())</span>
257 |         <span class="n">time</span><span class="o">.</span><span class="n">sleep</span><span class="p">(</span><span class="mi">1</span><span class="p">)</span>
258 | 
259 | <span class="k">def</span> <span class="nf">consumer</span><span class="p">():</span>
260 |     <span class="k">while</span> <span class="bp">True</span><span class="p">:</span>
261 |         <span class="n">n</span> <span class="o">=</span> <span class="n">numbers</span><span class="o">.</span><span class="n">get</span><span class="p">()</span>
262 |         <span class="n">before</span> <span class="o">=</span> <span class="n">time</span><span class="o">.</span><span class="n">time</span><span class="p">()</span>
263 |         <span class="n">primality</span> <span class="o">=</span> <span class="n">is_prime</span><span class="p">(</span><span class="n">n</span><span class="p">)</span>
264 |         <span class="n">elapsed</span> <span class="o">=</span> <span class="n">time</span><span class="o">.</span><span class="n">time</span><span class="p">()</span> <span class="o">-</span> <span class="n">before</span>
265 |         <span class="k">if</span> <span class="n">primality</span><span class="p">:</span>
266 |             <span class="k">print</span> <span class="n">n</span><span class="p">,</span> <span class="s">&quot;is prime&quot;</span>
267 |             <span class="n">conn</span><span class="o">.</span><span class="n">consumer</span><span class="o">.</span><span class="n">record</span><span class="p">(</span><span class="s">&quot;prime&quot;</span><span class="p">,</span> <span class="n">count</span> <span class="o">=</span> <span class="mi">1</span><span class="p">,</span> <span class="n">time</span> <span class="o">=</span> <span class="n">elapsed</span><span class="p">)</span>
268 |         <span class="k">else</span><span class="p">:</span>
269 |             <span class="k">print</span> <span class="n">n</span><span class="p">,</span> <span class="s">&quot;is not prime&quot;</span>
270 |             <span class="n">conn</span><span class="o">.</span><span class="n">consumer</span><span class="o">.</span><span class="n">record</span><span class="p">(</span><span class="s">&quot;composite&quot;</span><span class="p">,</span> <span class="n">count</span> <span class="o">=</span> <span class="mi">1</span><span class="p">,</span> <span class="n">time</span> <span class="o">=</span> <span class="n">elapsed</span><span class="p">)</span>
271 | 
272 | <span class="k">def</span> <span class="nf">producer</span><span class="p">():</span>
273 |     <span class="k">while</span> <span class="bp">True</span><span class="p">:</span>
274 |         <span class="n">n</span> <span class="o">=</span> <span class="nb">int</span><span class="p">((</span><span class="n">time</span><span class="o">.</span><span class="n">time</span><span class="p">()</span> <span class="o">%</span> <span class="mi">30</span><span class="p">)</span> <span class="o">**</span> <span class="n">normalvariate</span><span class="p">(</span><span class="mi">5</span><span class="p">,</span> <span class="mi">2</span><span class="p">))</span>
275 |         <span class="k">if</span> <span class="n">n</span> <span class="o">&lt;</span> <span class="mi">2</span><span class="p">:</span>
276 |             <span class="n">conn</span><span class="o">.</span><span class="n">producer</span><span class="o">.</span><span class="n">record</span><span class="p">(</span><span class="n">too_small</span> <span class="o">=</span> <span class="mi">1</span><span class="p">)</span>
277 |         <span class="k">elif</span> <span class="n">n</span> <span class="o">&gt;</span> <span class="mi">10</span> <span class="o">**</span> <span class="mi">9</span><span class="p">:</span>
278 |             <span class="n">conn</span><span class="o">.</span><span class="n">producer</span><span class="o">.</span><span class="n">record</span><span class="p">(</span><span class="n">too_big</span> <span class="o">=</span> <span class="mi">1</span><span class="p">)</span>
279 |         <span class="k">else</span><span class="p">:</span>
280 |             <span class="n">conn</span><span class="o">.</span><span class="n">producer</span><span class="o">.</span><span class="n">record</span><span class="p">(</span><span class="n">just_right</span> <span class="o">=</span> <span class="mi">1</span><span class="p">)</span>
281 |             <span class="n">numbers</span><span class="o">.</span><span class="n">put</span><span class="p">(</span><span class="n">n</span><span class="p">)</span>
282 |         <span class="n">time</span><span class="o">.</span><span class="n">sleep</span><span class="p">(</span><span class="mf">0.33</span><span class="p">)</span>
283 | 
284 | <span class="k">if</span> <span class="n">__name__</span> <span class="o">==</span> <span class="s">&quot;__main__&quot;</span><span class="p">:</span>
285 |     <span class="n">collectd</span><span class="o">.</span><span class="n">start_threads</span><span class="p">()</span>
286 |     <span class="k">for</span> <span class="n">func</span> <span class="ow">in</span> <span class="p">[</span><span class="n">producer</span><span class="p">,</span> <span class="n">consumer</span><span class="p">]:</span>
287 |         <span class="n">t</span> <span class="o">=</span> <span class="n">Thread</span><span class="p">(</span><span class="n">target</span> <span class="o">=</span> <span class="n">func</span><span class="p">)</span>
288 |         <span class="n">t</span><span class="o">.</span><span class="n">daemon</span> <span class="o">=</span> <span class="bp">True</span>
289 |         <span class="n">t</span><span class="o">.</span><span class="n">start</span><span class="p">()</span>
290 |     
291 |     <span class="n">watch_queue</span><span class="p">()</span>
292 | </pre></div>
293 | </div>
294 | <p>Here&#8217;s a list of files generated by this code, along with an explanation of
295 | the counter which each file contains for each time interval:</p>
296 | <ul class="simple">
297 | <li><tt class="docutils literal"><span class="pre">gauge-queue-size.rrd</span></tt>: a snapshot of the size of the numbers queue</li>
298 | <li><tt class="docutils literal"><span class="pre">gauge-producer-too_small.rrd</span></tt>: a count of the random numbers generated by the producer thread which were discarded for being too small</li>
299 | <li><tt class="docutils literal"><span class="pre">gauge-producer-too_big.rrd</span></tt>: a count of the random numbers generated by the producer thread which were discarded for being too large</li>
300 | <li><tt class="docutils literal"><span class="pre">gauge-producer-just_right.rrd</span></tt>: a count of the random numbers generated by the producer thread which were sent to the consumer thread for factoring</li>
301 | <li><tt class="docutils literal"><span class="pre">gauge-consumer-count.rrd</span></tt>: an overall count of the numbers factored by the consumer thread</li>
302 | <li><tt class="docutils literal"><span class="pre">gauge-consumer-composite-count.rrd</span></tt>: a count of the numbers factored by the consumer thread which turned out to be non-prime</li>
303 | <li><tt class="docutils literal"><span class="pre">gauge-consumer-prime-count.rrd</span></tt>: a count of the numbers factored by the consumer thread which turned out to be prime</li>
304 | <li><tt class="docutils literal"><span class="pre">gauge-consumer-time.rrd</span></tt>: the amount of wallclock time elapsed while factoring numbers</li>
305 | <li><tt class="docutils literal"><span class="pre">gauge-consumer-composite-time.rrd</span></tt>: the amount of wallclock time elapsed while factoring numbers which turned out to be non-prime</li>
306 | <li><tt class="docutils literal"><span class="pre">gauge-consumer-prime-time.rrd</span></tt>: the amount of wallclock time elapsed while factoring numbers which turned out to be prime</li>
307 | </ul>
308 | <p>TODO: add graphs to this example to demonstrate what the data looks like</p>
309 | </div>
310 | <div class="section" id="a-utility-for-graphing-rrd-data">
311 | <h1>A Utility for Graphing RRD Data<a class="headerlink" href="#a-utility-for-graphing-rrd-data" title="Permalink to this headline">¶</a></h1>
312 | <p>This is forthcoming; we&#8217;d like a simple script for generating the complex
313 | command-line arguments understood by <tt class="docutils literal"><span class="pre">rrdtool</span> <span class="pre">graph</span></tt> commands.</p>
314 | <p>At some point we may also want a web interface similar to the existing
315 | collectd cgi script which dynamically lets you select and generate graphs,
316 | but with awareness of the semantics of the files generated by this module,
317 | which would allow users to start with a high-level overview and drill-down
318 | into specific data, combine data from different sources into one graph, etc.</p>
319 | </div>
320 | 
321 | 
322 |           </div>
323 |         </div>
324 |       </div>
325 |       <div class="sphinxsidebar">
326 |         <div class="sphinxsidebarwrapper">
327 |   <h3><a href="#">Table Of Contents</a></h3>
328 |   <ul>
329 | <li><a class="reference internal" href="#">collectd - Send statistics over UDP to collectd servers</a></li>
330 | <li><a class="reference internal" href="#installation">Installation</a></li>
331 | <li><a class="reference internal" href="#functions-and-classes">Functions and Classes</a></li>
332 | <li><a class="reference internal" href="#logging">Logging</a></li>
333 | <li><a class="reference internal" href="#a-more-complex-example">A More Complex Example</a></li>
334 | <li><a class="reference internal" href="#a-utility-for-graphing-rrd-data">A Utility for Graphing RRD Data</a></li>
335 | </ul>
336 | 
337 |   <h3>This Page</h3>
338 |   <ul class="this-page-menu">
339 |     <li><a href="_sources/index.txt"
340 |            rel="nofollow">Show Source</a></li>
341 |   </ul>
342 | <div id="searchbox" style="display: none">
343 |   <h3>Quick search</h3>
344 |     <form class="search" action="search.html" method="get">
345 |       <input type="text" name="q" size="18" />
346 |       <input type="submit" value="Go" />
347 |       <input type="hidden" name="check_keywords" value="yes" />
348 |       <input type="hidden" name="area" value="default" />
349 |     </form>
350 |     <p class="searchtip" style="font-size: 90%">
351 |     Enter search terms or a module, class or function name.
352 |     </p>
353 | </div>
354 | <script type="text/javascript">$('#searchbox').show(0);</script>
355 |         </div>
356 |       </div>
357 |       <div class="clearer"></div>
358 |     </div>
359 |     <div class="related">
360 |       <h3>Navigation</h3>
361 |       <ul>
362 |         <li class="right" style="margin-right: 10px">
363 |           <a href="genindex.html" title="General Index"
364 |              >index</a></li>
365 |         <li><a href="#">collectd v1.0.2 documentation</a> &raquo;</li> 
366 |       </ul>
367 |     </div>
368 |     <div class="footer">
369 |         &copy; Copyright 2012, Eli Courtwright.
370 |       Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0.1.
371 |     </div>
372 |   </body>
373 | </html>


--------------------------------------------------------------------------------
/docs/objects.inv:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/appliedsec/collectd/7b51edfd08e055149b446e9839c4dc0bc7c834ce/docs/objects.inv


--------------------------------------------------------------------------------
/docs/search.html:
--------------------------------------------------------------------------------
 1 | 
 2 | 
 3 | <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
 4 |   "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
 5 | 
 6 | <html xmlns="http://www.w3.org/1999/xhtml">
 7 |   <head>
 8 |     <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
 9 |     
10 |     <title>Search &mdash; collectd v1.0.2 documentation</title>
11 |     <link rel="stylesheet" href="_static/default.css" type="text/css" />
12 |     <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
13 |     <script type="text/javascript">
14 |       var DOCUMENTATION_OPTIONS = {
15 |         URL_ROOT:    '',
16 |         VERSION:     '1.0.2',
17 |         COLLAPSE_INDEX: false,
18 |         FILE_SUFFIX: '.html',
19 |         HAS_SOURCE:  true
20 |       };
21 |     </script>
22 |     <script type="text/javascript" src="_static/jquery.js"></script>
23 |     <script type="text/javascript" src="_static/underscore.js"></script>
24 |     <script type="text/javascript" src="_static/doctools.js"></script>
25 |     <script type="text/javascript" src="_static/searchtools.js"></script>
26 |     <link rel="top" title="collectd v1.0.2 documentation" href="index.html" />
27 |   <script type="text/javascript">
28 |     jQuery(function() { Search.loadIndex("searchindex.js"); });
29 |   </script>
30 |    
31 | 
32 |   </head>
33 |   <body>
34 |     <div class="related">
35 |       <h3>Navigation</h3>
36 |       <ul>
37 |         <li class="right" style="margin-right: 10px">
38 |           <a href="genindex.html" title="General Index"
39 |              accesskey="I">index</a></li>
40 |         <li><a href="index.html">collectd v1.0.2 documentation</a> &raquo;</li> 
41 |       </ul>
42 |     </div>  
43 | 
44 |     <div class="document">
45 |       <div class="documentwrapper">
46 |         <div class="bodywrapper">
47 |           <div class="body">
48 |             
49 |   <h1 id="search-documentation">Search</h1>
50 |   <div id="fallback" class="admonition warning">
51 |   <script type="text/javascript">$('#fallback').hide();</script>
52 |   <p>
53 |     Please activate JavaScript to enable the search
54 |     functionality.
55 |   </p>
56 |   </div>
57 |   <p>
58 |     From here you can search these documents. Enter your search
59 |     words into the box below and click "search". Note that the search
60 |     function will automatically search for all of the words. Pages
61 |     containing fewer words won't appear in the result list.
62 |   </p>
63 |   <form action="" method="get">
64 |     <input type="text" name="q" value="" />
65 |     <input type="submit" value="search" />
66 |     <span id="search-progress" style="padding-left: 10px"></span>
67 |   </form>
68 |   
69 |   <div id="search-results">
70 |   
71 |   </div>
72 | 
73 |           </div>
74 |         </div>
75 |       </div>
76 |       <div class="sphinxsidebar">
77 |         <div class="sphinxsidebarwrapper">
78 |         </div>
79 |       </div>
80 |       <div class="clearer"></div>
81 |     </div>
82 |     <div class="related">
83 |       <h3>Navigation</h3>
84 |       <ul>
85 |         <li class="right" style="margin-right: 10px">
86 |           <a href="genindex.html" title="General Index"
87 |              >index</a></li>
88 |         <li><a href="index.html">collectd v1.0.2 documentation</a> &raquo;</li> 
89 |       </ul>
90 |     </div>
91 |     <div class="footer">
92 |         &copy; Copyright 2012, Eli Courtwright.
93 |       Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0.1.
94 |     </div>
95 |   </body>
96 | </html>


--------------------------------------------------------------------------------
/docs/searchindex.js:
--------------------------------------------------------------------------------
1 | Search.setIndex({objects:{"":{Connection:[0,1,1],Counter:[0,1,1],start_threads:[0,2,1]},Connection:{"__getattr__":[0,0,1]},Counter:{record:[0,0,1],set_exact:[0,0,1]}},terms:{all:0,code:0,consum:0,sleep:0,follow:0,whose:0,depend:0,graph:0,send:0,tail:0,program:0,under:0,sent:0,sourc:0,string:0,fals:0,util:0,affect:0,exact:0,implement:0,level:0,did:0,list:0,small:0,rrd:0,another_stat:0,pass:0,download:0,click:0,even:0,index:0,what:0,filler:[],sum:0,access:0,version:0,method:0,hasn:[],abov:0,gener:0,never:0,here:0,shouldn:0,let:0,address:0,along:0,becom:0,interpret:0,queue:0,amount:0,incrementd:0,aka:0,normalvari:0,semant:0,modul:0,put:0,instal:0,select:0,from:0,would:0,distinct:0,two:0,handler:0,call:0,checkout:[],more:0,desir:0,peopl:0,appliedsec:0,warn:0,particular:[],central:0,cach:0,must:0,none:[],word:0,work:[],can:0,drill:0,def:0,high:0,want:0,serial:0,occur:0,alwai:0,rather:0,how:[],instead:0,simpl:0,updat:0,clone:0,befor:0,some_categori:0,mai:0,underscor:0,data:0,demonstr:0,github:0,gethostnam:0,tutori:0,counter:0,maintain:0,combin:0,allow:0,elif:0,composit:0,over:0,through:0,dynam:0,paramet:0,collectd_host:0,therefor:0,non:0,"return":0,python:0,overal:0,mention:0,discuss:0,too_big:0,name:0,anyth:0,separ:0,some_count:0,each:0,found:0,bar_baz:0,connect:0,our:[],todo:0,out:0,network:0,foo_bar:0,categori:0,print:0,free:0,standard:0,base:0,releas:[],org:[],asi:[],thrown:0,thread:0,could:0,omit:0,synchron:0,turn:0,first:0,singleton:0,directli:0,onc:0,number:0,yourself:0,done:0,open:[],coin_flip:[],size:0,differ:0,script:0,associ:0,licens:0,system:0,messag:0,too:0,store:0,forthcom:0,udp:0,option:0,packet:0,mostli:0,than:0,target:0,keyword:0,provid:0,tree:0,charact:0,project:0,were:0,posit:0,sai:0,randrang:0,ran:0,argument:0,packag:0,have:0,"__main__":0,need:0,lib:0,randint:0,wallclock:0,also:0,exampl:0,take:0,which:0,noth:0,singl:0,sure:[],distribut:0,though:0,track:0,object:0,too_smal:0,most:0,plan:[],bsd:0,"class":0,clear:[],later:[],quantiti:0,snapshot:0,section:[],came:0,shop:0,random:0,watch_queu:0,protocol:0,just_right:0,onli:0,locat:0,configur:0,factor:0,local:[],reset:0,get:0,pypi:0,collectd_port:0,requir:0,prime:0,bar:0,organ:0,baz:0,statist:0,contain:0,gaug:0,where:0,set:0,collectd:0,displai:0,sec:[],result:0,awar:0,someth:0,getattr:0,plugin_inst:0,"import":0,attribut:0,numer:0,xrang:0,both:0,plugin:0,howev:0,etc:0,instanc:0,swallow:0,com:0,point:0,instanti:0,overview:0,period:0,is_prim:0,filesysem:0,been:[],trigger:0,valu:0,basic:0,set_exact:0,ani:0,func:0,ident:0,look:0,defin:0,"while":0,behavior:0,error:0,increment:0,them:0,worri:0,destin:0,itself:0,conn:0,develop:0,perform:0,port:0,binari:0,complex:0,eventu:[],safe:0,http:0,hostnam:0,user:0,typic:0,rrdtool:0,appropri:0,chees:0,command:0,thi:0,explan:0,identifi:0,just:[],simultan:0,web:0,except:0,add:0,els:0,logger:0,sanit:0,agnost:0,coin_stat:0,daemon:0,like:0,specif:0,arbitrari:0,elaps:0,server:0,either:0,output:0,page:0,interv:0,some:0,understood:0,courtwright:[],librari:0,lead:0,"__getattr__":0,larg:0,foo:0,localhost:0,cgi:0,run:0,although:0,meantim:[],"__name__":0,"throw":0,about:0,actual:0,socket:0,plugin_nam:0,you:0,discard:0,produc:0,qsize:0,effici:0,primal:0,easy_instal:0,automat:0,down:0,your:0,merg:0,git:0,log:0,spam:0,avail:0,start:0,interfac:0,"var":0,"function":0,head:0,link:[],line:0,"true":0,count:0,possibl:0,"default":0,wish:0,googlecod:[],flip:0,record:0,easyinstal:0,similar:0,creat:0,"int":0,repres:0,exist:0,file:0,check:0,when:0,field:0,other:0,test:[],presum:[],stat:0,svn:[],start_thread:0,directori:0,alphanumer:0,time:0},objtypes:{"0":"py:method","1":"py:class","2":"py:function"},titles:["collectd - Send statistics over UDP to collectd servers"],objnames:{"0":"Python method","1":"Python class","2":"Python function"},filenames:["index"]})


--------------------------------------------------------------------------------
/examples/basic.py:
--------------------------------------------------------------------------------
 1 | import time, random
 2 | 
 3 | import collectd
 4 | 
 5 | collectd.start_threads()
 6 | conn = collectd.Connection()
 7 | 
 8 | while True:
 9 |     conn.some_category.record(some_counter = 1, another_stat = random.random())
10 |     if random.randrange(2):
11 |         conn.coin_stats.record("heads", flips = 1)
12 |     else:
13 |         conn.coin_stats.record("tails", flips = 1)
14 |     
15 |     time.sleep(random.randint(1, 4))
16 | 


--------------------------------------------------------------------------------
/examples/primes.py:
--------------------------------------------------------------------------------
 1 | import time
 2 | from Queue import Queue
 3 | from threading import Thread
 4 | from random import normalvariate
 5 | 
 6 | import collectd
 7 | 
 8 | numbers = Queue()
 9 | conn = collectd.Connection()
10 | 
11 | def is_prime(n):
12 |     for i in xrange(2, n):
13 |         if n % i == 0:
14 |             return False
15 |     return True
16 | 
17 | def watch_queue():
18 |     while True:
19 |         conn.queue.set_exact(size = numbers.qsize())
20 |         time.sleep(1)
21 | 
22 | def consumer():
23 |     while True:
24 |         n = numbers.get()
25 |         before = time.time()
26 |         primality = is_prime(n)
27 |         elapsed = time.time() - before
28 |         if primality:
29 |             print n, "is prime"
30 |             conn.consumer.record("prime", count = 1, time = elapsed)
31 |         else:
32 |             print n, "is not prime"
33 |             conn.consumer.record("composite", count = 1, time = elapsed)
34 | 
35 | def producer():
36 |     while True:
37 |         n = int((time.time() % 30) ** normalvariate(5, 2))
38 |         if n < 2:
39 |             conn.producer.record(too_small = 1)
40 |         elif n > 10 ** 9:
41 |             conn.producer.record(too_big = 1)
42 |         else:
43 |             conn.producer.record(just_right = 1)
44 |             numbers.put(n)
45 |         time.sleep(0.33)
46 | 
47 | if __name__ == "__main__":
48 |     collectd.start_threads()
49 |     for func in [producer, consumer]:
50 |         t = Thread(target = func)
51 |         t.daemon = True
52 |         t.start()
53 |     
54 |     watch_queue()
55 | 


--------------------------------------------------------------------------------
/setup.py:
--------------------------------------------------------------------------------
 1 | from setuptools import setup
 2 | 
 3 | setup(
 4 |     name = "collectd",
 5 |     version = "1.0.2",
 6 |     py_modules = ["collectd"],
 7 |     
 8 |     author = "Eli Courtwright",
 9 |     author_email = "eli@courtwright.org",
10 |     description = "library for sending statistics over UDP to collectd servers",
11 |     license = "BSD",
12 |     url = "https://github.com/appliedsec/collectd",
13 |     
14 |     download_url = "https://github.com/downloads/appliedsec/collectd/collectd-1.0.2.tar.gz",
15 |     
16 |     classifiers = [
17 |         "Programming Language :: Python",
18 |         "Programming Language :: Python :: 2.6",
19 |         "Programming Language :: Python :: 2.7",
20 |         "License :: OSI Approved :: BSD License",
21 |         "Operating System :: OS Independent",
22 |         "Development Status :: 4 - Beta",
23 |         "Intended Audience :: Developers",
24 |         "Topic :: Software Development :: Libraries :: Python Modules",
25 |         "Topic :: System :: Logging",
26 |         "Topic :: System :: Networking",
27 |         "Topic :: System :: Monitoring",
28 |         "Topic :: System :: Networking :: Monitoring",
29 |     ],
30 |     
31 |     long_description = """\
32 | This Python module implements the binary protocol used by the collectd Network
33 | plugin to let you send arbitrary numeric data to collectd servers. Other than
34 | turning on the Network plugin on the destination collectd server, no
35 | configuration is needed."""
36 | )
37 | 


--------------------------------------------------------------------------------
/sphinx/Makefile:
--------------------------------------------------------------------------------
 1 | # Makefile for Sphinx documentation
 2 | #
 3 | 
 4 | # You can set these variables from the command line.
 5 | SPHINXOPTS    =
 6 | SPHINXBUILD   = sphinx-build
 7 | PAPER         =
 8 | BUILDDIR      = build
 9 | 
10 | # Internal variables.
11 | PAPEROPT_a4     = -D latex_paper_size=a4
12 | PAPEROPT_letter = -D latex_paper_size=letter
13 | ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
14 | 
15 | .PHONY: help clean html dirhtml pickle json htmlhelp qthelp latex changes linkcheck doctest
16 | 
17 | help:
18 | 	@echo "Please use \`make <target>' where <target> is one of"
19 | 	@echo "  html      to make standalone HTML files"
20 | 	@echo "  dirhtml   to make HTML files named index.html in directories"
21 | 	@echo "  pickle    to make pickle files"
22 | 	@echo "  json      to make JSON files"
23 | 	@echo "  htmlhelp  to make HTML files and a HTML help project"
24 | 	@echo "  qthelp    to make HTML files and a qthelp project"
25 | 	@echo "  latex     to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
26 | 	@echo "  changes   to make an overview of all changed/added/deprecated items"
27 | 	@echo "  linkcheck to check all external links for integrity"
28 | 	@echo "  doctest   to run all doctests embedded in the documentation (if enabled)"
29 | 
30 | clean:
31 | 	-rm -rf $(BUILDDIR)/*
32 | 
33 | html:
34 | 	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) ../docs
35 | 	@echo
36 | 	@echo "Build finished. The HTML pages are in ../docs"
37 | 
38 | dirhtml:
39 | 	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
40 | 	@echo
41 | 	@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
42 | 
43 | pickle:
44 | 	$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
45 | 	@echo
46 | 	@echo "Build finished; now you can process the pickle files."
47 | 
48 | json:
49 | 	$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
50 | 	@echo
51 | 	@echo "Build finished; now you can process the JSON files."
52 | 
53 | htmlhelp:
54 | 	$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
55 | 	@echo
56 | 	@echo "Build finished; now you can run HTML Help Workshop with the" \
57 | 	      ".hhp project file in $(BUILDDIR)/htmlhelp."
58 | 
59 | qthelp:
60 | 	$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
61 | 	@echo
62 | 	@echo "Build finished; now you can run "qcollectiongenerator" with the" \
63 | 	      ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
64 | 	@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/collectd.qhcp"
65 | 	@echo "To view the help file:"
66 | 	@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/collectd.qhc"
67 | 
68 | latex:
69 | 	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
70 | 	@echo
71 | 	@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
72 | 	@echo "Run \`make all-pdf' or \`make all-ps' in that directory to" \
73 | 	      "run these through (pdf)latex."
74 | 
75 | changes:
76 | 	$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
77 | 	@echo
78 | 	@echo "The overview file is in $(BUILDDIR)/changes."
79 | 
80 | linkcheck:
81 | 	$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
82 | 	@echo
83 | 	@echo "Link check complete; look for any errors in the above output " \
84 | 	      "or in $(BUILDDIR)/linkcheck/output.txt."
85 | 
86 | doctest:
87 | 	$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
88 | 	@echo "Testing of doctests in the sources finished, look at the " \
89 | 	      "results in $(BUILDDIR)/doctest/output.txt."
90 | 


--------------------------------------------------------------------------------
/sphinx/build/doctrees/environment.pickle:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/appliedsec/collectd/7b51edfd08e055149b446e9839c4dc0bc7c834ce/sphinx/build/doctrees/environment.pickle


--------------------------------------------------------------------------------
/sphinx/build/doctrees/index.doctree:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/appliedsec/collectd/7b51edfd08e055149b446e9839c4dc0bc7c834ce/sphinx/build/doctrees/index.doctree


--------------------------------------------------------------------------------
/sphinx/conf.py:
--------------------------------------------------------------------------------
  1 | # -*- coding: utf-8 -*-
  2 | #
  3 | # collectd documentation build configuration file, created by
  4 | # sphinx-quickstart on Wed Oct 20 15:16:52 2010.
  5 | #
  6 | # This file is execfile()d with the current directory set to its containing dir.
  7 | #
  8 | # Note that not all possible configuration values are present in this
  9 | # autogenerated file.
 10 | #
 11 | # All configuration values have a default; values that are commented out
 12 | # serve to show the default.
 13 | 
 14 | import sys, os
 15 | 
 16 | # If extensions (or modules to document with autodoc) are in another directory,
 17 | # add these directories to sys.path here. If the directory is relative to the
 18 | # documentation root, use os.path.abspath to make it absolute, like shown here.
 19 | #sys.path.append(os.path.abspath('.'))
 20 | 
 21 | # -- General configuration -----------------------------------------------------
 22 | 
 23 | # Add any Sphinx extension module names here, as strings. They can be extensions
 24 | # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
 25 | extensions = []
 26 | 
 27 | # Add any paths that contain templates here, relative to this directory.
 28 | templates_path = ['_templates']
 29 | 
 30 | # The suffix of source filenames.
 31 | source_suffix = '.rst'
 32 | 
 33 | # The encoding of source files.
 34 | #source_encoding = 'utf-8'
 35 | 
 36 | # The master toctree document.
 37 | master_doc = 'index'
 38 | 
 39 | # General information about the project.
 40 | project = u'collectd'
 41 | copyright = u'2012, Eli Courtwright'
 42 | 
 43 | # The version info for the project you're documenting, acts as replacement for
 44 | # |version| and |release|, also used in various other places throughout the
 45 | # built documents.
 46 | #
 47 | # The short X.Y version.
 48 | version = '1.0.2'
 49 | # The full version, including alpha/beta/rc tags.
 50 | release = '1.0.2'
 51 | 
 52 | # The language for content autogenerated by Sphinx. Refer to documentation
 53 | # for a list of supported languages.
 54 | #language = None
 55 | 
 56 | # There are two options for replacing |today|: either, you set today to some
 57 | # non-false value, then it is used:
 58 | #today = ''
 59 | # Else, today_fmt is used as the format for a strftime call.
 60 | #today_fmt = '%B %d, %Y'
 61 | 
 62 | # List of documents that shouldn't be included in the build.
 63 | #unused_docs = []
 64 | 
 65 | # List of directories, relative to source directory, that shouldn't be searched
 66 | # for source files.
 67 | exclude_trees = []
 68 | 
 69 | # The reST default role (used for this markup: `text`) to use for all documents.
 70 | #default_role = None
 71 | 
 72 | # If true, '()' will be appended to :func: etc. cross-reference text.
 73 | #add_function_parentheses = True
 74 | 
 75 | # If true, the current module name will be prepended to all description
 76 | # unit titles (such as .. function::).
 77 | #add_module_names = True
 78 | 
 79 | # If true, sectionauthor and moduleauthor directives will be shown in the
 80 | # output. They are ignored by default.
 81 | #show_authors = False
 82 | 
 83 | # The name of the Pygments (syntax highlighting) style to use.
 84 | pygments_style = 'sphinx'
 85 | 
 86 | # A list of ignored prefixes for module index sorting.
 87 | #modindex_common_prefix = []
 88 | 
 89 | 
 90 | # -- Options for HTML output ---------------------------------------------------
 91 | 
 92 | # The theme to use for HTML and HTML Help pages.  Major themes that come with
 93 | # Sphinx are currently 'default' and 'sphinxdoc'.
 94 | html_theme = 'default'
 95 | 
 96 | # Theme options are theme-specific and customize the look and feel of a theme
 97 | # further.  For a list of options available for each theme, see the
 98 | # documentation.
 99 | #html_theme_options = {}
100 | 
101 | # Add any paths that contain custom themes here, relative to this directory.
102 | #html_theme_path = []
103 | 
104 | # The name for this set of Sphinx documents.  If None, it defaults to
105 | # "<project> v<release> documentation".
106 | #html_title = None
107 | 
108 | # A shorter title for the navigation bar.  Default is the same as html_title.
109 | #html_short_title = None
110 | 
111 | # The name of an image file (relative to this directory) to place at the top
112 | # of the sidebar.
113 | #html_logo = None
114 | 
115 | # The name of an image file (within the static path) to use as favicon of the
116 | # docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
117 | # pixels large.
118 | #html_favicon = None
119 | 
120 | # Add any paths that contain custom static files (such as style sheets) here,
121 | # relative to this directory. They are copied after the builtin static files,
122 | # so a file named "default.css" will overwrite the builtin "default.css".
123 | html_static_path = ['_static']
124 | 
125 | # If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
126 | # using the given strftime format.
127 | #html_last_updated_fmt = '%b %d, %Y'
128 | 
129 | # If true, SmartyPants will be used to convert quotes and dashes to
130 | # typographically correct entities.
131 | #html_use_smartypants = True
132 | 
133 | # Custom sidebar templates, maps document names to template names.
134 | #html_sidebars = {}
135 | 
136 | # Additional templates that should be rendered to pages, maps page names to
137 | # template names.
138 | #html_additional_pages = {}
139 | 
140 | # If false, no module index is generated.
141 | #html_use_modindex = True
142 | 
143 | # If false, no index is generated.
144 | #html_use_index = True
145 | 
146 | # If true, the index is split into individual pages for each letter.
147 | #html_split_index = False
148 | 
149 | # If true, links to the reST sources are added to the pages.
150 | #html_show_sourcelink = True
151 | 
152 | # If true, an OpenSearch description file will be output, and all pages will
153 | # contain a <link> tag referring to it.  The value of this option must be the
154 | # base URL from which the finished HTML is served.
155 | #html_use_opensearch = ''
156 | 
157 | # If nonempty, this is the file name suffix for HTML files (e.g. ".xhtml").
158 | #html_file_suffix = ''
159 | 
160 | # Output file base name for HTML help builder.
161 | htmlhelp_basename = 'collectddoc'
162 | 
163 | 
164 | # -- Options for LaTeX output --------------------------------------------------
165 | 
166 | # The paper size ('letter' or 'a4').
167 | #latex_paper_size = 'letter'
168 | 
169 | # The font size ('10pt', '11pt' or '12pt').
170 | #latex_font_size = '10pt'
171 | 
172 | # Grouping the document tree into LaTeX files. List of tuples
173 | # (source start file, target name, title, author, documentclass [howto/manual]).
174 | latex_documents = [
175 |   ('index', 'collectd.tex', u'collectd Documentation',
176 |    u'Eli Courtwright', 'manual'),
177 | ]
178 | 
179 | # The name of an image file (relative to this directory) to place at the top of
180 | # the title page.
181 | #latex_logo = None
182 | 
183 | # For "manual" documents, if this is true, then toplevel headings are parts,
184 | # not chapters.
185 | #latex_use_parts = False
186 | 
187 | # Additional stuff for the LaTeX preamble.
188 | #latex_preamble = ''
189 | 
190 | # Documents to append as an appendix to all manuals.
191 | #latex_appendices = []
192 | 
193 | # If false, no module index is generated.
194 | #latex_use_modindex = True
195 | 


--------------------------------------------------------------------------------
/sphinx/index.rst:
--------------------------------------------------------------------------------
  1 | .. toctree::
  2 |     :maxdepth: 1
  3 | 
  4 | 
  5 | collectd - Send statistics over UDP to collectd servers
  6 | =======================================================
  7 | 
  8 | This module implements the
  9 | `binary protocol <http://collectd.org/wiki/index.php/Binary_protocol>`_
 10 | used by the
 11 | `Network plugin <http://collectd.org/wiki/index.php/Plugin:Network>`_
 12 | to let you send arbitrary numeric data to collectd servers.  Other than turning
 13 | on the Network plugin on the destination collectd server, no configuration is
 14 | needed.
 15 | 
 16 | Although you can configure your collectd server to do anything with your
 17 | statistics, most people use the
 18 | `RRDtool plugin <http://collectd.org/wiki/index.php/Plugin:RRDtool>`_
 19 | to efficiently store large quantities of data.  Therefore, this tutorial
 20 | will discuss the output files generated by the RRDtool plugin, even though
 21 | this module sends destination-agnostic statistics messages to your collectd
 22 | server.
 23 | 
 24 | Here's an example of sending statistics:
 25 | 
 26 | .. literalinclude:: ../examples/basic.py
 27 | 
 28 | If you run this script (which is ``examples/basic.py`` in your source package)
 29 | then your collectd server will create an RRD file for each statistic you are
 30 | tracking.  These files are typically stored under one central location on the
 31 | filesysem, such as ``/var/lib/collectd/rrd`` and organized by the hostname of
 32 | where the statistics came from and the name of the plugin that generated them.
 33 | 
 34 | This module identifies itself with the plugin name ``any``, so if you ran
 35 | the above script, it would create a ``localhost/any`` directory with the
 36 | following files:
 37 | 
 38 | * ``gauge-some_category-another_stat.rrd``
 39 | * ``gauge-some_category-some_counter.rrd``
 40 | * ``gauge-coin_stats-heads-flips.rrd``
 41 | * ``gauge-coin_stats-tails-flips.rrd``
 42 | * ``gauge-coin_stats-flips.rrd`` (contains the sum of heads and tails flips)
 43 | 
 44 | Each call to ``record()`` increments the statistics you provide.  Periodically
 45 | the sums of these statistics are sent to the collectd server and then reset.
 46 | Therefore, if you displayed a graph of one of these statistics files, each
 47 | data point on the graph would represent the sum of all ``record()`` values
 48 | over that time increment.
 49 | 
 50 | 
 51 | 
 52 | Installation
 53 | ============
 54 | This module is free for use under the BSD license.  It requires Python 2.6 or 
 55 | Python 2.7 and has no other dependencies.
 56 | 
 57 | You may `click here <https://github.com/downloads/appliedsec/collectd/collectd-1.0.1.tar.gz>`_
 58 | to  download the collectd module. You may also run ``easy_install collectd``
 59 | if you have `EasyInstall <http://peak.telecommunity.com/DevCenter/EasyInstall>`_
 60 | on your system.  The project page for collectd in the Cheese Shop (aka the Python
 61 | Package Index or PyPI) `may be found here <http://pypi.python.org/pypi/collectd/>`_.
 62 | 
 63 | You may also check out the development version of collectd with this command:
 64 | 
 65 | ``git clone https://github.com/appliedsec/collectd.git``
 66 | 
 67 | 
 68 | Functions and Classes
 69 | =====================
 70 | 
 71 | .. function:: start_threads()
 72 | 
 73 |     This function starts two daemon threads.  The first takes snapshots of your
 74 |     counters and resets them periodically.  The other serializes the statistics
 75 |     into protocol messages understood by the collectd Network plugin and sends
 76 |     them in appropriately-sized UDP packets.
 77 |     
 78 |     You must call this function when your program starts, or else this module
 79 |     will never actually send any data to any collectd servers.  Calling this
 80 |     function more than once throws an exception.
 81 | 
 82 | 
 83 | 
 84 | .. class:: Connection(hostname = socket.gethostname(), collectd_host = "localhost", collectd_port = 25826, plugin_inst = "", plugin_name = "any")
 85 | 
 86 |     Connection objects may be instantiated with 5 optional arguments:
 87 |     
 88 |     * ``hostname``: the hostname you use to identify yourself to the collectd server; if omitted, this defaults to the result of ``socket.gethostname()``
 89 |     * ``collectd_host``: the hostname or ip address of the collectd server to which we will send statistics
 90 |     * ``collectd_port``: the port to which you will send statistics messages
 91 |     * ``plugin_inst``: the plugin instance name which will be sent to the collectd server; this mostly affects the directory name used by the collectd rrdtool plugin
 92 |     * ``plugin_name``: the name of the plugin with which the collectd server will associate your statistics; this mostly affects the directory tree used by the collectd rrdtool plugin
 93 |     
 94 |     Connection objects with identical parameters are singletons; in other
 95 |     words, ``Connection("foo") is Connection("foo")`` but
 96 |     ``Connection("foo") is not Connection("bar")``.
 97 |     
 98 |     .. method:: __getattr__(name)
 99 |     
100 |         Statistics are recorded through ``Counter`` objects, which are
101 |         dynamically generated by accessing fields on ``Connection`` instances.
102 |         So saying ``conn.foo`` creates a ``Counter`` object.
103 |         
104 |         These objects are distinct but cached, so ``conn.foo is conn.foo`` but
105 |         ``conn.foo is not conn.bar``.
106 | 
107 | 
108 | 
109 | .. class:: Counter(category)
110 | 
111 |     You shouldn't directly instantiate this class; instead ``Counter`` objects
112 |     are automatically created by accessing attributes of ``Connection`` objects
113 |     such that ``conn.foo`` will cache and return ``Counter("foo")``.
114 |     
115 |     Both of the following methods swallow and log all possible exceptions, so
116 |     you never need to worry about an error being thrown by calls to either of
117 |     these methods.  These functions are also synchronized, so you can safely
118 |     call them simultaneously from different threads.
119 |     
120 |     .. method:: record(*specific, **stats)
121 |     
122 |         Each keyword argument to this method is interpreted as a statistic,
123 |         whose name is the argument name, and whose value is incrementd by
124 |         the argument value.
125 |         
126 |         You may pass one or more string identifiers as positional arguments
127 |         to this method.  If you do so, then separate statistic counts will
128 |         be maintained for this identifier.  These counts are always added
129 |         to the base count for each statistic.
130 |         
131 |         For example, if you ran the following code
132 |         
133 |         .. code-block:: python
134 |         
135 |             conn = collectd.Connection()
136 |             conn.example.record(baz = 1)
137 |             conn.example.record("foo", baz = 2)
138 |             conn.example.record("bar", baz = 3)
139 |         
140 |         and then statistics were sent to the collectd server, it would result
141 |         in the following files:
142 |         
143 |         * ``gauge-example-baz.rrd`` (with a value of 6 for this time increment)
144 |         * ``gauge-example-foo-baz.rrd`` (with a value of 2 for this time increment)
145 |         * ``gauge-example-bar-baz.rrd`` (with a value of 3 for this time increment)
146 |     
147 |     
148 |     .. method:: set_exact(**stats)
149 |     
150 |         Each keyword argument to this method is interpreted as a statistic,
151 |         whose name is the argument name, and whose value is set to the exact
152 |         value of the argument.  Use this method when you have values which you
153 |         wish to update to a specific value rather than increment.
154 | 
155 | 
156 | 
157 | .. warning::
158 | 
159 |     All names are sanitized to contain only alphanumeric characters separated
160 |     by underscores.  In other words, if you did something like
161 |     
162 |     .. code-block:: python
163 |     
164 |         conn = collectd.Connection()
165 |         counter = getattr(conn, "^@#@foo%$&&*")
166 |         stat = {"*()#@spam!@$^&*": 1}
167 |         counter.record("()#@bar&*()baz$^_+", **stat)
168 |     
169 |     then the resulting files would be named ``gauge-foo-spam.rrd`` and
170 |     ``gauge-foo-bar_baz-spam.rrd``. Although this behavior is generally
171 |     desirable, it could lead to your statistics becoming merged.  For example,
172 |     the ``foo-bar`` and ``foo/bar`` statistics in the following code would be
173 |     combined into a single ``foo_bar`` statistic:
174 |     
175 |     .. code-block:: python
176 |     
177 |         conn = collectd.Connection()
178 |         conn.foo.record("foo-bar", baz = 2)
179 |         conn.foo.record("foo/bar", baz = 3)
180 | 
181 | 
182 | 
183 | Logging
184 | =======
185 | As mentioned above, collectd swallows exceptions so that you never have to
186 | worry about calling a function from this module and triggering an exception.
187 | However, any exceptions which do occur are logged using the
188 | `logging <http://docs.python.org/library/logging.html>`_ module from the
189 | standard library, specifically to the `collectd` logger.  No other logging
190 | is performed.
191 | 
192 | However, this module defines no handlers for the `collectd` logger, so by
193 | default nothing is done with any of these log messages.
194 | 
195 | 
196 | 
197 | A More Complex Example
198 | ======================
199 | The following code is available in the ``examples/primes.py`` file in your
200 | source distribution:
201 | 
202 | .. literalinclude:: ../examples/primes.py
203 | 
204 | Here's a list of files generated by this code, along with an explanation of
205 | the counter which each file contains for each time interval:
206 | 
207 | * ``gauge-queue-size.rrd``: a snapshot of the size of the numbers queue
208 | * ``gauge-producer-too_small.rrd``: a count of the random numbers generated by the producer thread which were discarded for being too small
209 | * ``gauge-producer-too_big.rrd``: a count of the random numbers generated by the producer thread which were discarded for being too large
210 | * ``gauge-producer-just_right.rrd``: a count of the random numbers generated by the producer thread which were sent to the consumer thread for factoring
211 | * ``gauge-consumer-count.rrd``: an overall count of the numbers factored by the consumer thread
212 | * ``gauge-consumer-composite-count.rrd``: a count of the numbers factored by the consumer thread which turned out to be non-prime
213 | * ``gauge-consumer-prime-count.rrd``: a count of the numbers factored by the consumer thread which turned out to be prime
214 | * ``gauge-consumer-time.rrd``: the amount of wallclock time elapsed while factoring numbers
215 | * ``gauge-consumer-composite-time.rrd``: the amount of wallclock time elapsed while factoring numbers which turned out to be non-prime
216 | * ``gauge-consumer-prime-time.rrd``: the amount of wallclock time elapsed while factoring numbers which turned out to be prime
217 | 
218 | TODO: add graphs to this example to demonstrate what the data looks like
219 | 
220 | 
221 | 
222 | A Utility for Graphing RRD Data
223 | ===============================
224 | This is forthcoming; we'd like a simple script for generating the complex
225 | command-line arguments understood by ``rrdtool graph`` commands.
226 | 
227 | At some point we may also want a web interface similar to the existing
228 | collectd cgi script which dynamically lets you select and generate graphs,
229 | but with awareness of the semantics of the files generated by this module,
230 | which would allow users to start with a high-level overview and drill-down
231 | into specific data, combine data from different sources into one graph, etc.
232 | 


--------------------------------------------------------------------------------
/unit_tests.py:
--------------------------------------------------------------------------------
  1 | import time
  2 | import struct
  3 | import socket
  4 | import logging
  5 | from random import randrange
  6 | from unittest import TestCase, main
  7 | 
  8 | import collectd
  9 | 
 10 | class BaseCase(TestCase):
 11 |     def assertValidPacket(self, expected_type_count, s):
 12 |         type_codes = {}
 13 |         while s:
 14 |             type_code, size = struct.unpack("!HH", s[:4])
 15 |             type_codes[type_code] = 1
 16 |             self.assertTrue(size > 0)
 17 |             self.assertTrue(len(s) >= size)
 18 |             self.assertTrue(type_code in (collectd.LONG_INT_CODES
 19 |                                         + collectd.STRING_CODES
 20 |                                         + [collectd.TYPE_VALUES]))
 21 |             if type_code in collectd.LONG_INT_CODES:
 22 |                 self.assertEqual(size, 12)
 23 |                 struct.unpack("!q", s[4:12])
 24 |             elif type_code in collectd.STRING_CODES:
 25 |                 self.assertEqual(s[size-1], "\0")
 26 |                 struct.unpack(str(size-4) + "s", s[4:size])
 27 |             else:
 28 |                 self.assertEqual(type_code, collectd.TYPE_VALUES)
 29 |                 values = s[6:size]
 30 |                 count = 0
 31 |                 while values:
 32 |                     value_code = struct.unpack("B", values[0])[0]
 33 |                     self.assertTrue(value_code in collectd.VALUE_CODES)
 34 |                     struct.unpack(collectd.VALUE_CODES[value_code], values[1:9])
 35 |                     values = values[9:]
 36 |                     count += 1
 37 |                 self.assertEqual(count, struct.unpack("!H", s[4:6])[0])
 38 |             s = s[size:]
 39 |         self.assertEqual(expected_type_count, sum(type_codes.values()))
 40 |     
 41 |     def assertValidMessages(self, expected_message_count, stats):
 42 |         packets = collectd.messages(stats)
 43 |         self.assertEqual(expected_message_count, len(packets))
 44 |         for packet in packets:
 45 |             self.assertValidPacket(8, packet)
 46 | 
 47 | 
 48 | class CounterTests(BaseCase):
 49 |     def setUp(self):
 50 |         self.counter = collectd.Counter("test")
 51 |     
 52 |     def snapshot(self):
 53 |         return self.counter.snapshot()
 54 |     
 55 |     def record(self, *args, **kwargs):
 56 |         self.counter.record(*args, **kwargs)
 57 |     
 58 |     def set_exact(self, **kwargs):
 59 |         self.counter.set_exact(**kwargs)
 60 |     
 61 |     def test_snapshot_reset(self):
 62 |         self.assertEqual({}, self.snapshot())
 63 |         self.record(foo = 2)
 64 |         self.assertEqual({"test-foo": 2}, self.snapshot())
 65 |         self.assertEqual({"test-foo": 0}, self.snapshot())
 66 |     
 67 |     def test_record_adding(self):
 68 |         self.record(foo = 0.5)
 69 |         self.record(foo = 1.5)
 70 |         self.assertEqual({"test-foo": 2}, self.snapshot())
 71 |     
 72 |     def test_record_many(self):
 73 |         self.record(foo = 2, bar = 3)
 74 |         self.assertEqual({"test-foo":2, "test-bar":3}, self.snapshot())
 75 |     
 76 |     def test_record_duplicates(self):
 77 |         self.record("sub1", "sub2", foo = 2)
 78 |         self.assertEqual({"test-foo":2, "test-sub1-foo":2, "test-sub2-foo":2},
 79 |                          self.snapshot())
 80 |     
 81 |     def test_record_heirarchy(self):
 82 |         self.record("sub1", foo = 2)
 83 |         self.record("sub2", foo = 3)
 84 |         self.assertEqual({"test-foo":5, "test-sub1-foo":2, "test-sub2-foo":3},
 85 |                          self.snapshot())
 86 |     
 87 |     def test_exact(self):
 88 |         self.set_exact(foo = 3)
 89 |         self.set_exact(foo = 2)
 90 |         self.assertEqual({"test-foo": 2}, self.snapshot())
 91 |         self.assertEqual({"test-foo": 0}, self.snapshot())
 92 |         
 93 |         self.record(foo = 5)
 94 |         self.set_exact(foo = 2)
 95 |         self.assertEqual({"test-foo": 2}, self.snapshot())
 96 |         
 97 |         self.set_exact(foo = 2)
 98 |         self.record(foo = 5)
 99 |         self.assertEqual({"test-foo": 7}, self.snapshot())
100 |     
101 |     def test_no_stats(self):
102 |         self.record()
103 |         self.assertEqual({}, self.snapshot())
104 |         
105 |         self.record("sub1")
106 |         self.assertEqual({}, self.snapshot())
107 |         
108 |         self.set_exact()
109 |         self.assertEqual({}, self.snapshot())
110 |     
111 |     def test_bad_stats(self):
112 |         for arg in [None, 666, int, float]:
113 |             self.record(arg, foo = 2)
114 |             self.assertEqual({}, self.snapshot())
115 |         
116 |         for val in ["invalid", 2 ** 100, int, float]:
117 |             self.record(foo = "invalid")
118 |             self.set_exact(foo = "invalid")
119 |             self.assertEqual({}, self.snapshot())
120 |     
121 |     def test_sanitize(self):
122 |         valid = []
123 |         for start,end in [("a","z"), ("A","Z"), ("0","9")]:
124 |             for i in range(ord(start), ord(end) + 1):
125 |                 valid.append(i)
126 |         
127 |         invalid = "".join(chr(i) for i in range(256) if i not in valid)
128 |         stats = {invalid + "foo" + invalid + "bar" + invalid: 5}
129 |         for func in [self.record, self.set_exact]:
130 |             func(**stats)
131 |             self.assertEqual({"test-foo_bar": 5}, self.snapshot())
132 | 
133 | 
134 | class ConnectionTests(CounterTests):
135 |     def setUp(self):
136 |         self.conn = collectd.Connection()
137 |     
138 |     def tearDown(self):
139 |         collectd.Connection.instances.clear()
140 |     
141 |     def snapshot(self):
142 |         snap = self.conn._snapshot()
143 |         return snap[0] if snap else {}
144 |     
145 |     def record(self, *args, **kwargs):
146 |         self.conn.test.record(*args, **kwargs)
147 |     
148 |     def set_exact(self, **kwargs):
149 |         self.conn.test.set_exact(**kwargs)
150 |     
151 |     def test_sameness(self):
152 |         for params in [{"hostname":"127.0.0.1"}, {"collectd_port":1337}]:
153 |             self.assertTrue(self.conn is not collectd.Connection(**params))
154 |             self.assertTrue(collectd.Connection(plugin_inst = "xkcd", **params)
155 |                      is not collectd.Connection(**params))
156 |             self.assertTrue(collectd.Connection(**params)
157 |                          is collectd.Connection(**params))
158 | 
159 | 
160 | class PacketTests(BaseCase):
161 |     def test_numeric_valid(self):
162 |         for num in [0, 1, -1, 2**63-1, -2**63]:
163 |             for type_code in collectd.LONG_INT_CODES:
164 |                 self.assertValidPacket(1, collectd.pack(type_code, num))
165 |     
166 |     def test_numeric_invalid(self):
167 |         for x in [2**63, -2**63-1, float("nan"), float("inf"), None, "s"]:
168 |             for type_code in collectd.LONG_INT_CODES:
169 |                 self.assertRaises(Exception, collectd.pack, type_code, x)
170 |     
171 |     def test_string_valid(self):
172 |         for s in ["", "s", "Hello World!", "X" * 1024]:
173 |             for type_code in collectd.STRING_CODES:
174 |                 self.assertValidPacket(1, collectd.pack(type_code, s))
175 |     
176 |     def test_string_invalid(self):
177 |         for x in [None, 5, 1.2, ()]:
178 |             for type_code in collectd.STRING_CODES:
179 |                 self.assertRaises(Exception, collectd.pack, type_code, x)
180 |     
181 |     def test_start_valid(self):
182 |         for params in [{}, {"host":""}, {"when":time.time()}]:
183 |             self.assertValidPacket(6, collectd.message_start(**params))
184 |     
185 |     def test_empty_messages(self):
186 |         self.assertValidMessages(0, {})
187 |     
188 |     def test_small_messages(self):
189 |         for stats in [{"stat":5}, {"foo":6,"bar":7}, {"foo-bar-baz":0}]:
190 |             self.assertValidMessages(1, stats)
191 |     
192 |     def test_large_messages(self):
193 |         size = collectd.MAX_PACKET_SIZE // 2
194 |         self.assertValidMessages(2, {"X"*size: 6, "Y"*size: 7})
195 |     
196 |     def test_many_messages(self):
197 |         avail = collectd.MAX_PACKET_SIZE - len(collectd.message_start())
198 |         val_size = len(collectd.pack("xxxx", 0))
199 |         too_many = avail // val_size + 1
200 |         stats = dict(("{0:04}".format(i), i) for i in range(too_many))
201 |         self.assertValidMessages(2, stats)
202 |     
203 |     def test_oversize_messages(self):
204 |         self.assertValidMessages(0, {"X"*collectd.MAX_PACKET_SIZE: 1})
205 |         self.assertValidMessages(1, {"X"*collectd.MAX_PACKET_SIZE: 1, "Y": 2})
206 | 
207 | 
208 | class SnapshotTests(BaseCase):
209 |     def tearDown(self):
210 |         collectd.Connection.instances.clear()
211 |         while collectd.snaps.qsize():
212 |             collectd.snaps.get()
213 |     
214 |     def assertQueued(self, size):
215 |         self.assertEqual(size, collectd.snaps.qsize())
216 |         while collectd.snaps.qsize():
217 |             when, stats, conn = collectd.snaps.get()
218 |             self.assertValidMessages(1, stats)
219 |     
220 |     def test_none(self):
221 |         collectd.take_snapshots()
222 |         self.assertEqual(0, collectd.snaps.qsize())
223 |     
224 |     def test_empty(self):
225 |         conn = collectd.Connection()
226 |         collectd.take_snapshots()
227 |         self.assertQueued(0)
228 |         conn.test
229 |         self.assertQueued(0)
230 |     
231 |     def test_regular(self):
232 |         collectd.Connection().test.record(foo = 5)
233 |         collectd.take_snapshots()
234 |         self.assertQueued(1)
235 |     
236 |     def test_multiple_counters(self):
237 |         conn = collectd.Connection()
238 |         conn.foo.record(baz = 5)
239 |         conn.bar.record(baz = 5)
240 |         collectd.take_snapshots()
241 |         self.assertQueued(1)
242 |     
243 |     def test_multiple_conns(self):
244 |         conn1 = collectd.Connection(collectd_host = "localhost")
245 |         conn2 = collectd.Connection(collectd_host = "127.0.0.1")
246 |         conn1.foo.record(baz = 5)
247 |         conn2.bar.record(baz = 5)
248 |         collectd.take_snapshots()
249 |         self.assertQueued(2)
250 | 
251 | 
252 | class SocketTests(BaseCase):
253 |     TEST_PORT = 13367
254 |     
255 |     def setUp(self):
256 |         self.conn = collectd.Connection(collectd_port = self.TEST_PORT)
257 |         self.server = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
258 |         self.server.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
259 |         self.server.bind(("localhost", self.TEST_PORT))
260 |     
261 |     def tearDown(self):
262 |         collectd.Connection.instances.clear()
263 |         self.server.close()
264 |     
265 |     def send_and_recv(self, conn=None, *specific, **stats):
266 |         (conn or self.conn).test.record(*specific, **stats)
267 |         collectd.take_snapshots()
268 |         collectd.send_stats(raise_on_empty = True)
269 |         packet = self.server.recv(collectd.MAX_PACKET_SIZE)
270 |         self.assertValidPacket(8, packet)
271 |         return packet
272 |     
273 |     def test_empty(self):
274 |         collectd.send_stats()
275 |     
276 |     def test_single(self):
277 |         self.send_and_recv(foo = 5)
278 |     
279 |     def test_multiple(self):
280 |         stats = {"foo": 345352, "bar": -5023123}
281 |         packet = self.send_and_recv(**stats)
282 |         for name, value in stats.items():
283 |             self.assertTrue(name + "\0" in packet)
284 |             self.assertTrue(struct.pack("<d", value) in packet)
285 |             self.assertTrue(collectd.pack("test-"+name, value) in packet)
286 |     
287 |     def test_plugin_name(self):
288 |         conn = collectd.Connection(collectd_port = self.TEST_PORT,
289 |                                    plugin_name = "dckx")
290 |         self.assertTrue("dckx" in self.send_and_recv(conn, foo=5))
291 | 
292 |     def test_plugin_inst(self):
293 |         conn = collectd.Connection(collectd_port = self.TEST_PORT,
294 |                                    plugin_inst = "xkcd")
295 |         self.assertTrue("xkcd" in self.send_and_recv(conn, foo=5))
296 |     
297 |     def test_unicode(self):
298 |         self.send_and_recv(self.conn, u"foo.bar", hits = 1)
299 |     
300 |     def test_too_large(self):
301 |         size = collectd.MAX_PACKET_SIZE // 2
302 |         stats = [("X"*size, 123), ("Y"*size, 321)]
303 |         self.conn.test.record(**dict(stats))
304 |         collectd.take_snapshots()
305 |         collectd.send_stats(raise_on_empty = True)
306 |         for name,val in stats:
307 |             packet = self.server.recv(collectd.MAX_PACKET_SIZE)
308 |             self.assertTrue(name + "\0" in packet)
309 |             self.assertTrue(struct.pack("<d", val) in packet)
310 |             self.assertValidPacket(8, packet)
311 |     
312 |     def test_too_many(self):
313 |         stats = [("x{0:02}".format(i), randrange(256)) for i in range(50)]
314 |         self.conn.test.record(**dict(stats))
315 |         collectd.take_snapshots()
316 |         collectd.send_stats(raise_on_empty = True)
317 |         
318 |         packets = [self.server.recv(collectd.MAX_PACKET_SIZE) for i in range(2)]
319 |         for packet in packets:
320 |             self.assertValidPacket(8, packet)
321 |         
322 |         data = "".join(packets)
323 |         for name,val in stats:
324 |             self.assertTrue(name + "\0" in data)
325 |             self.assertTrue(struct.pack("<d", val) in data)
326 | 
327 | 
328 | 
329 | class NullHandler(logging.Handler):
330 |     def emit(self, record):
331 |         pass
332 | collectd.logger.addHandler(NullHandler())
333 | 
334 | if __name__ == "__main__":
335 |     main()
336 | 


--------------------------------------------------------------------------------