From 69cb4fa3705eea1647f39c56cac35d8fcff140b8 Mon Sep 17 00:00:00 2001
From: Will Kahn-Greene <willkg@mozilla.com>
Date: Mon, 24 Apr 2017 18:57:09 -0400
Subject: [PATCH] Add logging docs

Fixes #12
---
 docs/django.rst  | 30 +++++++++++++++++++++++++-
 docs/index.rst   |  7 +++++-
 docs/logging.rst | 55 ++++++++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 90 insertions(+), 2 deletions(-)
 create mode 100644 docs/logging.rst

diff --git a/docs/django.rst b/docs/django.rst
index 8cbe4c9..d02b1d7 100644
--- a/docs/django.rst
+++ b/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:
 
diff --git a/docs/index.rst b/docs/index.rst
index 3e233a2..23d6cba 100644
--- a/docs/index.rst
+++ b/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
 
diff --git a/docs/logging.rst b/docs/logging.rst
new file mode 100644
index 0000000..461adbb
--- /dev/null
+++ b/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