diff --git a/doc/source/examples/_i18n.py b/doc/source/examples/_i18n.py new file mode 100644 index 00000000..3bc9256c --- /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 00000000..886278a1 --- /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 00000000..44605da1 --- /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 00000000..8466050e --- /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 00000000..0b5baa47 --- /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 00000000..ef53f849 --- /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 706db8f9..f19855b0 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 00000000..25d13c4a --- /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 29fd4785..442a323f 100644 --- a/doc/source/usage.rst +++ b/doc/source/usage.rst @@ -2,6 +2,79 @@ Usage ======= +.. _usage-app: + +In an Application +================= + +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 before using standard logging functions. + +Call :func:`~oslo_log.log.register_options` with an oslo.config CONF object +before parsing the application command line options. + +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. + + +General Logging Guidelines +========================== + +The `OpenStack Logging Guidelines`_ in openstack-specs repository +explain how to use different logging levels, and the desired logging +patterns to be used in OpenStack applications. + +.. _OpenStack Logging Guidelines: http://specs.openstack.org/openstack/openstack-specs/specs/log-guidelines.html + In a Library ============ @@ -13,149 +86,3 @@ 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 -logging-related configuration options and configure the root and other -default loggers. - -Call :func:`~oslo_log.log.register_options` before parsing command -line options. - -Call :func:`~oslo_log.log.set_defaults` before configuring logging. - -Call :func:`~oslo_log.log.setup` to configure logging for the -application. - -General Logging Guidelines -========================== - -The `OpenStack Logging Guidelines`_ in openstack-specs repository -explain how to use different logging levels, and the desired logging -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. diff --git a/oslo_log/_options.py b/oslo_log/_options.py index 660e3051..1d0e2a1b 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 """