doc: How to remote-pdb under systemd
Add instructions for installing and enabling remote-pdb [1] under
systemd.
[1] https://pypi.python.org/pypi/remote-pdb
Thanks to clarkb for pointing me to this. TIL.
Change-Id: I640ac36cfbcc5b199e911c0e3f6b18705c3fbbc4
diff --git a/doc/source/systemd.rst b/doc/source/systemd.rst
index f9971ab..c1d2944 100644
--- a/doc/source/systemd.rst
+++ b/doc/source/systemd.rst
@@ -120,8 +120,11 @@
See ``man 1 journalctl`` for more.
-Debugging with pdb
-==================
+Debugging
+=========
+
+Using pdb
+---------
In order to break into a regular pdb session on a systemd-controlled
service, you need to invoke the process manually - that is, take it out
@@ -143,6 +146,37 @@
/usr/local/bin/nova-scheduler --config-file /etc/nova/nova.conf
+Using remote-pdb
+----------------
+
+`remote-pdb`_ works while the process is under systemd control.
+
+Make sure you have remote-pdb installed::
+
+ sudo pip install remote-pdb
+
+Inject your breakpoint in the source, e.g.::
+
+ import remote_pdb; remote_pdb.set_trace()
+
+Restart the relevant service::
+
+ sudo systemctl restart devstack@n-api.service
+
+The remote-pdb code configures the telnet port when ``set_trace()`` is
+invoked. Do whatever it takes to hit the instrumented code path, and
+inspect the logs for a message displaying the listening port::
+
+ Sep 07 16:36:12 p8-100-neo devstack@n-api.service[772]: RemotePdb session open at 127.0.0.1:46771, waiting for connection ...
+
+Telnet to that port to enter the pdb session::
+
+ telnet 127.0.0.1 46771
+
+See the `remote-pdb`_ home page for more options.
+
+.. _`remote-pdb`: https://pypi.python.org/pypi/remote-pdb
+
Known Issues
============