refactor: added documentation and change classes' name

Author: Bob Bui

README.md

@@ -313,10 +313,10 @@ method:
 
 Class | Description | Mandatory
 --- | --- | ---
-RequestAdapter | Helper class help to extract logging-relevant information from HTTP request object | yes
-ResponseAdapter | Helper class help to extract logging-relevant information from HTTP response object | yes
-FrameworkConfigurator |  Class to perform logging configuration for given framework as needed | no
-AppRequestInstrumentationConfigurator | Class to perform request instrumentation logging configuration | no
+BaseRequestInfoExtractor | Helper class help to extract logging-relevant information from HTTP request object | yes
+BaseResponseInfoExtractor | Helper class help to extract logging-relevant information from HTTP response object | yes
+BaseFrameworkConfigurator |  Class to perform logging configuration for given framework as needed | no
+BaseAppRequestInstrumentationConfigurator | Class to perform request instrumentation logging configuration | no
 
 Take a look at [**json_logging/base_framework.py**](json_logging/framework_base.py), [**
 json_logging.flask**](json_logging/framework/flask) and [**json_logging.sanic**](json_logging/framework/sanic) packages

example/custom_log_format_request.py

@@ -43,7 +43,7 @@ def on_request_complete(self, response):
 json_logging.init_flask(enable_json=True)
 json_logging.init_request_instrument(app, exclude_url_patterns=[r'/exclude_from_request_instrumentation'],
                                      custom_formatter=CustomRequestJSONLog,
-                                     request_response_data_extractor_class=CustomDefaultRequestResponseDTO)
+                                     request_response_dto_class=CustomDefaultRequestResponseDTO)
 
 # init the logger as usual
 logger = logging.getLogger("test logger")

json_logging/__init__.py

@@ -7,8 +7,9 @@
 from json_logging import util
 from json_logging.dto import RequestResponseDTOBase, DefaultRequestResponseDTO
 from json_logging.formatters import JSONRequestLogFormatter, JSONLogFormatter, JSONLogWebFormatter
-from json_logging.framework_base import RequestAdapter, ResponseAdapter, AppRequestInstrumentationConfigurator, \
-    FrameworkConfigurator
+from json_logging.framework_base import BaseRequestInfoExtractor, BaseResponseInfoExtractor, \
+    BaseAppRequestInstrumentationConfigurator, \
+    BaseFrameworkConfigurator
 from json_logging.util import get_library_logger, is_env_var_toggle
 
 CORRELATION_ID_GENERATOR = uuid.uuid1
@@ -64,6 +65,11 @@ def config_root_logger():
 
 
 def init_non_web(*args, **kw):
+    """
+    Initialize for a non HTTP application
+    :param args:
+    :param kw:
+    """
     __init(*args, **kw)
 
 
@@ -106,8 +112,9 @@ def __init(framework_name=None, custom_formatter=None, enable_json=False):
         global _request_util
 
         _current_framework = _framework_support_map[framework_name]
-        _request_util = util.RequestUtil(request_adapter_class=_current_framework['request_adapter_class'],
-                                         response_adapter_class=_current_framework['response_adapter_class'])
+        _request_util = util.RequestUtil(
+            request_info_extractor_class=_current_framework['request_info_extractor_class'],
+            response_info_extractor_class=_current_framework['response_info_extractor_class'])
 
         if ENABLE_JSON_LOGGING and _current_framework['app_configurator'] is not None:
             _current_framework['app_configurator']().config()
@@ -126,15 +133,15 @@ def __init(framework_name=None, custom_formatter=None, enable_json=False):
 
 
 def init_request_instrument(app=None, custom_formatter=None, exclude_url_patterns=[],
-                            request_response_data_extractor_class=DefaultRequestResponseDTO):
+                            request_response_dto_class=DefaultRequestResponseDTO):
     """
     Configure the request instrumentation logging configuration for given web app. Must be called after init method
 
     If **custom_formatter** is passed, it will use this formatter over the default.
 
     :param app: current web application instance
     :param custom_formatter: formatter to override default JSONRequestLogFormatter.
-    :param request_response_data_extractor_class: request_response_data_extractor_class to override default json_logging.RequestResponseDataExtractor.
+    :param request_response_dto_class: request_response_dto_class to override default json_logging.RequestResponseDataExtractor.
     """
 
     if _current_framework is None or _current_framework == '-':
