JSON Formatter

0.3.4 · active · verified Wed Apr 15

jsonformatter is a Python library that provides a logging formatter to output log records as JSON objects. It allows for easy customization of LogRecord attributes, enabling users to include or replace fields, for instance, to integrate with log aggregation systems like Logstash. It supports Python 2.7 and Python 3. The latest version, 0.3.4, was released in November 2024, with an irregular but ongoing release cadence.

Warnings

gotcha This `jsonformatter` library (by MyColorfulDays, version 0.3.4) is distinct from `python-json-logger` (by madzak/nhairs), which is a more widely used and actively maintained alternative with a similar purpose. Users often confuse the two. If you're looking for the commonly recommended JSON logger, you might be looking for `python-json-logger`.
Fix: Verify the PyPI package name (`jsonformatter` vs `python-json-logger`) and the GitHub repository (`MyColorfulDays/jsonformatter` vs `nhairs/python-json-logger`) to ensure you are installing and using the intended library.
gotcha When logging objects that are not natively JSON serializable (e.g., custom class instances, `datetime` objects without special handling), `jsonformatter` may raise `TypeError` unless a custom `default` or `cls` parameter is provided to the `JsonFormatter` constructor. This is a common pitfall in Python's `json` module usage.
Fix: Pass a `default` callable or a custom `json.JSONEncoder` subclass via the `cls` parameter to the `JsonFormatter` constructor to define how non-serializable objects should be converted. For example, `JsonFormatter(format_string, default=str)` will convert such objects to their string representation.
deprecated While `jsonformatter` officially supports Python 2.7, Python 2 has reached its End-of-Life (EOL) and is no longer maintained. Using it in new projects or maintaining existing Python 2 projects carries security and compatibility risks.
Fix: For new development, use Python 3 exclusively. For existing projects, consider migrating to Python 3. `jsonformatter` is also compatible with Python 3, so ensure your environment uses a supported Python 3 version.

Install

pip install jsonformatter Install with pip

Imports

basicConfig
```
from jsonformatter import basicConfig
```
JsonFormatter
```
from jsonformatter import JsonFormatter
```

Quickstart

This quickstart demonstrates two ways to use `jsonformatter`: first, using `basicConfig` for a quick setup, and second, by creating a `JsonFormatter` instance with a custom format string and attaching it to a `StreamHandler`. It also shows how to include extra fields in log messages and handle exceptions.

import logging
from jsonformatter import basicConfig, JsonFormatter
import sys

# Basic configuration for JSON output to console
basicConfig(level=logging.INFO)
logging.info('Hello, jsonformatter basic config!')

# Example with custom formatter and fields
FORMAT_STRING = '''{
    "time": "asctime",
    "level": "levelname",
    "message": "message",
    "logger_name": "name",
    "process_id": "process"
}'''

logger = logging.getLogger('my_app')
logger.setLevel(logging.DEBUG)

handler = logging.StreamHandler(sys.stdout)
formatter = JsonFormatter(FORMAT_STRING)
handler.setFormatter(formatter)
logger.addHandler(handler)

logger.info('User logged in', extra={'user_id': 123, 'ip_address': '192.168.1.1'})
try:
    raise ValueError('Something went wrong')
except ValueError:
    logger.exception('An error occurred during processing.')

view raw JSON →