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
153
154
155
156
157
158
159
160
161
162
163
164
165
166
|
=======
Usage
=======
.. _usage-app:
In an Application
=================
When using `Python's standard logging library`_ the following minimal setup
demostrates 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_olso_logging.py>`
Olso 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>`
Olso 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:**
.. testoutput::
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__
Logging within an application should use `Oslo International Utilities (i18n)`_ marker
functions to provide language translation capabilities.
.. _Oslo International Utilities (i18n): http://docs.openstack.org/developer/oslo.i18n/
.. literalinclude:: examples/usage_i18n.py
:linenos:
:lines: 31-32,76,79-85
:emphasize-lines: 1
Source: :ref:`examples/usage_i18n.py <example_usage_i18n.py>`
With the use of `Oslo Context`_, log records can also contain
additional contextual information applicable for your application.
.. _Oslo Context: http://docs.openstack.org/developer/oslo.context/
.. literalinclude:: examples/usage_context.py
:linenos:
:lines: 80-85
:emphasize-lines: 3-5
**Example Logging Output:**
.. testoutput::
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
:ref:`logging_default_format_string <opt-default-logging_default_format_string>`
configuration variable. When specifying context the
:ref:`logging_context_format_string <opt-default-logging_context_format_string>`
configuration variable is used.
The Oslo RequestContext object contains a number of attributes that can be
specified in ``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_i18n.py <example_usage_i18n.py>` provides a
documented example of Oslo Logging with Oslo i18n supported messages.
:ref:`examples/usage_context.py <example_usage_context.py>` provides
a documented example of Oslo Logging with Oslo Context.
General Logging Guidelines
==========================
The `OpenStack Logging Guidelines`_ in openstack-specs repository
explain how to use different logging levels, and the desired logging
patterns to be used in OpenStack applications.
.. _OpenStack Logging Guidelines: http://specs.openstack.org/openstack/openstack-specs/specs/log-guidelines.html
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.
|
