Improve documentataion of Oslo Log Usage2.3.0

Added examples to explain how to implement Oslo Logging
and to show how it interacts with Oslo Config and i18n.

Revised configuration option help (and order) to provide a better
documented Configuration Options page

Change-Id: Idf4a8788f887ba07fe1b3604e06b165366b2c808

10 files changed, 596 insertions, 176 deletions

diff --git a/doc/source/examples/_i18n.py b/doc/source/examples/_i18n.py
new file mode 100644
index 0000000..3bc9256
--- /dev/null
+++ b/doc/source/examples/_i18n.py
@@ -0,0 +1,49 @@
+# Copyright (c) 2016 OpenStack Foundation
+# All Rights Reserved.
+#
+#  Licensed under the Apache License, Version 2.0 (the "License"); you may
+#  not use this file except in compliance with the License. You may obtain
+#  a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+#  Unless required by applicable law or agreed to in writing, software
+#  distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+#  WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+#  License for the specific language governing permissions and limitations
+#  under the License.
+
+"""A demonstration of oslo.i18n integration module that is used
+   in projects wanting to implement Oslo i18n translation.
+
+   See  http://docs.openstack.org/developer/oslo.i18n/usage.html
+"""
+
+import oslo_i18n
+
+DOMAIN = "demo"
+
+_translators = oslo_i18n.TranslatorFactory(domain=DOMAIN)
+
+# The primary translation function using the well-known name "_"
+_ = _translators.primary
+
+# The contextual translation function using the name "_C"
+_C = _translators.contextual_form
+
+# The plural translation function using the name "_P"
+_P = _translators.plural_form
+
+# Translators for log levels.
+#
+# The abbreviated names are meant to reflect the usual use of a short
+# name like '_'. The "L" is for "log" and the other letter comes from
+# the level.
+_LI = _translators.log_info
+_LW = _translators.log_warning
+_LE = _translators.log_error
+_LC = _translators.log_critical
+
+
+def get_available_languages():
+    return oslo_i18n.get_available_languages(DOMAIN)
diff --git a/doc/source/examples/oslo_logging.py b/doc/source/examples/oslo_logging.py
new file mode 100644
index 0000000..886278a
--- /dev/null
+++ b/doc/source/examples/oslo_logging.py
@@ -0,0 +1,30 @@
+# Copyright (c) 2016 OpenStack Foundation
+#
+# Licensed under the Apache License, Version 2.0 (the "License"); you may
+# not use this file except in compliance with the License. You may obtain
+# a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+# License for the specific language governing permissions and limitations
+# under the License.
+
+"""A minimal syntax example of Oslo Logging"""
+
+from oslo_log import log as logging
+from oslo_config import cfg
+
+LOG = logging.getLogger(__name__)
+CONF = cfg.CONF
+DOMAIN = "demo"
+
+logging.register_options(CONF)
+logging.setup(CONF, DOMAIN)
+
+# Oslo Logging uses INFO as default
+LOG.info("Oslo Logging")
+LOG.warning("Oslo Logging")
+LOG.error("Oslo Logging")
diff --git a/doc/source/examples/python_logging.py b/doc/source/examples/python_logging.py
new file mode 100644
index 0000000..44605da
--- /dev/null
+++ b/doc/source/examples/python_logging.py
@@ -0,0 +1,26 @@
+# Copyright (c) 2016 OpenStack Foundation
+#
+# Licensed under the Apache License, Version 2.0 (the "License"); you may
+# not use this file except in compliance with the License. You may obtain
+# a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+# License for the specific language governing permissions and limitations
+# under the License.
+
+"""A syntax example of Python Logging"""
+
+import logging
+
+LOG = logging.getLogger(__name__)
+
+# Define a default handler at INFO logging level
+logging.basicConfig(level=logging.INFO)
+
+LOG.info("Python Standard Logging")
+LOG.warning("Python Standard Logging")
+LOG.error("Python Standard Logging")
diff --git a/doc/source/examples/usage.py b/doc/source/examples/usage.py
new file mode 100644
index 0000000..8466050
--- /dev/null
+++ b/doc/source/examples/usage.py
@@ -0,0 +1,80 @@
+# Copyright (c) 2016 OpenStack Foundation
+#
+# Licensed under the Apache License, Version 2.0 (the "License"); you may
+# not use this file except in compliance with the License. You may obtain
+# a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+# License for the specific language governing permissions and limitations
+# under the License.
+
+"""A usage example of Oslo Logging
+
+This example requires the following package to be installed.
+
+$ pip install oslo.log
+
+Additional Oslo packages installed include oslo.config, oslo.context,
+oslo.i18n, osli.serialization and oslo.utils.
+
+More information about Oslo Logging can be found at:
+
+  http://docs.openstack.org/developer/oslo.log/usage.html
+"""
+
+from oslo_config import cfg
+from oslo_log import log as logging
+
+LOG = logging.getLogger(__name__)
+CONF = cfg.CONF
+DOMAIN = "demo"
+
+
+def prepare():
+    """Prepare Oslo Logging (2 or 3 steps)
+
+    Use of Oslo Logging involves the following:
+
+    * logging.register_options
+    * logging.set_defaults (optional)
+    * logging.setup
+    """
+
+    # Required step to register common, logging and generic configuration
+    # variables
+    logging.register_options(CONF)
+
+    # Optional step to set new defaults if necessary for
+    # * logging_context_format_string
+    # * default_log_levels
+    #
+    # These variables default to respectively:
+    #
+    #  import oslo_log
+    #  oslo_log._options.DEFAULT_LOG_LEVELS
+    #  oslo_log._options.log_opts[0].default
+    #
+
+    custom_log_level_defaults = logging.get_default_log_levels() + [
+        'dogpile=INFO',
+        'routes=INFO'
+        ]
+
+    logging.set_defaults(default_log_levels=custom_log_level_defaults)
+
+    # Required setup based on configuration and domain
+    logging.setup(CONF, DOMAIN)
+
+
+if __name__ == '__main__':
+    prepare()
+    # NOTE: These examples do not demonstration Oslo i18n messages
+    LOG.info("Welcome to Oslo Logging")
+    LOG.debug("A debugging message")
+    LOG.warning("A warning occured")
+    LOG.error("An error occured")
+    LOG.exception("An Exception occured")
diff --git a/doc/source/examples/usage_helper.py b/doc/source/examples/usage_helper.py
new file mode 100644
index 0000000..0b5baa4
--- /dev/null
+++ b/doc/source/examples/usage_helper.py
@@ -0,0 +1,100 @@
+# Copyright (c) 2016 OpenStack Foundation
+#
+# Licensed under the Apache License, Version 2.0 (the "License"); you may
+# not use this file except in compliance with the License. You may obtain
+# a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+# License for the specific language governing permissions and limitations
+# under the License.
+
+"""A usage example with helper debugging of minimum Oslo Logging
+
+This example requires the following package to be installed.
+
+$ pip install oslo.log
+
+Additional Oslo packages installed include oslo.config, oslo.context,
+oslo.i18n, osli.serialization and oslo.utils.
+
+More information about Oslo Logging can be found at:
+
+  http://docs.openstack.org/developer/oslo.log/usage.html
+"""
+
+from oslo_config import cfg
+from oslo_log import log as logging
+# Use default Python logging to display running output
+import logging as py_logging
+
+
+LOG = py_logging.getLogger(__name__)
+CONF = cfg.CONF
+DOMAIN = "demo"
+
+
+def prepare():
+    """Prepare Oslo Logging (2 or 3 steps)
+
+    Use of Oslo Logging involves the following:
+
+    * logging.register_options
+    * logging.set_defaults (optional)
+    * logging.setup
+    """
+
+    LOG.debug("Prepare Oslo Logging")
+
+    LOG.info("Size of configuration options before %d", len(CONF))
+
+    # Required step to register common, logging and generic configuration
+    # variables
+    logging.register_options(CONF)
+
+    LOG.info("Size of configuration options after %d", len(CONF))
+
+    # Optional step to set new defaults if necessary for
+    # * logging_context_format_string
+    # * default_log_levels
+    #
+    # These variables default to respectively:
+    #
+    #  import oslo_log
+    #  oslo_log._options.DEFAULT_LOG_LEVELS
+    #  oslo_log._options.log_opts[0].default
+    #
+
+    custom_log_level_defaults = logging.get_default_log_levels() + [
+        'dogpile=INFO',
+        'routes=INFO'
+        ]
+
+    logging.set_defaults(default_log_levels=custom_log_level_defaults)
+
+    # NOTE: We cannot show the contents of the CONF object
+    # after register_options() because accessing this caches
+    # the default_log_levels subsequently modified with set_defaults()
+    LOG.info("List of Oslo Logging configuration options and current values")
+    LOG.info("=" * 80)
+    for c in CONF:
+        LOG.info("%s = %s" % (c, CONF[c]))
+    LOG.info("=" * 80)
+
+    # Required setup based on configuration and domain
+    logging.setup(CONF, DOMAIN)
+
+
+if __name__ == '__main__':
+    py_logging.basicConfig(level=py_logging.DEBUG)
+
+    prepare()
+    # NOTE: These examples do not demonstration Oslo i18n messages
+    LOG.info("Welcome to Oslo Logging")
+    LOG.debug("A debugging message")
+    LOG.warning("A warning occured")
+    LOG.error("An error occured")
+    LOG.exception("An Exception occured")
diff --git a/doc/source/examples/usage_i18n.py b/doc/source/examples/usage_i18n.py
new file mode 100644
index 0000000..ef53f84
--- /dev/null
+++ b/doc/source/examples/usage_i18n.py
@@ -0,0 +1,83 @@
+# Copyright (c) 2016 OpenStack Foundation
+#
+# Licensed under the Apache License, Version 2.0 (the "License"); you may
+# not use this file except in compliance with the License. You may obtain
+# a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+# License for the specific language governing permissions and limitations
+# under the License.
+
+"""A usage example of Oslo Logging with Oslo i18n
+
+This example requires the following package to be installed.
+
+$ pip install oslo.log
+
+Additional Oslo packages installed include oslo.config, oslo.context,
+oslo.i18n, osli.serialization and oslo.utils.
+
+More information about Oslo Logging can be found at:
+
+  http://docs.openstack.org/developer/oslo.log/usage.html
+  http://docs.openstack.org/developer/oslo.i18n/usage.html
+"""
+
+from oslo_config import cfg
+from oslo_log import log as logging
+from _i18n import _, _LI, _LW, _LE
+
+LOG = logging.getLogger(__name__)
+CONF = cfg.CONF
+DOMAIN = "demo"
+
+
+def prepare():
+    """Prepare Oslo Logging (2 or 3 steps)
+
+    Use of Oslo Logging involves the following:
+
+    * logging.register_options
+    * logging.set_defaults (optional)
+    * logging.setup
+    """
+
+    # Required step to register common, logging and generic configuration
+    # variables
+    logging.register_options(CONF)
+
+    # Optional step to set new defaults if necessary for
+    # * logging_context_format_string
+    # * default_log_levels
+    #
+    # These variables default to respectively:
+    #
+    #  import oslo_log
+    #  oslo_log._options.DEFAULT_LOG_LEVELS
+    #  oslo_log._options.log_opts[0].default
+    #
+
+    extra_log_level_defaults = [
+        'dogpile=INFO',
+        'routes=INFO'
+    ]
+
+    logging.set_defaults(default_log_levels=CONF.default_log_levels +
+                         extra_log_level_defaults)
+
+    # Required setup based on configuration and domain
+    logging.setup(CONF, DOMAIN)
+
+
+if __name__ == '__main__':
+    prepare()
+    # NOTE: These examples use Oslo i18n messages
+    LOG.info(_LI("Welcome to Oslo Logging"))
+    LOG.debug("A debugging message")  # Debug messages are not translated
+    LOG.warning(_LW("A warning occured"))
+    LOG.error(_LE("An error occured"))
+    LOG.exception(_("An Exception occured"))
diff --git a/doc/source/index.rst b/doc/source/index.rst
index 706db8f..f19855b 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -12,6 +12,7 @@ logging (like resource id's etc).
 
    installation
    usage
+   migration
    opts
    configfiles/index
    contributing
diff --git a/doc/source/migration.rst b/doc/source/migration.rst
new file mode 100644
index 0000000..25d13c4
--- /dev/null
+++ b/doc/source/migration.rst
@@ -0,0 +1,119 @@
+Migrating from Oslo Incubator to oslo.log
+=========================================
+
+Applications using the incubated version of the logging code from Oslo
+may need to make some extra changes.
+
+What do I import?
+-----------------
+
+Our goal is to allow most libraries to import the Python standard
+library module, ``logging``, and not require ``oslo.log``
+directly. Applications may do the same, but if an application takes
+advantage of features like passing keywords through to the context for
+logging, it is likely to be less confusing to use ``oslo.log``
+everywhere, rather than have different types of loggers in different
+modules of the application.
+
+No more ``audit()``
+-------------------
+
+The ``audit()`` method of the old ``ContextAdapter`` class no longer
+exists. We agreed in the `cross project spec`_ to stop using audit
+level anyway, so those calls should be replaced with calls to
+``info()``.
+
+.. _cross project spec: http://git.openstack.org/cgit/openstack/openstack-specs/tree/specs/log-guidelines.rst
+
+Deprecation tools moved to ``versionutils``
+-------------------------------------------
+
+The :meth:`deprecated` decorator and :class:`DeprecatedConfig` have
+moved to :mod:`oslo_log.versionutils`.  Replace ``LOG.deprecated()``
+with :mod:`oslo_log.versionutils.report_deprecated_feature`, passing a
+local logger object as the first argument so the log message includes
+the location information.
+
+No more implicit conversion to unicode/str
+------------------------------------------
+
+The old :class:`ContextAdapter` used to convert anything given to it
+to a :class:`unicode` object before passing it to lower layers of the
+logging code. The new logging configuration uses a formatter instead
+of an adapter, so this conversion is no longer possible. All message
+format strings therefore need to be passed as unicode objects --
+that's strictly :class:`unicode`, not :class:`str`. If a message has
+no interpolation for extra parameters, a byte string can be used.
+
+The most common place to encounter this is where :meth:`Logger.error`
+is used by passing an exception object as the first argument.
+
+::
+
+    # Old style
+    try:
+        do_something()
+    except Exception as err:
+        LOG.error(err)
+
+Now, the error should be converted to unicode either by calling
+:func:`six.text_type` or by using a unicode formatting string to
+provide context. It's even better to replace the redundant message
+produced by passing the exception with a useful message.
+
+::
+
+    # New style, preferred approach
+    from myapp._i18n import _LE  # see oslo.i18n
+    try:
+        do_something()
+    except Exception as err:
+        LOG.exception(_LE(u"do_something couldn't do something"))
+
+    # New style, with exception
+    from myapp._i18n import _LE  # see oslo.i18n
+    try:
+        do_something()
+    except Exception as err:
+        LOG.error(_LE(u"do_something couldn't do something: %s"), err)
+
+    # New style, alternate without context
+    import six
+    try:
+        do_something()
+    except Exception as err:
+        LOG.error(six.text_type(err))
+
+Failure to do this for exceptions or other objects containing
+translatable strings from ``oslo.i18n`` results in an exception when
+the :class:`_Message` instance is combined in unsupported ways with
+the default formatting string inside the :mod:`logging` module in the
+standard library.
+
+Changes to App Initialization
+-----------------------------
+
+The logging options are no longer registered on the global
+configuration object defined in ``oslo.config``, and need to be
+registered explicitly on the configuration object being used by the
+application. Do this by calling :func:`~oslo_log.log.register_options`
+before parsing command line options.
+
+The same configuration option passed to
+:func:`~oslo_log.log.register_options` should also be passed as the
+first argument to :func:`~oslo_log.log.setup`.
+
+See :ref:`usage-app` for more details about application setup.
+
+Passing Context
+---------------
+
+Applications are expected to be using
+:class:`oslo_context.context.RequestContext` as the base class for
+their application-specific context classes. The base class manages a
+thread-local storage for the "current" context object so that
+``oslo.log`` can retrieve it without having the value passed in
+explicitly. This ensures that all log messages include the same
+context information, such as the request id and user
+identification. See the ``oslo.context`` documentation for details of
+using the class.
diff --git a/doc/source/usage.rst b/doc/source/usage.rst
index 29fd478..442a323 100644
--- a/doc/source/usage.rst
+++ b/doc/source/usage.rst
@@ -2,34 +2,69 @@
  Usage
 =======
 
-In a Library
-============
-
-oslo.log is primarily used for configuring logging in an application,
-but it does include helpers that can be useful from libraries.
-
-:func:`~oslo_log.log.getLogger` wraps the function of the same name
-from Python's standard library to add a
-:class:`~oslo_log.log.KeywordArgumentAdapter`, making it easier to
-pass data to the formatters provided by oslo.log and configured by an
-application.
-
 .. _usage-app:
 
 In an Application
 =================
 
-Applications should use oslo.log's configuration functions to register
+When using `Python's standard logging library`_ the following minimal setup
+demostrates basic logging.
+
+.. _Python's standard logging library: https://docs.python.org/2/library/logging.html
+
+.. literalinclude:: examples/python_logging.py
+   :linenos:
+   :lines: 17-26
+
+Source: :download:`examples/python_logging.py`
+
+When using ``Oslo Logging`` the following setup demonstrates a comparative
+syntax with Python standard logging.
+
+
+.. literalinclude:: examples/oslo_logging.py
+   :linenos:
+   :lines: 17-30
+   :emphasize-lines: 8,9
+
+Source: :download:`examples/oslo_logging.py`
+
+Olso Logging Methods
+--------------------
+
+Applications need to use the oslo.log configuration functions to register
 logging-related configuration options and configure the root and other
-default loggers.
+default loggers before using standard logging functions.
 
-Call :func:`~oslo_log.log.register_options` before parsing command
-line options.
+Call :func:`~oslo_log.log.register_options` with an oslo.config CONF object
+before parsing the application command line options.
 
-Call :func:`~oslo_log.log.set_defaults` before configuring logging.
+Optionally call :func:`~oslo_log.log.set_defaults` before setup to
+change default logging levels if necessary.
+
+Call :func:`~oslo_log.log.setup` with the oslo.config CONF object used
+when registering objects, along with the domain and optionally a version
+to configure logging for the application.
+
+Use standard logging functions to produce log records at applicable log
+levels.  Logging should also use Oslo i18n contextual functions to provide
+translation.  With the use of Oslo Context, log records can also contain
+additional contextual information.
+
+Examples
+--------
+
+
+:download:`examples/usage.py` provides a documented example of
+Oslo Logging setup.
+
+:download:`examples/usage_helper.py` provides an example showing
+debugging logging at each step details the configuration and logging
+at each step of Oslo Logging setup.
+
+:download:`examples/usage_i18n.py` provides a documented example of
+Oslo Logging with Oslo i18n supported messages.
 
-Call :func:`~oslo_log.log.setup` to configure logging for the
-application.
 
 General Logging Guidelines
 ==========================
@@ -40,122 +75,14 @@ patterns to be used in OpenStack applications.
 
 .. _OpenStack Logging Guidelines: http://specs.openstack.org/openstack/openstack-specs/specs/log-guidelines.html
 
-Migrating to oslo.log
-=====================
-
-Applications using the incubated version of the logging code from Oslo
-may need to make some extra changes.
-
-What do I import?
------------------
-
-Our goal is to allow most libraries to import the Python standard
-library module, ``logging``, and not require ``oslo.log``
-directly. Applications may do the same, but if an application takes
-advantage of features like passing keywords through to the context for
-logging, it is likely to be less confusing to use ``oslo.log``
-everywhere, rather than have different types of loggers in different
-modules of the application.
-
-No more ``audit()``
--------------------
-
-The ``audit()`` method of the old ``ContextAdapter`` class no longer
-exists. We agreed in the `cross project spec`_ to stop using audit
-level anyway, so those calls should be replaced with calls to
-``info()``.
-
-.. _cross project spec: http://git.openstack.org/cgit/openstack/openstack-specs/tree/specs/log-guidelines.rst
-
-Deprecation tools moved to ``versionutils``
--------------------------------------------
-
-The :meth:`deprecated` decorator and :class:`DeprecatedConfig` have
-moved to :mod:`oslo_log.versionutils`.  Replace ``LOG.deprecated()``
-with :mod:`oslo_log.versionutils.report_deprecated_feature`, passing a
-local logger object as the first argument so the log message includes
-the location information.
-
-No more implicit conversion to unicode/str
-------------------------------------------
-
-The old :class:`ContextAdapter` used to convert anything given to it
-to a :class:`unicode` object before passing it to lower layers of the
-logging code. The new logging configuration uses a formatter instead
-of an adapter, so this conversion is no longer possible. All message
-format strings therefore need to be passed as unicode objects --
-that's strictly :class:`unicode`, not :class:`str`. If a message has
-no interpolation for extra parameters, a byte string can be used.
-
-The most common place to encounter this is where :meth:`Logger.error`
-is used by passing an exception object as the first argument.
-
-::
-
-    # Old style
-    try:
-        do_something()
-    except Exception as err:
-        LOG.error(err)
-
-Now, the error should be converted to unicode either by calling
-:func:`six.text_type` or by using a unicode formatting string to
-provide context. It's even better to replace the redundant message
-produced by passing the exception with a useful message.
-
-::
-
-    # New style, preferred approach
-    from myapp._i18n import _LE  # see oslo.i18n
-    try:
-        do_something()
-    except Exception as err:
-        LOG.exception(_LE(u"do_something couldn't do something"))
-
-    # New style, with exception
-    from myapp._i18n import _LE  # see oslo.i18n
-    try:
-        do_something()
-    except Exception as err:
-        LOG.error(_LE(u"do_something couldn't do something: %s"), err)
-
-    # New style, alternate without context
-    import six
-    try:
-        do_something()
-    except Exception as err:
-        LOG.error(six.text_type(err))
-
-Failure to do this for exceptions or other objects containing
-translatable strings from ``oslo.i18n`` results in an exception when
-the :class:`_Message` instance is combined in unsupported ways with
-the default formatting string inside the :mod:`logging` module in the
-standard library.
-
-Changes to App Initialization
------------------------------
-
-The logging options are no longer registered on the global
-configuration object defined in ``oslo.config``, and need to be
-registered explicitly on the configuration object being used by the
-application. Do this by calling :func:`~oslo_log.log.register_options`
-before parsing command line options.
-
-The same configuration option passed to
-:func:`~oslo_log.log.register_options` should also be passed as the
-first argument to :func:`~oslo_log.log.setup`.
-
-See :ref:`usage-app` for more details about application setup.
-
-Passing Context
----------------
-
-Applications are expected to be using
-:class:`oslo_context.context.RequestContext` as the base class for
-their application-specific context classes. The base class manages a
-thread-local storage for the "current" context object so that
-``oslo.log`` can retrieve it without having the value passed in
-explicitly. This ensures that all log messages include the same
-context information, such as the request id and user
-identification. See the ``oslo.context`` documentation for details of
-using the class.
+In a Library
+============
+
+oslo.log is primarily used for configuring logging in an application,
+but it does include helpers that can be useful from libraries.
+
+:func:`~oslo_log.log.getLogger` wraps the function of the same name
+from Python's standard library to add a
+:class:`~oslo_log.log.KeywordArgumentAdapter`, making it easier to
+pass data to the formatters provided by oslo.log and configured by an
+application.
diff --git a/oslo_log/_options.py b/oslo_log/_options.py
index 660e305..1d0e2a1 100644
--- a/oslo_log/_options.py
+++ b/oslo_log/_options.py
@@ -29,18 +29,19 @@ DEFAULT_LOG_LEVELS = ['amqp=WARN', 'amqplib=WARN', 'boto=WARN',
                       'stevedore=WARN', 'taskflow=WARN',
                       'keystoneauth=WARN']
 
+_IGNORE_MESSAGE = "This option is ignored if log_config_append is set."
 
 common_cli_opts = [
     cfg.BoolOpt('debug',
                 short='d',
                 default=False,
-                help='Print debugging output (set logging level to '
-                     'DEBUG instead of default INFO level).'),
+                help='If set to true, the logging level will be set to '
+                     'DEBUG instead of the default INFO level.'),
     cfg.BoolOpt('verbose',
                 short='v',
                 default=True,
-                help='If set to false, will disable INFO logging level, '
-                     'making WARNING the default.',
+                help='If set to false, the logging level will be set to '
+                     'WARNING instead of the default INFO level.',
                 deprecated_for_removal=True),
 ]
 
