add documentation with example of an external configuration file
Change-Id: I5f0af721e6a6b4c540a0b0b40496f441fa10b18f
This commit is contained in:
parent
ea7eaa4b06
commit
4c749ccaaa
|
@ -0,0 +1,84 @@
|
||||||
|
=========================================
|
||||||
|
Example Configuration File for ``nova``
|
||||||
|
=========================================
|
||||||
|
|
||||||
|
This sample configuration file demonstrates how the OpenStack compute
|
||||||
|
service (nova) might be configured.
|
||||||
|
|
||||||
|
.. literalinclude:: nova_sample.conf
|
||||||
|
:language: ini
|
||||||
|
:prepend: # nova_sample.conf
|
||||||
|
|
||||||
|
Two logger nodes are set up, ``root`` and ``nova``.
|
||||||
|
|
||||||
|
.. literalinclude:: nova_sample.conf
|
||||||
|
:language: ini
|
||||||
|
:lines: 1-2
|
||||||
|
|
||||||
|
Several handlers are created, to send messages to different outputs.
|
||||||
|
|
||||||
|
.. literalinclude:: nova_sample.conf
|
||||||
|
:language: ini
|
||||||
|
:lines: 4-5
|
||||||
|
|
||||||
|
And two formatters are created to be used based on whether the logging
|
||||||
|
location will have OpenStack request context information available or
|
||||||
|
not.
|
||||||
|
|
||||||
|
.. literalinclude:: nova_sample.conf
|
||||||
|
:language: ini
|
||||||
|
:lines: 7-8
|
||||||
|
|
||||||
|
The ``root`` logger is configured to send messages to the ``null``
|
||||||
|
handler, silencing most messages that are not part of the nova
|
||||||
|
application code namespace.
|
||||||
|
|
||||||
|
.. literalinclude:: nova_sample.conf
|
||||||
|
:language: ini
|
||||||
|
:lines: 10-12
|
||||||
|
|
||||||
|
The ``nova`` logger is configured to send messages marked as ``INFO``
|
||||||
|
and higher level to the standard error stream.
|
||||||
|
|
||||||
|
.. literalinclude:: nova_sample.conf
|
||||||
|
:language: ini
|
||||||
|
:lines: 14-17
|
||||||
|
|
||||||
|
The ``amqp`` and ``amqplib`` loggers, used by the module that connects
|
||||||
|
the application to the message bus, are configured to emit warning
|
||||||
|
messages to the standard error stream.
|
||||||
|
|
||||||
|
.. literalinclude:: nova_sample.conf
|
||||||
|
:language: ini
|
||||||
|
:lines: 19-27
|
||||||
|
|
||||||
|
The ``sqlalchemy`` logger, used by the module that connects the
|
||||||
|
application to the database, is configured to emit warning messages to
|
||||||
|
the standard error stream.
|
||||||
|
|
||||||
|
.. literalinclude:: nova_sample.conf
|
||||||
|
:language: ini
|
||||||
|
:lines: 29-35
|
||||||
|
|
||||||
|
Similarly, ``boto``, ``suds``, and ``eventlet.wsgi.server`` are
|
||||||
|
configured to send warnings to the standard error stream.
|
||||||
|
|
||||||
|
.. literalinclude:: nova_sample.conf
|
||||||
|
:language: ini
|
||||||
|
:lines: 37-53
|
||||||
|
|
||||||
|
The ``stderr`` handler, being used by most of the loggers above, is
|
||||||
|
configured to write to the standard error stream on the console.
|
||||||
|
|
||||||
|
.. literalinclude:: nova_sample.conf
|
||||||
|
:language: ini
|
||||||
|
:lines: 55-58
|
||||||
|
|
||||||
|
The ``stderr`` handler uses the ``context`` formatter, which takes its
|
||||||
|
configuration settings from ``oslo.config``.
|
||||||
|
|
||||||
|
.. literalinclude:: nova_sample.conf
|
||||||
|
:language: ini
|
||||||
|
:lines: 80-81
|
||||||
|
|
||||||
|
The ``stdout`` and ``syslog`` handlers are defined, but not used.
|
|
@ -0,0 +1,47 @@
|
||||||
|
==============================
|
||||||
|
Advanced Configuration Files
|
||||||
|
==============================
|
||||||
|
|
||||||
|
The oslo.config options described in :doc:`/opts` make it easy to
|
||||||
|
enable some default logging configuration behavior such as setting the
|
||||||
|
default log level and output file. For more advanced configurations
|
||||||
|
using translations or multiple output destinations oslo.log relies on
|
||||||
|
the Python standard library logging module configuration file
|
||||||
|
features.
|
||||||
|
|
||||||
|
The configuration file can be used to tie together the loggers,
|
||||||
|
handlers, and formatters and provide all of the necessary
|
||||||
|
configuration values to enable any desired behavior. Refer to the
|
||||||
|
`Python logging Module Tutorial`_ for descriptions of these concepts.
|
||||||
|
|
||||||
|
Logger Names
|
||||||
|
============
|
||||||
|
|
||||||
|
Loggers are configured by name. Most OpenStack applications use logger
|
||||||
|
names based on the source file where the message is coming from. A
|
||||||
|
file named ``myapp/package/module.py`` corresponds to a logger named
|
||||||
|
``myapp.package.module``.
|
||||||
|
|
||||||
|
Loggers are configured in a tree structure, and the names reflect
|
||||||
|
their location in this hierarchy. It is not necessary to configure
|
||||||
|
every logger, since messages are passed up the tree during
|
||||||
|
processing. To control the logging for ``myapp``, for example, it is
|
||||||
|
only necessary to set up a logger for ``myapp`` and not
|
||||||
|
``myapp.package.module``.
|
||||||
|
|
||||||
|
The base of the tree, through which all log message may pass unless
|
||||||
|
otherwise discarded, is called the ``root`` logger.
|
||||||
|
|
||||||
|
Example Files
|
||||||
|
=============
|
||||||
|
|
||||||
|
.. toctree::
|
||||||
|
:glob:
|
||||||
|
|
||||||
|
example*
|
||||||
|
|
||||||
|
.. seealso::
|
||||||
|
|
||||||
|
* `Python logging Module Tutorial`_
|
||||||
|
|
||||||
|
.. _Python logging Module Tutorial: https://docs.python.org/2.7/howto/logging.html
|
|
@ -0,0 +1,84 @@
|
||||||
|
[loggers]
|
||||||
|
keys = root, nova
|
||||||
|
|
||||||
|
[handlers]
|
||||||
|
keys = stderr, stdout, watchedfile, syslog, null
|
||||||
|
|
||||||
|
[formatters]
|
||||||
|
keys = context, default
|
||||||
|
|
||||||
|
[logger_root]
|
||||||
|
level = WARNING
|
||||||
|
handlers = null
|
||||||
|
|
||||||
|
[logger_nova]
|
||||||
|
level = INFO
|
||||||
|
handlers = stderr
|
||||||
|
qualname = nova
|
||||||
|
|
||||||
|
[logger_amqp]
|
||||||
|
level = WARNING
|
||||||
|
handlers = stderr
|
||||||
|
qualname = amqp
|
||||||
|
|
||||||
|
[logger_amqplib]
|
||||||
|
level = WARNING
|
||||||
|
handlers = stderr
|
||||||
|
qualname = amqplib
|
||||||
|
|
||||||
|
[logger_sqlalchemy]
|
||||||
|
level = WARNING
|
||||||
|
handlers = stderr
|
||||||
|
qualname = sqlalchemy
|
||||||
|
# "level = INFO" logs SQL queries.
|
||||||
|
# "level = DEBUG" logs SQL queries and results.
|
||||||
|
# "level = WARNING" logs neither. (Recommended for production systems.)
|
||||||
|
|
||||||
|
[logger_boto]
|
||||||
|
level = WARNING
|
||||||
|
handlers = stderr
|
||||||
|
qualname = boto
|
||||||
|
|
||||||
|
# NOTE(mikal): suds is used by the vmware driver, removing this will
|
||||||
|
# cause many extraneous log lines for their tempest runs. Refer to
|
||||||
|
# https://review.openstack.org/#/c/219225/ for details.
|
||||||
|
[logger_suds]
|
||||||
|
level = INFO
|
||||||
|
handlers = stderr
|
||||||
|
qualname = suds
|
||||||
|
|
||||||
|
[logger_eventletwsgi]
|
||||||
|
level = WARNING
|
||||||
|
handlers = stderr
|
||||||
|
qualname = eventlet.wsgi.server
|
||||||
|
|
||||||
|
[handler_stderr]
|
||||||
|
class = StreamHandler
|
||||||
|
args = (sys.stderr,)
|
||||||
|
formatter = context
|
||||||
|
|
||||||
|
[handler_stdout]
|
||||||
|
class = StreamHandler
|
||||||
|
args = (sys.stdout,)
|
||||||
|
formatter = context
|
||||||
|
|
||||||
|
[handler_watchedfile]
|
||||||
|
class = handlers.WatchedFileHandler
|
||||||
|
args = ('nova.log',)
|
||||||
|
formatter = context
|
||||||
|
|
||||||
|
[handler_syslog]
|
||||||
|
class = handlers.SysLogHandler
|
||||||
|
args = ('/dev/log', handlers.SysLogHandler.LOG_USER)
|
||||||
|
formatter = context
|
||||||
|
|
||||||
|
[handler_null]
|
||||||
|
class = logging.NullHandler
|
||||||
|
formatter = default
|
||||||
|
args = ()
|
||||||
|
|
||||||
|
[formatter_context]
|
||||||
|
class = oslo_log.formatters.ContextFormatter
|
||||||
|
|
||||||
|
[formatter_default]
|
||||||
|
format = %(message)s
|
|
@ -13,6 +13,7 @@ logging (like resource id's etc).
|
||||||
installation
|
installation
|
||||||
usage
|
usage
|
||||||
opts
|
opts
|
||||||
|
configfiles/index
|
||||||
contributing
|
contributing
|
||||||
history
|
history
|
||||||
|
|
||||||
|
|
Loading…
Reference in New Issue