Initial doc for guppy

1 files changed, 46 insertions, 0 deletions

diff --git a/doc/server/plugins/misc/guppy.txt b/doc/server/plugins/misc/guppy.txt
new file mode 100644
index 000000000..0b8ef8203
--- /dev/null
+++ b/doc/server/plugins/misc/guppy.txt
@@ -0,0 +1,46 @@
+.. -*- mode: rst -*-
+
+.. _server-plugins-misc-guppy:
+
+=====
+Guppy
+=====
+
+This plugin is used to trace memory leaks within the bcfg2-server
+process using Guppy_. By default the remote debugger is started
+when this plugin is enabled. The debugger can be shutoff in a running
+process using ``bcfg2-admin xcmd Guppy.Disable`` and reenabled using
+``bcfg2-admin xcmd Guppy.Enable``.
+
+.. _Guppy: http://pypi.python.org/pypi/guppy/0.1.8
+
+Setup
+=====
+
+- Install the Guppy_ package first.
+
+- Add *Guppy* to the **plugins** line in ``bcfg2.conf``.
+
+Use cases
+=========
+
+To attach the console run::
+
+    python -c "from guppy import hpy;hpy().monitor()"
+
+Example
+=======
+
+.. code-block:: sh
+
+    # python -c "from guppy import hpy;hpy().monitor()"
+    <Monitor> 
+    *** Connection 1 opened ***
+    <Monitor> lc
+    CID PID   ARGV
+      1 25063 ['/usr/sbin/bcfg2-server', '-D', '/var/run/bcfg2-server.pid']
+    <Monitor> sc 1
+    Remote connection 1. To return to Monitor, type <Ctrl-C> or .<RETURN>
+    <Annex> int
+    Remote interactive console. To return to Annex, type '-'.
+    >>> hp.heap()