1=======
2 Usage
3=======
4
5oslo.context is used in conjunction with `oslo.log`_ to provide context
6aware log records when specifying a :class:`~oslo_context.context.RequestContext`
7object.
8
9This code example demonstrates two INFO log records with varying output
10format due to the use of RequestContext.
11
12.. _oslo.log: https://docs.openstack.org/oslo.log/latest/
13
14.. highlight:: python
15.. literalinclude:: examples/usage_simple.py
16   :linenos:
17   :lines: 28-42
18   :emphasize-lines: 2,14
19
20Source: :ref:`example_usage_simple.py`
21
22**Example Logging Output:**
23
24.. code-block:: none
25
26    2016-01-20 21:56:29.283 8428 INFO __main__ [-] Message without context
27    2016-01-20 21:56:29.284 8428 INFO __main__ [req-929d23e9-f50e-46ae-a8a7-02bc8c3fd2c8 - - - - -] Message with context
28
29The format of these log records are defined by the
30`logging_default_format_string`_ and `logging_context_format_string`_
31configuration options respectively. The `logging_user_identity_format`_ option
32also provides further context aware definition flexibility.
33
34.. _logging_default_format_string: https://docs.openstack.org/oslo.log/latest/configuration/index.html#DEFAULT.logging_default_format_string
35.. _logging_context_format_string: https://docs.openstack.org/oslo.log/latest/configuration/index.html#DEFAULT.logging_context_format_string
36.. _logging_user_identity_format: https://docs.openstack.org/oslo.log/latest/configuration/index.html#DEFAULT.logging_user_identity_format
37
38-----------------
39Context Variables
40-----------------
41
42The oslo.context variables used in the **logging_context_format_string** and
43**logging_user_identity_format** configuration options include:
44
45* global_request_id - A request id
46  (e.g. req-9f2c484a-b504-4fd9-b44c-4357544cca50) which may have been
47  sent in from another service to indicate this is part of a chain of requests.
48* request_id - A request id (e.g. req-9f2c484a-b504-4fd9-b44c-4357544cca50)
49* user - A user id (e.g. e5bc7033e6b7473c9fe8ee1bd4df79a3)
50* tenant - A tenant/project id (e.g. 79e338475db84f7c91ee4e86b79b34c1)
51* domain - A domain id
52* user_domain - A user domain id
53* project_domain - A project domain id
54
55
56This code example demonstrates defining a context with specific attributes
57that are presented in the output log record.
58
59.. literalinclude:: examples/usage.py
60   :linenos:
61   :lines: 28-46
62   :emphasize-lines: 2,16-18
63
64Source: :ref:`example_usage.py`
65
66**Example Logging Output:**
67
68.. code-block:: none
69
70    2016-01-21 17:30:50.263 12201 INFO __main__ [-] Message without context
71    2016-01-21 17:30:50.264 12201 INFO __main__ [req-e591e881-36c3-4627-a5d8-54df200168ef 6ce90b4d d6134462 - - a6b9360e] Message with context
72
73A context object can also be passed as an argument to any logging level
74message.
75
76.. literalinclude:: examples/usage.py
77   :linenos:
78   :lines: 48-51
79   :emphasize-lines: 4
80
81**Example Logging Output:**
82
83.. code-block:: none
84
85    2016-01-21 22:43:55.621 17295 INFO __main__ [req-ac2d4a3a-ff3c-4c2b-97a0-2b76b33d9e72 ace90b4d b6134462 - - c6b9360e] Message with passed context
86
87.. note::
88
89    To maintain consistent log messages for operators across multiple
90    OpenStack projects it is highly recommended that
91    **logging_default_format_string** and **logging_context_format_string** are
92    not modified from oslo.log default values.
93
94
95--------------------------
96Project Specific Variables
97--------------------------
98
99Individual projects can also subclass :class:`~oslo_context.context.RequestContext`
100to provide additional attributes that can be using with oslo.log. The Nova
101`RequestContext`_ class for example provides additional variables including
102user_name and project_name.
103
104.. _RequestContext: https://opendev.org/openstack/nova/src/branch/master/nova/context.py
105
106This can for example enable the defining of **logging_user_identity_format =
107%(user_name)s %(project_name)s** which would produce a log record
108containing a context portion using names instead of ids such as
109**[req-e4b9a194-a9b1-4829-b7d0-35226fc101fc admin demo]**
110
111This following code example shows how a modified **logging_user_identity_format**
112configuration alters the context portion of the log record.
113
114.. literalinclude:: examples/usage_user_identity.py
115   :linenos:
116   :lines: 28-48
117   :emphasize-lines: 9
118
119Source: :ref:`example_usage_user_identity.py`
120
121
122**Example Logging Output:**
123
124.. code-block:: none
125
126    2016-01-21 20:56:43.964 14816 INFO __main__ [-] Message without context
127    2016-01-21 20:56:43.965 14816 INFO __main__ [req-abc 6ce90b4d/d6134462@a6b9360e] Message with context
128