1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
|
=======
Usage
=======
.. _usage-app:
In an Application
=================
When using `Python's standard logging library`_ the following minimal setup
demonstrates basic logging.
.. _Python's standard logging library: https://docs.python.org/2/library/logging.html
.. highlight:: python
.. literalinclude:: examples/python_logging.py
:linenos:
:lines: 17-26
Source: :ref:`examples/python_logging.py <example_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: :ref:`examples/oslo_logging.py <example_oslo_logging.py>`
Oslo Logging Setup 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 any application command line options.
.. literalinclude:: examples/usage.py
:linenos:
:lines: 33,36-37,46-49
:emphasize-lines: 7
Optionally call :func:`~oslo_log.log.set_defaults` before setup to
change default logging levels if necessary.
.. literalinclude:: examples/usage.py
:linenos:
:lines: 51-53,61-69
:emphasize-lines: 10
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.
.. literalinclude:: examples/usage.py
:linenos:
:lines: 34,36-37,70-72
:emphasize-lines: 6
Source: :ref:`examples/usage.py <example_usage.py>`
Oslo Logging Functions
----------------------
Use standard Python logging functions to produce log records at applicable
log levels.
.. literalinclude:: examples/usage.py
:linenos:
:lines: 77-83
**Example Logging Output:**
::
2016-01-14 21:07:51.394 12945 INFO __main__ [-] Welcome to Oslo Logging
2016-01-14 21:07:51.395 12945 WARNING __main__ [-] A warning occurred
2016-01-14 21:07:51.395 12945 ERROR __main__ [-] An error occurred
2016-01-14 21:07:51.396 12945 ERROR __main__ [-] An Exception occurred
2016-01-14 21:07:51.396 12945 ERROR __main__ None
2016-01-14 21:07:51.396 12945 ERROR __main__
Oslo Log Translation
--------------------
As of the Pike release, `logging within an application should no
longer use Oslo International Utilities (i18n) marker functions
<https://docs.openstack.org/oslo.i18n/latest/user/guidelines.html#log-translation>`_
to provide language translation capabilities.
Adding Context to Logging
-------------------------
With the use of `Oslo Context`_, log records can also contain
additional contextual information applicable for your application.
.. _Oslo Context: https://docs.openstack.org/oslo.context/latest
.. literalinclude:: examples/usage_context.py
:linenos:
:lines: 80-85
:emphasize-lines: 3-5
**Example Logging Output:**
::
2016-01-14 20:04:34.562 11266 INFO __main__ [-] Welcome to Oslo Logging
2016-01-14 20:04:34.563 11266 INFO __main__ [-] Without context
2016-01-14 20:04:34.563 11266 INFO __main__ [req-bbc837a6-be80-4eb2-8ca3-53043a93b78d 6ce90b4d d6134462 a6b9360e - -] With context
The log record output format without context is defined with
:oslo.config:option:`logging_default_format_string` configuration
variable. When specifying context the
:oslo.config:option:`logging_context_format_string` configuration
variable is used.
The Oslo RequestContext object contains a number of attributes that can be
specified in :oslo.config:option:`logging_context_format_string`. An
application can extend this object to provide additional attributes that can
be specified in log records.
Examples
--------
:ref:`examples/usage.py <example_usage.py>` provides a documented
example of Oslo Logging setup.
:ref:`examples/usage_helper.py <example_usage_helper.py>` provides an
example showing debugging logging at each step details the configuration
and logging at each step of Oslo Logging setup.
:ref:`examples/usage_context.py <example_usage_context.py>` provides
a documented example of Oslo Logging with Oslo Context.
In a Library
============
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.
|