@@ -52,9 +53,9 @@ logging_cli_opts = [
                     'is appended to any existing logging configuration '
                     'files. For details about logging configuration files, '
                     'see the Python logging module documentation. Note that '
-                    'when logging configuration files are used then all '
-                    'logging configuration is set in the configuration file '
-                    'and other logging configuration options are ignored '
+                    'when logging configuration files are used all '
+                    'logging configuration is defined in the configuration '
+                    'file and other logging configuration options are ignored '
                     '(for example, log_format).'),
     cfg.StrOpt('log-format',
                metavar='FORMAT',
@@ -68,54 +69,55 @@ logging_cli_opts = [
     cfg.StrOpt('log-date-format',
                default=_DEFAULT_LOG_DATE_FORMAT,
                metavar='DATE_FORMAT',
-               help='Format string for %%(asctime)s in log records. '
-                    'Default: %(default)s . This option is ignored if '
-                    'log_config_append is set.'),
+               help='Defines the format string for %%(asctime)s in log '
+                    'records. Default: %(default)s . '
+                    + _IGNORE_MESSAGE),
     cfg.StrOpt('log-file',
                metavar='PATH',
                deprecated_name='logfile',
-               help='(Optional) Name of log file to output to. '
-                    'If no default is set, logging will go to stdout. This '
-                    'option is ignored if log_config_append is set.'),
+               help='(Optional) Name of log file to send logging output to. '
+                    'If no default is set, logging will go to stderr as '
+                    'defined by use_stderr. '
+                    + _IGNORE_MESSAGE),
     cfg.StrOpt('log-dir',
                deprecated_name='logdir',
-               help='(Optional) The base directory used for relative '
-                    '--log-file paths. This option is ignored if '
-                    'log_config_append is set.'),
+               help='(Optional) The base directory used for relative log_file '
+                    ' paths. '
+                    + _IGNORE_MESSAGE),
     cfg.BoolOpt('watch-log-file',
                 default=False,
-                help='(Optional) Uses logging handler designed to watch file '
+                help='Uses logging handler designed to watch file '
                      'system. When log file is moved or removed this handler '
                      'will open a new log file with specified path '
-                     'instantaneously. It makes sense only if log-file option '
-                     'is specified and Linux platform is used. This option is '
-                     'ignored if log_config_append is set.'),
+                     'instantaneously. It makes sense only if log_file option '
+                     'is specified and Linux platform is used. '
+                     + _IGNORE_MESSAGE),
     cfg.BoolOpt('use-syslog',
                 default=False,
                 help='Use syslog for logging. '
                      'Existing syslog format is DEPRECATED '
-                     'and will be changed later to honor RFC5424. This option '
-                     'is ignored if log_config_append is set.'),
+                     'and will be changed later to honor RFC5424. '
+                     + _IGNORE_MESSAGE),
     cfg.BoolOpt('use-syslog-rfc-format',
                 default=True,
                 deprecated_for_removal=True,
-                help='(Optional) Enables or disables syslog rfc5424 format '
+                help='Enables or disables syslog rfc5424 format '
                      'for logging. If enabled, prefixes the MSG part of the '
                      'syslog message with APP-NAME (RFC5424). The '
                      'format without the APP-NAME is deprecated in Kilo, '
                      'and will be removed in Mitaka, along with this option. '
-                     'This option is ignored if log_config_append is set.'),
+                     + _IGNORE_MESSAGE),
     cfg.StrOpt('syslog-log-facility',
                default='LOG_USER',
-               help='Syslog facility to receive log lines. This option is '
-                    'ignored if log_config_append is set.')
+               help='Syslog facility to receive log lines. '
+                    + _IGNORE_MESSAGE),
 ]
 
 generic_log_opts = [
     cfg.BoolOpt('use_stderr',
                 default=True,
-                help='Log output to standard error. This option is ignored if '
-                     'log_config_append is set.')
+                help='Log output to standard error. '
+                     + _IGNORE_MESSAGE),
 ]
 
 log_opts = [
@@ -127,18 +129,25 @@ log_opts = [
     cfg.StrOpt('logging_default_format_string',
                default='%(asctime)s.%(msecs)03d %(process)d %(levelname)s '
                        '%(name)s [-] %(instance)s%(message)s',
-               help='Format string to use for log messages without context.'),
+               help='Format string to use for log messages when context is '
+                    'undefined.'),
     cfg.StrOpt('logging_debug_format_suffix',
                default='%(funcName)s %(pathname)s:%(lineno)d',
-               help='Data to append to log format when level is DEBUG.'),
+               help='Additional data to append to log message when logging '
+                    'level for the message is DEBUG.'),
     cfg.StrOpt('logging_exception_prefix',
                default='%(asctime)s.%(msecs)03d %(process)d ERROR %(name)s '
                '%(instance)s',
                help='Prefix each line of exception output with this format.'),
