add documentation with example of an external configuration file

Change-Id: I5f0af721e6a6b4c540a0b0b40496f441fa10b18f

doc/source/configfiles/example_nova.rst

@@ -0,0 +1,84 @@
+=========================================
+ Example Configuration File for ``nova``
+=========================================
+
+This sample configuration file demonstrates how the OpenStack compute
+service (nova) might be configured.
+
+.. literalinclude:: nova_sample.conf
+   :language: ini
+   :prepend: # nova_sample.conf
+
+Two logger nodes are set up, ``root`` and ``nova``.
+
+.. literalinclude:: nova_sample.conf
+   :language: ini
+   :lines: 1-2
+
+Several handlers are created, to send messages to different outputs.
+
+.. literalinclude:: nova_sample.conf
+   :language: ini
+   :lines: 4-5
+
+And two formatters are created to be used based on whether the logging
+location will have OpenStack request context information available or
+not.
+
+.. literalinclude:: nova_sample.conf
+   :language: ini
+   :lines: 7-8
+
+The ``root`` logger is configured to send messages to the ``null``
+handler, silencing most messages that are not part of the nova
+application code namespace.
+
+.. literalinclude:: nova_sample.conf
+   :language: ini
+   :lines: 10-12
+
+The ``nova`` logger is configured to send messages marked as ``INFO``
+and higher level to the standard error stream.
+
+.. literalinclude:: nova_sample.conf
+   :language: ini
+   :lines: 14-17
+
+The ``amqp`` and ``amqplib`` loggers, used by the module that connects
+the application to the message bus, are configured to emit warning
+messages to the standard error stream.
+
+.. literalinclude:: nova_sample.conf
+   :language: ini
+   :lines: 19-27
+
+The ``sqlalchemy`` logger, used by the module that connects the
+application to the database, is configured to emit warning messages to
+the standard error stream.
+
+.. literalinclude:: nova_sample.conf
+   :language: ini
+   :lines: 29-35
+
+Similarly, ``boto``, ``suds``, and ``eventlet.wsgi.server`` are
+configured to send warnings to the standard error stream.
+
+.. literalinclude:: nova_sample.conf
+   :language: ini
+   :lines: 37-53
+
+The ``stderr`` handler, being used by most of the loggers above, is
+configured to write to the standard error stream on the console.
+
+.. literalinclude:: nova_sample.conf
+   :language: ini
+   :lines: 55-58
+
+The ``stderr`` handler uses the ``context`` formatter, which takes its
+configuration settings from ``oslo.config``.
+
+.. literalinclude:: nova_sample.conf
+   :language: ini
+   :lines: 80-81
+
+The ``stdout`` and ``syslog`` handlers are defined, but not used.

doc/source/configfiles/index.rst

@@ -0,0 +1,47 @@
+==============================
+ Advanced Configuration Files
+==============================
+
+The oslo.config options described in :doc:`/opts` make it easy to
+enable some default logging configuration behavior such as setting the
+default log level and output file. For more advanced configurations
+using translations or multiple output destinations oslo.log relies on
+the Python standard library logging module configuration file
+features.
+
+The configuration file can be used to tie together the loggers,
+handlers, and formatters and provide all of the necessary
+configuration values to enable any desired behavior.  Refer to the
+`Python logging Module Tutorial`_ for descriptions of these concepts.
+
+Logger Names
+============
+
+Loggers are configured by name. Most OpenStack applications use logger
+names based on the source file where the message is coming from. A
+file named ``myapp/package/module.py`` corresponds to a logger named
+``myapp.package.module``.
+
+Loggers are configured in a tree structure, and the names reflect
+their location in this hierarchy. It is not necessary to configure
+every logger, since messages are passed up the tree during
+processing. To control the logging for ``myapp``, for example, it is
+only necessary to set up a logger for ``myapp`` and not
+``myapp.package.module``.
+
+The base of the tree, through which all log message may pass unless
+otherwise discarded, is called the ``root`` logger.
+
+Example Files
+=============
+
+.. toctree::
+   :glob:
+
+   example*
+
+.. seealso::
+
+   * `Python logging Module Tutorial`_
+
+.. _Python logging Module Tutorial: https://docs.python.org/2.7/howto/logging.html

doc/source/configfiles/nova_sample.conf

@@ -0,0 +1,84 @@
+[loggers]
+keys = root, nova
+
+[handlers]
+keys = stderr, stdout, watchedfile, syslog, null
+
+[formatters]
+keys = context, default
+
+[logger_root]
+level = WARNING
+handlers = null
+
+[logger_nova]
+level = INFO
+handlers = stderr
+qualname = nova
+
+[logger_amqp]
+level = WARNING
+handlers = stderr
+qualname = amqp
+
+[logger_amqplib]
+level = WARNING
+handlers = stderr
+qualname = amqplib
+
+[logger_sqlalchemy]
+level = WARNING
+handlers = stderr
+qualname = sqlalchemy
+# "level = INFO" logs SQL queries.
+# "level = DEBUG" logs SQL queries and results.
+# "level = WARNING" logs neither.  (Recommended for production systems.)
+
+[logger_boto]
+level = WARNING
+handlers = stderr
+qualname = boto
+
+# NOTE(mikal): suds is used by the vmware driver, removing this will
+# cause many extraneous log lines for their tempest runs. Refer to
+# https://review.openstack.org/#/c/219225/ for details.
+[logger_suds]
+level = INFO
+handlers = stderr
+qualname = suds
+
+[logger_eventletwsgi]
+level = WARNING
+handlers = stderr
+qualname = eventlet.wsgi.server
+
+[handler_stderr]
+class = StreamHandler
+args = (sys.stderr,)
+formatter = context
+
+[handler_stdout]
+class = StreamHandler
+args = (sys.stdout,)
+formatter = context
+
+[handler_watchedfile]
+class = handlers.WatchedFileHandler
+args = ('nova.log',)
+formatter = context
+
+[handler_syslog]
+class = handlers.SysLogHandler
+args = ('/dev/log', handlers.SysLogHandler.LOG_USER)
+formatter = context
+
+[handler_null]
+class = logging.NullHandler
+formatter = default
+args = ()
+
+[formatter_context]
+class = oslo_log.formatters.ContextFormatter
+
+[formatter_default]
+format = %(message)s

doc/source/index.rst

@@ -13,6 +13,7 @@ logging (like resource id's etc).
    installation
    usage
    opts
+   configfiles/index
    contributing
    history