JSON Logging for Python

1.5.1 · active · verified Sun Apr 12

json-logging is a Python library that enables structured JSON logging for your applications. It provides a `JSONLogFormatter` that outputs log records as JSON objects, making them easier to consume by log management systems like ELK stack. The library is actively maintained, with the current stable version being 1.5.1, and receives regular updates to address issues and add framework support.

Warnings

breaking The import path for `JSONLogFormatter` changed from `json_logging.default_formatter.JSONLogFormatter` to `json_logging.JSONLogFormatter` in version 1.5.0.
Fix: Update your imports to `from json_logging import JSONLogFormatter` when upgrading to 1.5.0 or newer.
gotcha The `init_json_logging()` function must be called early in your application's lifecycle, before any loggers are used, to ensure all relevant loggers are correctly configured with the JSON formatter. Calling it too late might result in some logs not being formatted as JSON.
Fix: Place `json_logging.init_json_logging()` at the very beginning of your application's entry point, e.g., `app.py` or `main.py`.
deprecated When running with Python 3.12+, older versions of `json-logging` (<1.5.1) may produce deprecation warnings or errors related to `datetime.utcnow()`. This was addressed in version 1.5.1.
Fix: Upgrade to `json-logging` version 1.5.1 or newer to ensure compatibility and avoid `utcnow` related issues.
gotcha For full request and response context logging in web frameworks like Flask, FastAPI, or Connexion, `init_json_logging()` alone is often not sufficient. You usually need to integrate specific middleware or call framework-specific helper functions (e.g., `json_logging.util.add_request_and_response_fields` for Flask) to ensure request/response data is captured.
Fix: Refer to the `json-logging` documentation for your specific web framework for detailed integration steps beyond basic initialization.

Install

pip install json-logging Install stable version

Imports

init_json_logging

from json_logging import init_json_logging

ENABLE_JSON_LOGGING

from json_logging import ENABLE_JSON_LOGGING

JSONLogFormatter
```
from json_logging import JSONLogFormatter
```
Path changed in version 1.5.0 due to internal refactoring. Older versions used the 'default_formatter' submodule.

Quickstart

Initializes JSON logging for your application and demonstrates how to log standard messages and messages with extra fields. The `init_json_logging` function configures the root logger (or a specific logger if provided) to use the `JSONLogFormatter`. Messages are output as JSON objects to `stdout` by default.

import logging
import json_logging
import sys

# Initialize JSON logging early in your application lifecycle
json_logging.init_json_logging(enable_json=True)

# Configure a logger
logger = logging.getLogger('my_app_logger')
logger.setLevel(logging.INFO)

# Ensure the handler is using the JSON formatter
# json_logging.init_json_logging typically handles this for the root logger
# or its own default handler. For custom handlers, ensure they use JSONLogFormatter.
# For example:
# handler = logging.StreamHandler(sys.stdout)
# handler.setFormatter(json_logging.JSONLogFormatter())
# logger.addHandler(handler)

logger.info('This is a basic info log message.')
logger.warning('A warning occurred!', extra={'event_id': 'WARN-001', 'user': 'test_user'})

try:
    1 / 0
except ZeroDivisionError as e:
    logger.error('An error occurred during division.', exc_info=True, extra={'operation': 'math', 'error_type': str(type(e))})

print('\n--- Example Output (trimmed for brevity) ---\n')
# To see output, run this script.

view raw JSON →