ansible: migrate logging variables into utils.

ansible_mitogen/strategy/mitogen.py

@@ -131,15 +131,6 @@ class StrategyModule(ansible.plugins.strategy.linear.StrategyModule):
         conn_dir = os.path.join(basedir, 'connection')
         ansible.plugins.connection_loader.add_directory(conn_dir)
 
-    def _setup_logging(self):
-        """
-        Setup Mitogen's logging. Eventually this should be redirected into
-        Ansible's logging.
-        """
-        log_level = os.environ.get('MITOGEN_LOG_LEVEL', 'INFO')
-        log_io = 'MITOGEN_LOG_IO' in os.environ
-        mitogen.utils.log_to_file(level=log_level, io=log_io)
-
     def _setup_master(self):
         """
         Construct a Router, Broker, mitogen.unix listener thread, and thread
@@ -162,7 +153,7 @@ class StrategyModule(ansible.plugins.strategy.linear.StrategyModule):
         Arrange for a mitogen.master.Router to be available for the duration of
         the strategy's real run() method.
         """
-        self._setup_logging()
+        mitogen.utils.log_to_file()
         self._setup_master()
         try:
             return super(StrategyModule, self).run(iterator, play_context)

docs/ansible.rst

@@ -148,3 +148,10 @@ Sudo Variables
 
 * username (default: root)
 * password (default: assume passwordless)
+
+
+Debugging
+---------
+
+See :ref:`logging-env-vars` in the Getting Started guide for environment
+variables that activate debug logging.

docs/getting_started.rst

@@ -106,6 +106,25 @@ logging level, you may wish to update its configuration to restrict the
 output will be generated by default.
 
 
+.. _logging-env-vars:
+
+Logging Environment Variables
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+``MITOGEN_LOG_LEVEL``
+    Overrides the :py:mod:`logging` package log level set by any call to
+    :py:func:`mitogen.utils.log_to_file`. Defaults to ``INFO``.
+
+``MITOGEN_LOG_USEC``
+    If present, forces microsecond-level timestamps for any call to
+    :py:func:`mitogen.utils.log_to_file`.
+
+``MITOGEN_LOG_IO``
+    If present, forces IO logging for any call to
+    :py:func:`mitogen.utils.log_to_file`. IO logging produces extremely verbose
+    logs of any IO interaction, which is useful when debugging deadlocks.
+
+
 Creating A Context
 ------------------
 

mitogen/utils.py

@@ -27,6 +27,7 @@
 
 import datetime
 import logging
+import os
 import sys
 
 import mitogen
@@ -49,6 +50,10 @@ def _formatTime(record, datefmt=None):
 
 
 def log_to_file(path=None, io=True, usec=False, level='INFO'):
+    io = ('MITOGEN_LOG_IO' in os.environ) or io
+    usec = ('MITOGEN_LOG_USEC' in os.environ) or usec
+    level = os.environ.get('MITOGEN_LOG_LEVEL', level).upper()
+
     log = logging.getLogger('')
     if path:
         fp = open(path, 'w', 1)