From 7c1cc064a45e5498c3578024cb2ba0c4f853c50b Mon Sep 17 00:00:00 2001
From: David Wilson <dw@botanicus.net>
Date: Sat, 17 Feb 2018 16:17:10 +0545
Subject: [PATCH] ansible: migrate logging variables into utils.

---
 ansible_mitogen/strategy/mitogen.py | 11 +----------
 docs/ansible.rst                    |  7 +++++++
 docs/getting_started.rst            | 19 +++++++++++++++++++
 mitogen/utils.py                    |  5 +++++
 4 files changed, 32 insertions(+), 10 deletions(-)

diff --git a/ansible_mitogen/strategy/mitogen.py b/ansible_mitogen/strategy/mitogen.py
index 4a881acb..08c9e1cb 100644
--- a/ansible_mitogen/strategy/mitogen.py
+++ b/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)
diff --git a/docs/ansible.rst b/docs/ansible.rst
index 640334e6..f26f203e 100644
--- a/docs/ansible.rst
+++ b/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.
diff --git a/docs/getting_started.rst b/docs/getting_started.rst
index 65f89ae9..56c486fd 100644
--- a/docs/getting_started.rst
+++ b/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
 ------------------
 
diff --git a/mitogen/utils.py b/mitogen/utils.py
index 5c6debbf..f41a7dee 100644
--- a/mitogen/utils.py
+++ b/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)