diff options
| -rw-r--r-- | .gitignore | 2 | ||||
| -rwxr-xr-x | doc/source/conf.py | 2 | ||||
| -rw-r--r-- | doc/source/examples.rst | 37 | ||||
| -rw-r--r-- | doc/source/examples/usage.py | 51 | ||||
| -rw-r--r-- | doc/source/examples/usage_simple.py | 42 | ||||
| -rw-r--r-- | doc/source/examples/usage_user_identity.py | 48 | ||||
| -rw-r--r-- | doc/source/index.rst | 1 | ||||
| -rw-r--r-- | doc/source/usage.rst | 121 |
8 files changed, 300 insertions, 4 deletions
@@ -4,7 +4,7 @@ *.so # Packages -*.egg +*.egg* *.egg-info dist build diff --git a/doc/source/conf.py b/doc/source/conf.py index bf20de1..ca1f348 100755 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -38,7 +38,7 @@ master_doc = 'index' # General information about the project. project = u'oslo.context' -copyright = u'2014, OpenStack Foundation' +copyright = u'2016, OpenStack Foundation' # If true, '()' will be appended to :func: etc. cross-reference text. add_function_parentheses = True diff --git a/doc/source/examples.rst b/doc/source/examples.rst new file mode 100644 index 0000000..016487a --- /dev/null +++ b/doc/source/examples.rst @@ -0,0 +1,37 @@ +========== + Examples +========== + +.. _examples: + +These files can be found in the doc/source/examples directory of +the git source of this project. They can also be found at the +`online git respository`_ of this project. + +.. _online git respository: http://git.openstack.org/cgit/openstack/oslo.context/tree/doc/source/examples + + +.. _example_usage_simple.py: + +usage_simple.py +--------------- + +.. highlight:: python +.. literalinclude:: examples/usage_simple.py + :linenos: + +.. _example_usage.py: + +usage.py +-------- + +.. literalinclude:: examples/usage.py + :linenos: + +.. _example_usage_user_identity.py: + +usage_user_identity.py +---------------------- + +.. literalinclude:: examples/usage_user_identity.py + :linenos: diff --git a/doc/source/examples/usage.py b/doc/source/examples/usage.py new file mode 100644 index 0000000..53c4654 --- /dev/null +++ b/doc/source/examples/usage.py @@ -0,0 +1,51 @@ +#!/usr/bin/env python +# +# Copyright (c) 2015 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 respresentative usage example of Oslo Context + +This example requires the following modules to be installed. + +$ pip install oslo.context oslo.log + +More information can be found at: + + http://docs.openstack.org/developer/oslo.context/usage.html +""" + +from oslo_config import cfg +from oslo_context import context +from oslo_log import log as logging + +CONF = cfg.CONF +DOMAIN = "demo" + +logging.register_options(CONF) +logging.setup(CONF, DOMAIN) + +LOG = logging.getLogger(__name__) + +LOG.info("Message without context") +# ids in Openstack are 32 characters long +# For readability a shorter id value is used +context.RequestContext(user='6ce90b4d', + tenant='d6134462', + project_domain='a6b9360e') +LOG.info("Message with context") + +context = context.RequestContext(user='ace90b4d', + tenant='b6134462', + project_domain='c6b9360e') +LOG.info("Message with passed context", context=context) diff --git a/doc/source/examples/usage_simple.py b/doc/source/examples/usage_simple.py new file mode 100644 index 0000000..4755395 --- /dev/null +++ b/doc/source/examples/usage_simple.py @@ -0,0 +1,42 @@ +#!/usr/bin/env python +# +# Copyright (c) 2015 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 simple usage example of Oslo Context + +This example requires the following modules to be installed. + +$ pip install oslo.context oslo.log + +More information can be found at: + + http://docs.openstack.org/developer/oslo.context/usage.html +""" + +from oslo_config import cfg +from oslo_context import context +from oslo_log import log as logging + +CONF = cfg.CONF +DOMAIN = "demo" + +logging.register_options(CONF) +logging.setup(CONF, DOMAIN) + +LOG = logging.getLogger(__name__) + +LOG.info("Message without context") +context.RequestContext() +LOG.info("Message with context") diff --git a/doc/source/examples/usage_user_identity.py b/doc/source/examples/usage_user_identity.py new file mode 100644 index 0000000..609f696 --- /dev/null +++ b/doc/source/examples/usage_user_identity.py @@ -0,0 +1,48 @@ +#!/usr/bin/env python +# +# Copyright (c) 2015 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 Context with user_identity + +This example requires the following modules to be installed. + +$ pip install oslo.context oslo.log + +More information can be found at: + + http://docs.openstack.org/developer/oslo.context/usage.html +""" + +from oslo_config import cfg +from oslo_context import context +from oslo_log import log as logging + +CONF = cfg.CONF +DOMAIN = "demo" + +logging.register_options(CONF) +CONF.logging_user_identity_format = "%(user)s/%(tenant)s@%(project_domain)s" +logging.setup(CONF, DOMAIN) + +LOG = logging.getLogger(__name__) + +LOG.info("Message without context") +# ids in Openstack are 32 characters long +# For readability a shorter id value is used +context.RequestContext(request_id='req-abc', + user='6ce90b4d', + tenant='d6134462', + project_domain='a6b9360e') +LOG.info("Message with context") diff --git a/doc/source/index.rst b/doc/source/index.rst index 86b923f..411f6f3 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -7,6 +7,7 @@ Contents: installation usage + examples contributing history diff --git a/doc/source/usage.rst b/doc/source/usage.rst index a1e9e92..8c84163 100644 --- a/doc/source/usage.rst +++ b/doc/source/usage.rst @@ -2,6 +2,123 @@ Usage ======= -To use oslo.context in a project:: +oslo.context is used in conjunction with `oslo.log`_ to provide context +aware log records when specifying a :class:`~oslo_context.context.RequestContext` +object. - from oslo_context import context +This code example demonstrates two INFO log records with varying output +format due to the use of RequestContext. + +.. _oslo.log: http://docs.openstack.org/developer/oslo.log/ + +.. highlight:: python +.. literalinclude:: examples/usage_simple.py + :linenos: + :lines: 28-42 + :emphasize-lines: 2,14 + +Source: :ref:`example_usage_simple.py` + +**Example Logging Output:** + +:: + + 2016-01-20 21:56:29.283 8428 INFO __main__ [-] Message without context + 2016-01-20 21:56:29.284 8428 INFO __main__ [req-929d23e9-f50e-46ae-a8a7-02bc8c3fd2c8 - - - - -] Message with context + +The format of these log records are defined by the +`logging_default_format_string`_ and `logging_context_format_string`_ +configuration options respectively. The `logging_user_identity_format`_ option +also provides further context aware definition flexibility. + +.. _logging_default_format_string: http://docs.openstack.org/developer/oslo.log/opts.html#logging_default_format_string +.. _logging_context_format_string: http://docs.openstack.org/developer/oslo.log/opts.html#logging_context_format_string +.. _logging_user_identity_format: http://docs.openstack.org/developer/oslo.log/opts.html#logging_user_identity_format + +----------------- +Context Variables +----------------- + +The oslo.context variables used in the **logging_context_format_string** and +**logging_user_identity_format** configuration options include: + +* request_id - A request id (e.g. req-9f2c484a-b504-4fd9-b44c-4357544cca50) +* user - A user id (e.g. e5bc7033e6b7473c9fe8ee1bd4df79a3) +* tenant - A tenant/project id (e.g. 79e338475db84f7c91ee4e86b79b34c1) +* domain - A domain id +* user_domain - A user domain id +* project_domain - A project domain id + + +This code example demonstrates defining a context with specific attributes +that are presented in the output log record. + +.. literalinclude:: examples/usage.py + :linenos: + :lines: 28-46 + :emphasize-lines: 2,16-18 + +Source: :ref:`example_usage.py` + +**Example Logging Output:** + +:: + + 2016-01-21 17:30:50.263 12201 INFO __main__ [-] Message without context + 2016-01-21 17:30:50.264 12201 INFO __main__ [req-e591e881-36c3-4627-a5d8-54df200168ef 6ce90b4d d6134462 - - a6b9360e] Message with context + +A context object can also be passed as an argument to any logging level +message. + +.. literalinclude:: examples/usage.py + :linenos: + :lines: 48-51 + :emphasize-lines: 4 + +**Example Logging Output:** + +:: + + 2016-01-21 22:43:55.621 17295 INFO __main__ [req-ac2d4a3a-ff3c-4c2b-97a0-2b76b33d9e72 ace90b4d b6134462 - - c6b9360e] Message with passed context + +.. note:: + + To maintain consistent log messages for operators across multiple + OpenStack projects it is highly recommended that + **logging_default_format_string** and **logging_context_format_string** are + not modified from oslo.log default values. + + +-------------------------- +Project Specific Variables +-------------------------- + +Individual projects can also subclass :class:`~oslo_context.context.RequestContext` +to provide additional attributes that can be using with oslo.log. The Nova +`RequestContext`_ class for example provides additional variables including +user_name and project_name. + +.. _RequestContext: http://git.openstack.org/cgit/openstack/nova/tree/nova/context.py + +This can for example enable the defining of **logging_user_identity_format = +%(user_name)s %(project_name)s** which would produce a log record +containing a context portion using names instead of ids such as +**[req-e4b9a194-a9b1-4829-b7d0-35226fc101fc admin demo]** + +This following code example shows how a modified **logging_user_identity_format** +configuration alters the context portion of the log record. + +.. literalinclude:: examples/usage_user_identity.py + :linenos: + :lines: 28-48 + :emphasize-lines: 9 + +Source: :ref:`example_usage_user_identity.py` + + +**Example Logging Output:** + +:: + + 2016-01-21 20:56:43.964 14816 INFO __main__ [-] Message without context + 2016-01-21 20:56:43.965 14816 INFO __main__ [req-abc 6ce90b4d/d6134462@a6b9360e] Message with context |