docs: Ansible logging update (#111)

ansible_mitogen/logging.py

@@ -69,11 +69,9 @@ def setup():
     """
     display = find_display()
 
-    mitogen.core.LOG.propagate = False
     mitogen.core.LOG.handlers = [Handler(display.v)]
     mitogen.core.LOG.setLevel(logging.DEBUG)
 
-    mitogen.core.IOLOG.propagate = False
     mitogen.core.IOLOG.handlers = [Handler(display.vvvv)]
     if display.verbosity > 3:
         mitogen.core.IOLOG.setLevel(logging.DEBUG)

ansible_mitogen/strategy.py

@@ -158,6 +158,8 @@ class StrategyModule(ansible.plugins.strategy.linear.StrategyModule):
         Construct a Router, Broker, and mitogen.unix listener
         """
         self.router = mitogen.master.Router()
+        if 'MITOGEN_ROUTER_DEBUG' in os.environ:
+            self.router.enable_debug()
         self.router.responder.whitelist_prefix('ansible')
         self.router.responder.whitelist_prefix('ansible_mitogen')
         self.listener = mitogen.unix.Listener(self.router)

docs/ansible.rst

@@ -232,8 +232,18 @@ Sudo Variables
 Debugging
 ---------
 
-See :ref:`logging-env-vars` in the Getting Started guide for environment
-variables that activate debug logging.
+Mitogen's logs are integrated into Ansible's display framework. Basic high
+level debug logs are produced with ``-vvv``, with logging of all IO activity on
+the controller machine with ``-vvvv``.
+
+It is not possible to receive IO activity logs from children spawned on remote
+machines, as the processs of receiving those woulds would in turn generate more
+logs To receive a complete trace of every process, file-based logging is
+required, which can be enabled by setting ``MITOGEN_ROUTER_DEBUG=1`` in your
+environment.
+
+When file-based logging is enabled, one file per context will be created on the
+target machines, as ``/tmp/mitogen.<pid>.log``.
 
 
 Implementation Notes