+    cfg.StrOpt('logging_user_identity_format',
+               default='%(user)s %(tenant)s '
+                       '%(domain)s %(user_domain)s %(project_domain)s',
+               help='Defines the format string for %(user_identity)s that '
+                    'is used in logging_context_format_string.'),
     cfg.ListOpt('default_log_levels',
                 default=DEFAULT_LOG_LEVELS,
-                help='List of logger=LEVEL pairs. This option is ignored if '
-                     'log_config_append is set.'),
+                help='List of package logging levels in logger=LEVEL pairs. '
+                     + _IGNORE_MESSAGE),
     cfg.BoolOpt('publish_errors',
                 default=False,
                 help='Enables or disables publication of error events.'),
@@ -154,11 +163,6 @@ log_opts = [
                default='[instance: %(uuid)s] ',
                help='The format for an instance UUID that is passed with the '
                     'log message.'),
-    cfg.StrOpt('logging_user_identity_format',
-               default='%(user)s %(tenant)s '
-                       '%(domain)s %(user_domain)s %(project_domain)s',
-               help='Format string for user_identity field of '
-                    'the logging_context_format_string'),
 ]
 
 
@@ -174,7 +178,8 @@ def list_opts():
     config files.
 
     The purpose of this is to allow tools like the Oslo sample config file
-    generator to discover the options exposed to users by this library.
+    generator (oslo-config-generator) to discover the options exposed to users
+    by this library.
 
     :returns: a list of (group_name, opts) tuples
     """