diff options
author | Jenkins <jenkins@review.openstack.org> | 2017-05-21 16:10:28 +0000 |
---|---|---|
committer | Gerrit Code Review <review@openstack.org> | 2017-05-21 16:10:28 +0000 |
commit | b3665b70a632759e8dbfa2a6238d139dc9f4f916 (patch) | |
tree | 3352b44870c413247b28a3e34cfb59f812a441ae | |
parent | 49422ab97fe8dac280b3f240f7325380f37ac7d1 (diff) | |
parent | 0defdcff96568a94358f396105ad9276a1cdb001 (diff) | |
download | oslo-log-b3665b70a632759e8dbfa2a6238d139dc9f4f916.tar.gz |
Merge "improve the documentation for log format strings"
-rw-r--r-- | doc/source/opts.rst | 138 |
1 files changed, 138 insertions, 0 deletions
diff --git a/doc/source/opts.rst b/doc/source/opts.rst index 4e95f4d..f329f8e 100644 --- a/doc/source/opts.rst +++ b/doc/source/opts.rst @@ -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>`__ |