diff options
| -rw-r--r-- | README.rst | 2 | ||||
| -rw-r--r-- | doc/source/api/formatters.rst | 8 | ||||
| -rw-r--r-- | doc/source/api/handlers.rst | 8 | ||||
| -rw-r--r-- | doc/source/api/helpers.rst | 8 | ||||
| -rw-r--r-- | doc/source/api/index.rst | 9 | ||||
| -rw-r--r-- | doc/source/api/log.rst | 12 | ||||
| -rw-r--r-- | doc/source/index.rst | 1 | ||||
| -rw-r--r-- | doc/source/usage.rst | 27 | ||||
| -rw-r--r-- | oslo_log/log.py | 33 | ||||
| -rw-r--r-- | requirements.txt | 8 |
10 files changed, 93 insertions, 23 deletions
@@ -9,4 +9,4 @@ support for context specific logging (like resource id's etc). * Free software: Apache license * Documentation: http://docs.openstack.org/developer/oslo.log * Source: http://git.openstack.org/cgit/openstack/oslo.log -* Bugs: http://bugs.launchpad.net/oslo +* Bugs: http://bugs.launchpad.net/oslo.log diff --git a/doc/source/api/formatters.rst b/doc/source/api/formatters.rst new file mode 100644 index 0000000..5ff6fd8 --- /dev/null +++ b/doc/source/api/formatters.rst @@ -0,0 +1,8 @@ +===================== + oslo_log.formatters +===================== + +.. automodule:: oslo_log.formatters + :members: + :undoc-members: + :show-inheritance: diff --git a/doc/source/api/handlers.rst b/doc/source/api/handlers.rst new file mode 100644 index 0000000..b02a32c --- /dev/null +++ b/doc/source/api/handlers.rst @@ -0,0 +1,8 @@ +===================== + oslo_log.handlers +===================== + +.. automodule:: oslo_log.handlers + :members: + :undoc-members: + :show-inheritance: diff --git a/doc/source/api/helpers.rst b/doc/source/api/helpers.rst new file mode 100644 index 0000000..747905a --- /dev/null +++ b/doc/source/api/helpers.rst @@ -0,0 +1,8 @@ +================== + oslo_log.helpers +================== + +.. automodule:: oslo_log.helpers + :members: + :undoc-members: + :show-inheritance: diff --git a/doc/source/api/index.rst b/doc/source/api/index.rst new file mode 100644 index 0000000..a02cdb7 --- /dev/null +++ b/doc/source/api/index.rst @@ -0,0 +1,9 @@ +=============== + API Reference +=============== + +.. toctree:: + :maxdepth: 1 + :glob: + + * diff --git a/doc/source/api/log.rst b/doc/source/api/log.rst new file mode 100644 index 0000000..b4d42be --- /dev/null +++ b/doc/source/api/log.rst @@ -0,0 +1,12 @@ +============== + oslo_log.log +============== + +.. automodule:: oslo_log.log + :members: + :undoc-members: + :show-inheritance: + +.. seealso:: + + :doc:`../usage` diff --git a/doc/source/index.rst b/doc/source/index.rst index c137e75..2edf365 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -11,6 +11,7 @@ Contents :maxdepth: 2 installation + api/index usage contributing history diff --git a/doc/source/usage.rst b/doc/source/usage.rst index b9dc444..69ef826 100644 --- a/doc/source/usage.rst +++ b/doc/source/usage.rst @@ -2,6 +2,29 @@ Usage ======= -To use oslo.log in a project:: +In a Library +============ - import oslo_log +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. + +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. diff --git a/oslo_log/log.py b/oslo_log/log.py index abf686d..1f08b88 100644 --- a/oslo_log/log.py +++ b/oslo_log/log.py @@ -195,6 +195,7 @@ def _load_log_config(log_config_append): def register_options(conf): + """Register the command line and configuration options used by oslo.log.""" conf.register_cli_opts(_options.common_cli_opts) conf.register_cli_opts(_options.logging_cli_opts) conf.register_opts(_options.generic_log_opts) @@ -203,7 +204,7 @@ def register_options(conf): def setup(conf, product_name, version='unknown'): - """Setup logging.""" + """Setup logging for the current application.""" if conf.log_config_append: _load_log_config(conf.log_config_append) else: @@ -213,6 +214,7 @@ def setup(conf, product_name, version='unknown'): def set_defaults(logging_context_format_string=None, default_log_levels=None): + """Set default values for the configuration options used by oslo.log.""" # Just in case the caller is not setting the # default_log_level. This is insurance because # we introduced the default_log_level parameter @@ -277,6 +279,20 @@ def _setup_logging_from_conf(conf, project, version): logging.ERROR) log_root.addHandler(handler) + if conf.use_syslog: + try: + facility = _find_facility_from_conf(conf) + # TODO(bogdando) use the format provided by RFCSysLogHandler + # after existing syslog format deprecation in J + if conf.use_syslog_rfc_format: + syslog = handlers.RFCSysLogHandler(facility=facility) + else: + syslog = logging.handlers.SysLogHandler(facility=facility) + log_root.addHandler(syslog) + except socket.error: + log_root.error('Unable to add syslog handler. Verify that syslog ' + 'is running.') + datefmt = conf.log_date_format for handler in log_root.handlers: # NOTE(alaski): CONF.log_format overrides everything currently. This @@ -310,21 +326,6 @@ def _setup_logging_from_conf(conf, project, version): else: logger.setLevel(level_name) - if conf.use_syslog: - try: - facility = _find_facility_from_conf(conf) - # TODO(bogdando) use the format provided by RFCSysLogHandler - # after existing syslog format deprecation in J - if conf.use_syslog_rfc_format: - syslog = handlers.RFCSysLogHandler(facility=facility) - else: - syslog = logging.handlers.SysLogHandler(facility=facility) - log_root.addHandler(syslog) - except socket.error: - log_root.error('Unable to add syslog handler. Verify that syslog ' - 'is running.') - - _loggers = {} diff --git a/requirements.txt b/requirements.txt index bff738c..c978f08 100644 --- a/requirements.txt +++ b/requirements.txt @@ -6,8 +6,8 @@ pbr>=0.6,!=0.7,<1.0 Babel>=1.3 six>=1.7.0 iso8601>=0.1.9 -oslo.config>=1.4.0 # Apache-2.0 +oslo.config>=1.6.0 # Apache-2.0 oslo.context>=0.1.0 # Apache-2.0 -oslo.i18n>=1.0.0 # Apache-2.0 -oslo.utils>=1.1.0 # Apache-2.0 -oslo.serialization>=1.0.0 # Apache-2.0 +oslo.i18n>=1.3.0 # Apache-2.0 +oslo.utils>=1.2.0 # Apache-2.0 +oslo.serialization>=1.2.0 # Apache-2.0 |