Merge pull request #52 from quodlibetor/add-examples-to-readme

Add examples to readme

Author: Zakaria Zajac

README.markdown

@@ -12,7 +12,7 @@ Pip:
 
 Pypi:
 
-   https://pypi.python.org/pypi/python-json-logger 
+   https://pypi.python.org/pypi/python-json-logger
 
 Manual:
 
@@ -21,6 +21,8 @@ Manual:
 Usage
 =====
 
+## Integrating with Python's logging framework
+
 Json outputs are provided by the JsonFormatter logging formatter. You can add the customer formatter like below:
 
 **Please note: version 0.1.0 has changed the import structure, please update to the following example for proper importing**
@@ -36,85 +38,122 @@ Json outputs are provided by the JsonFormatter logging formatter. You can add th
     logHandler.setFormatter(formatter)
     logger.addHandler(logHandler)
 ```
-The fmt parser can also be overidden if you want to use an alternate from the default.
+
+## Customizing fields
+
+The fmt parser can also be overidden if you want to have required fields that differ from the default of just `message`.
+
+These two invocations are equivalent:
 
 ```python
-    class CustomJsonFormatter(jsonlogger.JsonFormatter):
-      def parse(self):
-          return eval(self._fmt)
+class CustomJsonFormatter(jsonlogger.JsonFormatter):
+    def parse(self):
+        return self._fmt.split(';')
+
+formatter = CustomJsonFormatter('one;two')
+
+# is equivalent to:
+
+formatter = jsonlogger.JsonFormatter('(one) (two)')
 ```
 
-You can also add extra fields to your json output by specifying a dict in place of message, as well as by specifying an extra={} argument.
+You can also add extra fields to your json output by specifying a dict in place of message, as well as by specifying an `extra={}` argument.
+
 Contents of these dictionaries will be added at the root level of the entry and may override basic fields.
+
+You can also use the `add_fields` method to add to or generally normalize the set of default set of fields, it is be called for every log event. For example, to unify default fields with those provided by [structlog](http://www.structlog.org/) you could do something like this:
+
+```python
+class CustomJsonFormatter(jsonlogger.JsonFormatter):
+    def add_fields(self, log_record, record, message_dict):
+        super(CustomJsonFormatter, self).add_fields(log_record, record, message_dict)
+        if not log_record.get('timestamp'):
+            # this doesn't use record.created, so it is slightly off
+            now = datetime.utcnow().strftime('%Y-%m-%dT%H:%M:%S.%fZ')
+            log_record['timestamp'] = now
+        if log_record.get('level'):
+            log_record['level'] = log_record['level'].upper()
+        else:
+            log_record['level'] = record.levelname
+
+formatter = CustomJsonFormatter('(timestamp) (level) (name) (message)')
+```
+
+Items added to the log record will be included in *every* log message, no matter what the format requires.
+
+## Adding custom object serialization
+
 For custom handling of object serialization you can specify default json object translator or provide a custom encoder
 
 ```python
-    def json_translate(obj):
-        if isinstance(obj, MyClass):
-            return {"special": obj.special}
+def json_translate(obj):
+    if isinstance(obj, MyClass):
+        return {"special": obj.special}
 
-    formatter = jsonlogger.JsonFormatter(json_default=json_translate,
-                                         json_encoder=json.JSONEncoder())
-    logHandler.setFormatter(formatter)
+formatter = jsonlogger.JsonFormatter(json_default=json_translate,
+                                     json_encoder=json.JSONEncoder())
+logHandler.setFormatter(formatter)
 
-    logger.info({"special": "value", "run": 12})
-    logger.info("classic message", extra={"special": "value", "run": 12})
+logger.info({"special": "value", "run": 12})
+logger.info("classic message", extra={"special": "value", "run": 12})
 ```
 
-With a Config File
-------------------
+## Using a Config File
+
 To use the module with a config file using the [`fileConfig` function](https://docs.python.org/3/library/logging.config.html#logging.config.fileConfig), use the class `pythonjsonlogger.jsonlogger.JsonFormatter`. Here is a sample config file.
 
-    [loggers]
-    keys = root,custom
-    
-    [logger_root]
-    handlers = 
-    
-    [logger_custom]
-    level = INFO
-    handlers = custom
-    qualname = custom
-    
-    [handlers]
-    keys = custom
-    
-    [handler_custom]
-    class = StreamHandler
-    level = INFO
-    formatter = json
-    args = (sys.stdout,)
-    
-    [formatters]
-    keys = json
-    
-    [formatter_json]
-    format = %(message)s
-    class = pythonjsonlogger.jsonlogger.JsonFormatter
-
-Example
-=======
+```ini
+[loggers]
+keys = root,custom
+
+[logger_root]
+handlers =
+
+[logger_custom]
+level = INFO
+handlers = custom
+qualname = custom
+
+[handlers]
+keys = custom
+
+[handler_custom]
+class = StreamHandler
+level = INFO
+formatter = json
+args = (sys.stdout,)
+
+[formatters]
+keys = json
+
+[formatter_json]
+format = %(message)s
+class = pythonjsonlogger.jsonlogger.JsonFormatter
+```
+
+Example Output
+==============
 
 Sample JSON with a full formatter (basically the log message from the unit test). Every log message will appear on 1 line like a typical logger.
 
 ```json
 {
-    "threadName": "MainThread", 
-    "name": "root", 
-    "thread": 140735202359648, 
-    "created": 1336281068.506248, 
-    "process": 41937, 
-    "processName": "MainProcess", 
-    "relativeCreated": 9.100914001464844, 
-    "module": "tests", 
-    "funcName": "testFormatKeys", 
-    "levelno": 20, 
-    "msecs": 506.24799728393555, 
-    "pathname": "tests/tests.py", 
-    "lineno": 60, 
-    "asctime": ["12-05-05 22:11:08,506248"], 
-    "message": "testing logging format", 
-    "filename": "tests.py", 
+    "threadName": "MainThread",
+    "name": "root",
+    "thread": 140735202359648,
+    "created": 1336281068.506248,
+    "process": 41937,
+    "processName": "MainProcess",
+    "relativeCreated": 9.100914001464844,
+    "module": "tests",
+    "funcName": "testFormatKeys",
+    "levelno": 20,
+    "msecs": 506.24799728393555,
+    "pathname": "tests/tests.py",
+    "lineno": 60,
+    "asctime": ["12-05-05 22:11:08,506248"],
+    "message": "testing logging format",
+    "filename": "tests.py",
     "levelname": "INFO",
     "special": "value",
     "run": 12

src/pythonjsonlogger/jsonlogger.py

@@ -86,7 +86,12 @@ def _default_json_handler(obj):
         self._skip_fields.update(RESERVED_ATTR_HASH)
 
     def parse(self):
-        """Parses format string looking for substitutions"""
+        """
+        Parses format string looking for substitutions
+
+        This method is responsible for returning a list of fields (as strings)
+        to include in all log messages.
+        """
         standard_formatters = re.compile(r'\((.+?)\)', re.IGNORECASE)
         return standard_formatters.findall(self._fmt)