docs: add some docs about sending app emails, and logging to email

docs/narr/email/logging.rst

@@ -0,0 +1,107 @@
+
+Logging to Email
+================
+
+It's possible to configure logging such that when "errors" are logged,
+an email can be sent to some recipient(s).
+
+You can set this up however you like of course; see upstream docs for
+more info:
+
+* :doc:`python:library/logging`
+* :ref:`python:smtp-handler`
+
+But the example shown below does as follows:
+
+* root logger is DEBUG+ and uses 3 handlers: file, console, email
+
+* file handler
+
+  * writes to ``app/log/wutta.log`` (you should specify absolute path instead)
+
+  * will auto-rotate log file when size reaches 10MB
+
+  * uses "generic" entry formatter
+
+* console handler
+
+  * writes to STDERR for the current process
+
+  * writes only INFO+ entries (so no DEBUG)
+
+  * uses "console" entry formatter
+
+* email handler
+
+  * writes only ERROR+ entries (so no DEBUG, INFO or WARNING)
+
+  * email is From: sender and To: recip(s) with Subject: as shown
+
+  * uses "generic" entry formatter (for message body)
+
+.. note::
+
+   This will *not* send email when "uncaught exceptions" occur.  This
+   will only send email when an error is *logged*.  For example::
+
+      import logging
+
+      log = logging.getLogger(__name__)
+
+      log.debug("do not email this")
+      log.info("nor this")
+      log.warning("nor this")
+
+      log.error("but *do* email this")
+
+      try:
+          raise RuntimeError
+      except:
+          log.exception("this also gets emailed")
+
+      # nb. no email is sent *here*, although possibly further up the
+      # stack another try/except block could be setup to log uncaught
+      # errors, in which case email may still be sent.
+      raise RuntimeError("this will just raise up the stack")
+
+Now here is the example, which can be added to a normal :term:`config
+file` (modifying as needed):
+
+.. code-block:: ini
+
+   [loggers]
+   keys = root
+
+   [handlers]
+   keys = file, console, email
+
+   [formatters]
+   keys = generic, console
+
+   [logger_root]
+   handlers = file, console, email
+   level = DEBUG
+
+   [handler_file]
+   class = handlers.RotatingFileHandler
+   args = ('app/log/wutta.log', 'a', 1000000, 100, 'utf_8')
+   formatter = generic
+
+   [handler_console]
+   class = StreamHandler
+   args = (sys.stderr,)
+   formatter = console
+   level = INFO
+
+   [handler_email]
+   class = handlers.SMTPHandler
+   args = ('localhost', 'poser@localhost', ['root@localhost', 'other@localhost'], "[Poser] Logging")
+   formatter = generic
+   level = ERROR
+
+   [formatter_generic]
+   format = %(asctime)s %(levelname)-5.5s [%(name)s][%(threadName)s] %(funcName)s: %(message)s
+   datefmt = %Y-%m-%d %H:%M:%S
+
+   [formatter_console]
+   format = %(levelname)-5.5s [%(name)s][%(threadName)s] %(funcName)s: %(message)s