Improve Context docs with example syntax
Added examples to explain how use Oslo Context with Oslo Log. Change-Id: I5b5d2ee152b305316b68c5b34d00f480c7daf5ba
This commit is contained in:
Ronald Bradford
parent
e6dfe63641
commit
b621d4eecc
2
.gitignore
vendored
2
.gitignore
vendored
@ -4,7 +4,7 @@
|
||||
*.so
|
||||
|
||||
# Packages
|
||||
*.egg
|
||||
*.egg*
|
||||
*.egg-info
|
||||
dist
|
||||
build
|
||||
|
||||
@ -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
|
||||
|
||||
37
doc/source/examples.rst
Normal file
37
doc/source/examples.rst
Normal file
@ -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:
|
||||
51
doc/source/examples/usage.py
Normal file
51
doc/source/examples/usage.py
Normal file
@ -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)
|
||||
42
doc/source/examples/usage_simple.py
Normal file
42
doc/source/examples/usage_simple.py
Normal file
@ -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")
|
||||
48
doc/source/examples/usage_user_identity.py
Normal file
48
doc/source/examples/usage_user_identity.py
Normal file
@ -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")
|
||||
@ -7,6 +7,7 @@ Contents:
|
||||
|
||||
installation
|
||||
usage
|
||||
examples
|
||||
contributing
|
||||
history
|
||||
|
||||
|
||||
@ -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
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user