Add logging docs

docs/django.rst

@@ -279,7 +279,35 @@ TODO
 Logging
 -------
 
-TODO
+Dockerflow provides a :py:class:`dockerflow.logging.JsonLogFormatter` Python
+logging formatter class.
+
+To use it, put something like this in your Django ``settings`` file::
+
+    LOGGING = {
+        'version': 1,
+        'formatters': {
+            'mozlog': {
+                '()': 'dockerflow.logging.JsonLogFormatter',
+                'logger_name': 'MyServiceName'
+            }
+        },
+        'handlers': {
+            'console': {
+                'level': 'DEBUG',
+                'class': 'logging.StreamHandler',
+                'formatter': 'mozlog'
+            },
+        },
+        'loggers': {
+            'myservice': {
+                'handlers': ['console'],
+                'level': 'DEBUG',
+            },
+        }
+    }
+
+
 
 .. _django-static:
 

docs/index.rst

@@ -48,7 +48,11 @@ Features
 
    logging
 
-      Send text logs to ``stdout`` or ``stderr``. See: :ref:`Django <django-logging>`
+      Send text logs to ``stdout`` or ``stderr``.
+
+      See: :ref:`Logging <logging>` for logging
+
+      See: :ref:`Django <django-logging>` for logging with Django
 
    static content
 
@@ -62,6 +66,7 @@ Contents
 
    authors
    changelog
+   logging
    django
    api
 

docs/logging.rst

@@ -0,0 +1,55 @@
+.. _logging:
+
+Logging
+=======
+
+python-dockerflow provides a :py:class:`dockerflow.logging.JsonLogFormatter` Python
+logging formatter that produces messages following the JSON schema for a common
+application logging format defined by the illustrious Mozilla Cloud Services
+group.
+
+
+Configuration
+-------------
+
+Example configuration::
+
+    import logging.config
+
+    cfg = {
+        'version': 1,
+        'formatters': {
+            'mozlog': {
+                '()': 'dockerflow.logging.JsonLogFormatter',
+                'logger_name': 'MyServiceName'
+            }
+        },
+        'handlers': {
+            'console': {
+                'level': 'DEBUG',
+                'class': 'logging.StreamHandler',
+                'formatter': 'mozlog'
+            },
+        },
+        'loggers': {
+            'myservice': {
+                'handlers': ['console'],
+                'level': 'DEBUG',
+            },
+        }
+    }
+
+    logging.config.dictConfig(cfg)
+
+    logging.info('I am logging in mozlog format now! woo hoo!')
+
+
+In this example, we set up a logger for ``myservice`` (you'd replace that with
+your service name) which has a single handler named ``console`` which uses the
+``mozlog`` formatter to output log event data to stdout.
+
+
+API
+---
+
+.. autoclass:: dockerflow.logging.JsonLogFormatter