Restore app-agnostic-logging-parameters spec
bp/app-agnostic-logging-parameters spec Change-Id: I7a25e00f1fb3ad6f043527502f1fa1b9385b0d3e
This commit is contained in:
Doug Hellmann
parent
612232fd72
commit
35ebb89c60
181
specs/kilo/app-agnostic-logging-parameters.rst
Normal file
181
specs/kilo/app-agnostic-logging-parameters.rst
Normal file
@ -0,0 +1,181 @@
|
||||
===================================================================
|
||||
Provide application-agnostic logging parameters in format strings
|
||||
===================================================================
|
||||
|
||||
https://blueprints.launchpad.net/oslo.log/+spec/app-agnostic-logging-parameters
|
||||
|
||||
We still have some nova-specific names in the default logging format
|
||||
string, and we want to eliminate those to make oslo.log more generally
|
||||
useful across projects.
|
||||
|
||||
Problem description
|
||||
===================
|
||||
|
||||
The default ``logging_context_format_string`` and
|
||||
``logging_default_format_string`` option values include
|
||||
``%(instance)s``, which is not useful in all projects. We should do
|
||||
something like what we did with "user_identity" and provide a generic
|
||||
name, which the projects can fill in with their desired value.
|
||||
|
||||
Proposed change
|
||||
===============
|
||||
|
||||
Make :class:`RequestContext` from :mod:`openstack.common.context` into
|
||||
an abstract base class for other applications to use for their own
|
||||
application-specific request contexts. In the new base class, define
|
||||
some abstract properties with generic names like ``user_identity``,
|
||||
``resource_id``, the chain of request ids, etc. that the subclass
|
||||
can override.
|
||||
|
||||
Change the default for the logging format strings to refer to these
|
||||
generic names.
|
||||
|
||||
Add a new method to the base class to return values useful for
|
||||
logging. We cannot use the existing :meth:`to_dict` because we expect
|
||||
the logging values to contain generated properties not used for things
|
||||
like reconstructing the context when it passes through RPC calls.
|
||||
|
||||
::
|
||||
|
||||
def get_logging_values(self):
|
||||
"""Return a dict containing values for logging using this context.
|
||||
"""
|
||||
values = self.to_dict()
|
||||
values.update({
|
||||
'user_identity': self.user_identity,
|
||||
'resource_id': self.resource_id,
|
||||
'request_chain': ' '.join(self.request_ids),
|
||||
})
|
||||
return values
|
||||
|
||||
Remove the other functions in the :mod:`context` module for creating
|
||||
and testing contexts. The applications all have their own version of
|
||||
these functions and the versions provided in :mod:`context` are not
|
||||
useful when subclasses of :class:`RequestContext` are used.
|
||||
|
||||
Update the logging code to use :meth:`get_logging_values` instead of
|
||||
:meth:`to_dict`.
|
||||
|
||||
Alternatives
|
||||
------------
|
||||
|
||||
We had previously talked about removing this module entirely, but
|
||||
given changes to logging to make the user identity parameters log
|
||||
consistently across projects, I think making it a useful base class is
|
||||
a better approach.
|
||||
|
||||
Impact on Existing APIs
|
||||
-----------------------
|
||||
|
||||
Existing context classes will be updated to be subclasses of the base
|
||||
class, which may allow us to save some repeated code in the
|
||||
constructor.
|
||||
|
||||
Security impact
|
||||
---------------
|
||||
|
||||
When we talk about logging and contexts together we typically worry
|
||||
about exposing secret details. I don't think any of these proposed
|
||||
changes expose any information beyond what we are exposing already.
|
||||
|
||||
Performance Impact
|
||||
------------------
|
||||
|
||||
Possibly a slight impact creating :class:`RequestContext` instances in
|
||||
the application. If an app sees that as a problem, they could opt to
|
||||
simply copy the base class API into their local class rather than
|
||||
using a subclass, but it would be up to them to keep up with API
|
||||
changes at that point. I don't think this is a significant performance
|
||||
issue.
|
||||
|
||||
Configuration Impact
|
||||
--------------------
|
||||
|
||||
The defaults for the configuration options might change, but the
|
||||
*output* should be the same and the old values will still work as well
|
||||
as they did before.
|
||||
|
||||
Developer Impact
|
||||
----------------
|
||||
|
||||
The idea is for the other projects to define their context as a
|
||||
subclass of the :class:`RequestContext` in Oslo, implementing or
|
||||
overriding private methods or properties in order to meet the API
|
||||
needed by the logging module.
|
||||
|
||||
Implementation
|
||||
==============
|
||||
|
||||
Assignee(s)
|
||||
-----------
|
||||
|
||||
Primary assignee:
|
||||
Doug Hellmann (doug-hellmann)
|
||||
|
||||
Other contributors:
|
||||
None
|
||||
|
||||
Milestones
|
||||
----------
|
||||
|
||||
Target Milestone for completion: Kilo-2
|
||||
|
||||
Work Items
|
||||
----------
|
||||
|
||||
1. Remove unused functions from :mod:`context`.
|
||||
2. Add new :meth:`get_logging_values` to :class:`RequestContext`.
|
||||
3. Add abstract properties to :class:`RequestContext`.
|
||||
4. Update default format strings in :mod:`log`.
|
||||
5. Update :mod:`log` to use :meth:`get_logging_values`.
|
||||
|
||||
Incubation
|
||||
==========
|
||||
|
||||
N/A
|
||||
|
||||
Adoption
|
||||
--------
|
||||
|
||||
N/A
|
||||
|
||||
Library
|
||||
-------
|
||||
|
||||
N/A
|
||||
|
||||
Anticipated API Stabilization
|
||||
-----------------------------
|
||||
|
||||
I expect :meth:`get_logging_values` to be stable.
|
||||
|
||||
We may add more generated properties to :class:`RequestContext` over
|
||||
time, but we will have to add those as normal properties (not
|
||||
abstract) to provide backwards compatibility.
|
||||
|
||||
Documentation Impact
|
||||
====================
|
||||
|
||||
The defaults for the config options will need to be updated in any
|
||||
documentation generated from the option definitions.
|
||||
|
||||
Dependencies
|
||||
============
|
||||
|
||||
None
|
||||
|
||||
References
|
||||
==========
|
||||
|
||||
* Discussion at the juno summit:
|
||||
https://etherpad.openstack.org/p/juno-oslo-release-plan
|
||||
* Mailing list thread that mentions the domain support in Oslo's
|
||||
context as a potential issue for nova:
|
||||
http://lists.openstack.org/pipermail/openstack-dev/2014-February/027634.html
|
||||
|
||||
|
||||
.. note::
|
||||
|
||||
This work is licensed under a Creative Commons Attribution 3.0
|
||||
Unported License.
|
||||
http://creativecommons.org/licenses/by/3.0/legalcode
|
||||
Loading…
Reference in New Issue
Block a user