======= 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 ` 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 ` 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 ` 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__ 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 ` 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:** :: 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 ` provides a documented example of Oslo Logging setup. :ref:`examples/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 ` provides a documented example of Oslo Logging with Oslo i18n supported messages. :ref:`examples/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.