improve the documentation for log format strings
Incorporate some of the information from the upstream docs here and add information about a few of our custom message parameters. Change-Id: Ib6f934e7f5d6e43afa8021241f92000c644c5e6d Signed-off-by: Doug Hellmann <doug@doughellmann.com>
This commit is contained in:
Doug Hellmann
parent
0caffbd0db
commit
0defdcff96
|
|
@ -7,3 +7,141 @@ to allow the deployer to control how an application's logs are
|
|||
handled.
|
||||
|
||||
.. show-options:: oslo.log
|
||||
|
||||
Format Strings and Log Record Metadata
|
||||
======================================
|
||||
|
||||
oslo.log builds on top of the Python standard library logging
|
||||
module. The format string supports all of the built-in replacement
|
||||
keys provided by that library, with some additions. Some of the more
|
||||
useful keys are listed here. Refer to the `section on LogRecord
|
||||
attributes
|
||||
<https://docs.python.org/3.5/library/logging.html#logrecord-attributes>`__
|
||||
in the library documentation for complete details about the built-in
|
||||
values.
|
||||
|
||||
Basic Information
|
||||
-----------------
|
||||
|
||||
.. list-table::
|
||||
:header-rows: 1
|
||||
:widths: 25,75
|
||||
|
||||
- * Format key
|
||||
* Description
|
||||
- * ``%(message)s``
|
||||
* The message passed from the application code.
|
||||
|
||||
Time Information
|
||||
----------------
|
||||
|
||||
.. list-table::
|
||||
:header-rows: 1
|
||||
:widths: 25,75
|
||||
|
||||
- * Format key
|
||||
* Description
|
||||
- * ``%(asctime)s``
|
||||
* Human-readable time stamp of when the logging record was
|
||||
created, formatted as '2003-07-08 16:49:45,896' (the numbers
|
||||
after the comma are milliseconds).
|
||||
- * ``%(isotime)s``
|
||||
* Human-readable time stamp of when the logging record was
|
||||
created, using `Python's isoformat()
|
||||
<https://docs.python.org/3.5/library/datetime.html#datetime.datetime.isoformat>`__
|
||||
function in ISO 8601 format (``YYYY-MM-DDTHH:MM:SS.mmmmmm`` or,
|
||||
if the microseconds value is 0, ``YYYY-MM-DDTHH:MM:SS``).
|
||||
|
||||
Location Information
|
||||
--------------------
|
||||
|
||||
.. list-table::
|
||||
:header-rows: 1
|
||||
:widths: 25,75
|
||||
|
||||
- * Format key
|
||||
* Description
|
||||
- * ``%(pathname)s``
|
||||
* Full name of the source file where the logging call was issued,
|
||||
when it is available.
|
||||
- * ``%(filename)s``
|
||||
* Filename portion of ``pathname``.
|
||||
- * ``%(lineno)d``
|
||||
* Source line number where the logging call was issued, when it
|
||||
is available.
|
||||
- * ``%(module)s``
|
||||
* The module name is derived from the filename.
|
||||
- * ``%(name)s``
|
||||
* The name of the logger used to log the call. For OpenStack
|
||||
projects, this usually corresponds to the full module name
|
||||
(i.e., ``nova.api`` or ``oslo_config.cfg``).
|
||||
|
||||
Severity Information
|
||||
--------------------
|
||||
|
||||
.. list-table::
|
||||
:header-rows: 1
|
||||
:widths: 25,75
|
||||
|
||||
- * Format key
|
||||
* Description
|
||||
- * ``%(levelname)s``
|
||||
* Text logging level for the message (``DEBUG``, ``INFO``,
|
||||
``WARNING``, ``ERROR``, ``CRITICAL``).
|
||||
- * ``%(levelno)s``
|
||||
* Numeric logging level for the message. DEBUG level messages
|
||||
have a lower numerical value than INFO, which have a lower
|
||||
value than WARNING, etc.
|
||||
|
||||
Error Handling Information
|
||||
--------------------------
|
||||
|
||||
.. list-table::
|
||||
:header-rows: 1
|
||||
:widths: 25,75
|
||||
|
||||
- * Format key
|
||||
* Description
|
||||
- * ``%(error_summary)s``
|
||||
* The name of the exception being processed and any message
|
||||
associated with it.
|
||||
|
||||
Identity Information
|
||||
--------------------
|
||||
|
||||
*These keys are only available in OpenStack applications that also use
|
||||
oslo.context.*
|
||||
|
||||
.. list-table::
|
||||
:header-rows: 1
|
||||
:widths: 25,75
|
||||
|
||||
- * Format key
|
||||
* Description
|
||||
- * ``%(user_identity)s``
|
||||
* The pre-formatted identity information about the user. See the
|
||||
``logging_user_identity_format`` configuration option.
|
||||
- * ``%(user_name)s``
|
||||
* The name of the authenticated user, if available.
|
||||
- * ``%(user)s``
|
||||
* The ID of the authenticated user, if available.
|
||||
- * ``%(tenant_name)s``
|
||||
* The name of the authenticated tenant, if available.
|
||||
- * ``%(tenant)s``
|
||||
* The ID of the authenticated tenant, if available.
|
||||
- * ``%(user_domain)s``
|
||||
* The ID of the authenticated user domain, if available.
|
||||
- * ``%(project_domain)s``
|
||||
* The ID of the authenticated project/tenant, if available.
|
||||
- * ``%(request_id)s``
|
||||
* The ID of the current request. This value can be used to tie
|
||||
multiple log messages together as relating to the same
|
||||
operation.
|
||||
- * ``%(resource_uuid)s``
|
||||
* The ID of the resource on which the current operation will have
|
||||
effect. For example, the instance, network, volume, etc.
|
||||
|
||||
.. seealso::
|
||||
|
||||
* `Python logging library LogRecord attributes
|
||||
<https://docs.python.org/3.5/library/logging.html#logrecord-attributes>`__
|
||||
|
|
|
|||
Loading…
Reference in New Issue