@@ -144,12 +151,12 @@ def init_request_instrument(app=None, custom_formatter=None, exclude_url_pattern
         if not issubclass(custom_formatter, logging.Formatter):
             raise ValueError('custom_formatter is not subclass of logging.Formatter', custom_formatter)
 
-    if not issubclass(request_response_data_extractor_class, RequestResponseDTOBase):
-        raise ValueError('request_response_data_extractor_class is not subclass of json_logging.RequestInfoBase',
+    if not issubclass(request_response_dto_class, RequestResponseDTOBase):
+        raise ValueError('request_response_dto_class is not subclass of json_logging.RequestInfoBase',
                          custom_formatter)
 
     configurator = _current_framework['app_request_instrumentation_configurator']()
-    configurator.config(app, request_response_data_extractor_class, exclude_url_patterns=exclude_url_patterns)
+    configurator.config(app, request_response_dto_class, exclude_url_patterns=exclude_url_patterns)
 
     formatter = custom_formatter if custom_formatter else JSONRequestLogFormatter
     request_logger = configurator.request_logger

json_logging/dto.py

@@ -5,7 +5,7 @@
 
 class RequestResponseDTOBase(dict):
     """
-        Data transfer object for HTTP request & response information for request instrumentation logging
+        Data transfer object (DTO) for HTTP request & response information for each request instrumentation logging
         Any key that is stored in this dict will be appended to final JSON log object
         Served as base class for any actual RequestResponseDTO implementation
     """

json_logging/formatters.py

@@ -5,7 +5,7 @@
 
 import json_logging
 
-# The list contains all the attributes listed in
+# The list contains all the attributes listed in that will not be overwritten by custom extra props
 # http://docs.python.org/library/logging.html#logrecord-attributes
 RECORD_ATTR_SKIP_LIST = [
     'asctime', 'created', 'exc_info', 'exc_text', 'filename', 'args',
@@ -23,13 +23,18 @@
     basestring = str
 
 if sys.version_info < (3, 0):
-    EASY_TYPES = (basestring, bool, dict, float, int, list, type(None))
+    EASY_SERIALIZABLE_TYPES = (basestring, bool, dict, float, int, list, type(None))
 else:
     RECORD_ATTR_SKIP_LIST.append('stack_info')
-    EASY_TYPES = (str, bool, dict, float, int, list, type(None))
+    EASY_SERIALIZABLE_TYPES = (str, bool, dict, float, int, list, type(None))
 
 
 def _sanitize_log_msg(record):
+    """
+    Sanitize log message to make sure we can print out properly formatted JSON string
+    :param record: log object
+    :return: sanitized log object
+    """
     return record.getMessage().replace('\n', '_').replace('\r', '_').replace('\t', '_')
 
 
@@ -49,31 +54,43 @@ def __init__(self, *args, **kw):
             self.base_object_common["component_instance_idx"] = json_logging.COMPONENT_INSTANCE_INDEX
 
     def format(self, record):
+        """
+            Format the specified record as text. Overriding default python logging implementation
+        """
         log_object = self._format_log_object(record, request_util=json_logging._request_util)
         return json_logging.JSON_SERIALIZER(log_object)
 
     def _format_log_object(self, record, request_util):
         utcnow = datetime.utcnow()
+
         base_obj = {
             "written_at": json_logging.util.iso_time_format(utcnow),
             "written_ts": json_logging.util.epoch_nano_second(utcnow),
         }
+
         base_obj.update(self.base_object_common)
         # Add extra fields
         base_obj.update(self._get_extra_fields(record))
+
         return base_obj
 
     def _get_extra_fields(self, record):
+        """
+        Get the dict of custom extra fields passed to the log statement
+        :param record: log record
+        :return:
+        """
         fields = {}
 
         if record.args:
             fields['msg'] = record.msg
 
         for key, value in record.__dict__.items():
             if key not in RECORD_ATTR_SKIP_LIST:
-                if isinstance(value, EASY_TYPES):
+                if isinstance(value, EASY_SERIALIZABLE_TYPES):
                     fields[key] = value
                 else:
+                    # try to cast it to a string representation
                     fields[key] = repr(value)
 
         # Always add 'props' to the root of the log, assumes props is a dict
@@ -83,46 +100,9 @@ def _get_extra_fields(self, record):
         return fields
 
 
-class JSONRequestLogFormatter(BaseJSONFormatter):
-    """
-       Formatter for HTTP request instrumentation logging
-    """
-
-    def _format_log_object(self, record, request_util):
-        json_log_object = super(JSONRequestLogFormatter, self)._format_log_object(record, request_util)
-        request_adapter = request_util.request_adapter
-        response_adapter = json_logging._request_util.response_adapter
-        request = record.request_response_data._request
-        response = record.request_response_data._response
-
-        length = request_adapter.get_content_length(request)
-
-        json_log_object.update({
-            "type": "request",
-            "correlation_id": request_util.get_correlation_id(request),
-            "remote_user": request_adapter.get_remote_user(request),
-            "request": request_adapter.get_path(request),
-            "referer": request_adapter.get_http_header(request, 'referer', json_logging.EMPTY_VALUE),
-            "x_forwarded_for": request_adapter.get_http_header(request, 'x-forwarded-for', json_logging.EMPTY_VALUE),
-            "protocol": request_adapter.get_protocol(request),
-            "method": request_adapter.get_method(request),
-            "remote_ip": request_adapter.get_remote_ip(request),
-            "request_size_b": json_logging.util.parse_int(length, -1),
-            "remote_host": request_adapter.get_remote_ip(request),
-            "remote_port": request_adapter.get_remote_port(request),
-            "response_status": response_adapter.get_status_code(response),
-            "response_size_b": response_adapter.get_response_size(response),
-            "response_content_type": response_adapter.get_content_type(response),
-        })
-
-        json_log_object.update(record.request_response_data)
-
-        return json_log_object
-
-
 class JSONLogFormatter(BaseJSONFormatter):
     """
-    Formatter for non-web application log
+    Default formatter for non-web application log
     """
 
     def get_exc_fields(self, record):
@@ -141,6 +121,7 @@ def format_exception(cls, exc_info):
 
     def _format_log_object(self, record, request_util):
         json_log_object = super(JSONLogFormatter, self)._format_log_object(record, request_util)
+
         json_log_object.update({
             "msg": _sanitize_log_msg(record),
             "type": "log",
@@ -159,13 +140,53 @@ def _format_log_object(self, record, request_util):
 
 class JSONLogWebFormatter(JSONLogFormatter):
     """
-    Formatter for web application log
+    Formatter for web application log with correlation-id
     """
 
     def _format_log_object(self, record, request_util):
         json_log_object = super(JSONLogWebFormatter, self)._format_log_object(record, request_util)
+
         if "correlation_id" not in json_log_object:
             json_log_object.update({
                 "correlation_id": request_util.get_correlation_id(within_formatter=True),
             })
         return json_log_object
+
+
+class JSONRequestLogFormatter(BaseJSONFormatter):
+    """
+       Formatter for HTTP request instrumentation logging
+    """
+
+    def _format_log_object(self, record, request_util):
+        json_log_object = super(JSONRequestLogFormatter, self)._format_log_object(record, request_util)
+
+        request_adapter = request_util.request_adapter
+        response_adapter = json_logging._request_util.response_adapter
+
+        request = record.request_response_data._request
+        response = record.request_response_data._response
+
+        length = request_adapter.get_content_length(request)
+
+        json_log_object.update({
+            "type": "request",
+            "correlation_id": request_util.get_correlation_id(request),
+            "remote_user": request_adapter.get_remote_user(request),
+            "request": request_adapter.get_path(request),
+            "referer": request_adapter.get_http_header(request, 'referer', json_logging.EMPTY_VALUE),
+            "x_forwarded_for": request_adapter.get_http_header(request, 'x-forwarded-for', json_logging.EMPTY_VALUE),
+            "protocol": request_adapter.get_protocol(request),
+            "method": request_adapter.get_method(request),
+            "remote_ip": request_adapter.get_remote_ip(request),
+            "request_size_b": json_logging.util.parse_int(length, -1),
+            "remote_host": request_adapter.get_remote_ip(request),
+            "remote_port": request_adapter.get_remote_port(request),
+            "response_status": response_adapter.get_status_code(response),
+            "response_size_b": response_adapter.get_response_size(response),
+            "response_content_type": response_adapter.get_content_type(response),
+        })
+
+        json_log_object.update(record.request_response_data)
+
+        return json_log_object

json_logging/framework/connexion/__init__.py

@@ -5,7 +5,8 @@
 import json_logging
 import json_logging.framework
 from json_logging import JSONLogWebFormatter
-from json_logging.framework_base import AppRequestInstrumentationConfigurator, RequestAdapter, ResponseAdapter
+from json_logging.framework_base import BaseAppRequestInstrumentationConfigurator, BaseRequestInfoExtractor, \
+    BaseResponseInfoExtractor
 from json_logging.util import is_not_match_any_pattern
 
 
@@ -30,8 +31,8 @@ def is_connexion_present():
     _connexion.g = g
 
 
-class ConnexionAppRequestInstrumentationConfigurator(AppRequestInstrumentationConfigurator):
-    def config(self, app, request_response_data_extractor_class, exclude_url_patterns=[]):
+class ConnexionAppRequestInstrumentationConfigurator(BaseAppRequestInstrumentationConfigurator):
+    def config(self, app, request_response_dto_class, exclude_url_patterns=[]):
         if not is_connexion_present():
             raise RuntimeError("connexion is not available in system runtime")
         from flask.app import Flask
@@ -51,7 +52,7 @@ def config(self, app, request_response_data_extractor_class, exclude_url_pattern
         @app.app.before_request
         def before_request():
             if is_not_match_any_pattern(_current_request.path, exclude_url_patterns):
-                g.request_response_data = request_response_data_extractor_class(_current_request)
+                g.request_response_data = request_response_dto_class(_current_request)
 
         @app.app.after_request
         def after_request(response):
@@ -62,7 +63,7 @@ def after_request(response):
             return response
 
 
-class ConnexionRequestAdapter(RequestAdapter):
+class ConnexionRequestInfoExtractor(BaseRequestInfoExtractor):
     @staticmethod
     def get_request_class_type():
         raise NotImplementedError
@@ -120,7 +121,7 @@ def get_remote_port(self, request):
         return request.environ.get('REMOTE_PORT')
 
 
-class ConnexionResponseAdapter(ResponseAdapter):
+class ConnexionResponseInfoExtractor(BaseResponseInfoExtractor):
     def get_status_code(self, response):
         return response.status_code
 

json_logging/framework/fastapi/__init__.py

@@ -10,4 +10,5 @@ def is_fastapi_present():
 
 
 if is_fastapi_present():
-    from .implementation import FastAPIAppRequestInstrumentationConfigurator, FastAPIRequestAdapter, FastAPIResponseAdapter
+    from .implementation import FastAPIAppRequestInstrumentationConfigurator, FastAPIRequestInfoExtractor, \
+        FastAPIResponseInfoExtractor

json_logging/framework/fastapi/implementation.py

@@ -2,7 +2,8 @@
 
 import json_logging
 import json_logging.framework
-from json_logging.framework_base import AppRequestInstrumentationConfigurator, RequestAdapter, ResponseAdapter
+from json_logging.framework_base import BaseAppRequestInstrumentationConfigurator, BaseRequestInfoExtractor, \
+    BaseResponseInfoExtractor
 
 from json_logging.util import is_not_match_any_pattern
 
@@ -40,13 +41,13 @@ async def dispatch(self, request: Request, call_next: RequestResponseEndpoint) -
         return response
 
 
-class FastAPIAppRequestInstrumentationConfigurator(AppRequestInstrumentationConfigurator):
-    def config(self, app, request_response_data_extractor_class, exclude_url_patterns=[]):
+class FastAPIAppRequestInstrumentationConfigurator(BaseAppRequestInstrumentationConfigurator):
+    def config(self, app, request_response_dto_class, exclude_url_patterns=[]):
         if not isinstance(app, fastapi.FastAPI):
             raise RuntimeError("app is not a valid fastapi.FastAPI instance")
 
         global _request_config_class
-        _request_config_class = request_response_data_extractor_class
+        _request_config_class = request_response_dto_class
 
         # Disable standard logging
         logging.getLogger('uvicorn.access').disabled = True
@@ -57,7 +58,7 @@ def config(self, app, request_response_data_extractor_class, exclude_url_pattern
         app.add_middleware(JSONLoggingASGIMiddleware, exclude_url_patterns=exclude_url_patterns)
 
 
-class FastAPIRequestAdapter(RequestAdapter):
+class FastAPIRequestInfoExtractor(BaseRequestInfoExtractor):
     @staticmethod
     def get_request_class_type():
         return starlette.requests.Request
@@ -116,7 +117,7 @@ def get_remote_port(self, request: starlette.requests.Request):
         return request.client.port
 
 
-class FastAPIResponseAdapter(ResponseAdapter):
+class FastAPIResponseInfoExtractor(BaseResponseInfoExtractor):
     def get_status_code(self, response: starlette.responses.Response):
         return response.status_code