JSON Log Formatter

Warnings

• gotcha As of v0.3.0, the formatter attempts a 'best effort' to serialize log records containing non-serializable values (e.g., WSGIRequest objects) instead of raising a TypeError. While this prevents crashes, it might result in altered or omitted data for those specific fields if not explicitly handled.
  Fix: Review logs to understand how non-serializable objects are represented. If specific serialization is required, override `JSONFormatter.json_record()` or ensure objects are pre-processed to be JSON-serializable.
• gotcha When using alternative JSON libraries like `ujson` or `simplejson` (by overriding `JSONFormatter.json_serializer`), be aware that `ujson` specifically does not support the `json.dumps(default=f)` argument. This can lead to `TypeError` exceptions or silently skipped attributes if objects cannot be serialized directly.
  Fix: If using `ujson` with custom types, ensure all objects passed to the logger are natively serializable by `ujson` or pre-serialize them. Alternatively, override `JSONFormatter.json_record()` to handle complex types explicitly before `ujson` attempts serialization. Consider `simplejson` for better `default` argument support.
• gotcha To add custom fields to every log record (e.g., user ID, IP address) or to customize the serialization of specific object types (e.g., `datetime` objects to timestamps), you must override the `json_record()` method in a custom formatter subclass. Not doing so will prevent these customizations from appearing in your logs.
  Fix: Subclass `JSONFormatter` and override the `json_record(self, message, extra, record)` method to manipulate the dictionary before JSON serialization. For example, add `extra` fields or format `datetime` objects.
• gotcha Logging sensitive data (e.g., passwords, API keys, PII) in JSON logs is a significant security risk. JSON's flexible structure makes it easy to accidentally include more data than intended, which can violate privacy regulations.
  Fix: Implement strict data filtering and redaction mechanisms *before* data reaches the logger. Carefully review `extra` dictionaries and any objects passed for serialization to ensure no sensitive information is present.

Install

• pip install json-log-formatter Install stable version

Imports

• JSONFormatter

  from json_log_formatter import JSONFormatter

  This is the primary formatter class for basic JSON output.
• VerboseJSONFormatter

  from json_log_formatter import VerboseJSONFormatter

  Use this formatter to include all built-in log record attributes.
• FlatJSONFormatter

  from json_log_formatter import FlatJSONFormatter

  Use this formatter to flatten complex objects into strings.

Quickstart

This quickstart demonstrates how to set up a basic logger using `JSONFormatter` to output structured JSON logs to standard output. It shows logging of informational messages with custom `extra` fields and how exceptions are handled.

import logging
import sys
from json_log_formatter import JSONFormatter

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

# Create a JSON formatter instance
formatter = JSONFormatter()

# Create a StreamHandler that writes to stdout
handler = logging.StreamHandler(sys.stdout)
handler.setFormatter(formatter)

# Add the handler to the logger
logger.addHandler(handler)

# Log some messages
logger.info('User signed up', extra={'user_id': 123, 'email': 'test@example.com'})
logger.warning('Payment failed', extra={'order_id': 'abc-123', 'reason': 'card declined'})

try:
    raise ValueError('Something went wrong!')
except ValueError:
    logger.error('An unexpected error occurred', exc_info=True, extra={'transaction_id': 'xyz-456'})