tessl/pypi-python-json-logger

JSON formatter for Python's built-in logging package that enables structured, machine-readable log output

—

Pending

Overview

Eval results

Files

High-Performance Formatting

Name: tessl/pypi-python-json-logger
Author: tessl

Alternative JSON formatters using orjson and msgspec libraries for improved performance in high-throughput logging scenarios. These formatters provide significant speed improvements over the standard json module.

Core Imports

For orjson formatter:

from pythonjsonlogger.orjson import OrjsonFormatter, orjson_default

For msgspec formatter:

from pythonjsonlogger.msgspec import MsgspecFormatter, msgspec_default

Checking availability:

import pythonjsonlogger
if pythonjsonlogger.ORJSON_AVAILABLE:
    # orjson is available
if pythonjsonlogger.MSGSPEC_AVAILABLE:
    # msgspec is available

Capabilities

OrjsonFormatter Class

JSON formatter using the orjson library for high-performance serialization.

class OrjsonFormatter(BaseJsonFormatter):
    def __init__(
        self,
        *args,
        json_default: OptionalCallableOrStr = orjson_default,
        json_indent: bool = False,
        **kwargs,
    ) -> None:
        """
        orjson-based JSON formatter initialization.

        Parameters:
        - args: see BaseJsonFormatter
        - json_default: function for encoding non-standard objects (defaults to orjson_default)
        - json_indent: indent output with 2 spaces
        - kwargs: see BaseJsonFormatter
        """

    def jsonify_log_record(self, log_record: LogRecord) -> str:
        """
        Convert log record to JSON string using orjson.

        Parameters:
        - log_record: dictionary containing log data

        Returns:
        JSON string representation using orjson serialization
        """

MsgspecFormatter Class

JSON formatter using the msgspec library for high-performance serialization with minimal memory overhead.

class MsgspecFormatter(BaseJsonFormatter):
    def __init__(
        self,
        *args,
        json_default: OptionalCallableOrStr = msgspec_default,
        **kwargs,
    ) -> None:
        """
        msgspec-based JSON formatter initialization.

        Parameters:
        - args: see BaseJsonFormatter  
        - json_default: function for encoding non-standard objects (defaults to msgspec_default)
        - kwargs: see BaseJsonFormatter
        """

    def jsonify_log_record(self, log_record: LogRecord) -> str:
        """
        Convert log record to JSON string using msgspec.

        Parameters:
        - log_record: dictionary containing log data

        Returns:
        JSON string representation using msgspec serialization
        """

Default Encoding Functions

Default encoder functions for handling non-standard types with orjson and msgspec.

def orjson_default(obj: Any) -> Any:
    """
    orjson default encoder function for non-standard types.

    Handles exceptions, tracebacks, bytes, enums, type objects,
    and unknown types.

    Parameters:
    - obj: object to encode

    Returns:
    Encodable representation of the object
    """

def msgspec_default(obj: Any) -> Any:
    """
    msgspec default encoder function for non-standard types.

    Handles exceptions, tracebacks, enums, type objects,
    and unknown types.

    Parameters:
    - obj: object to encode

    Returns:
    Encodable representation of the object
    """

Usage Examples

Using OrjsonFormatter

import logging
from pythonjsonlogger.orjson import OrjsonFormatter

# Check if orjson is available
import pythonjsonlogger
if pythonjsonlogger.ORJSON_AVAILABLE:
    # Set up high-performance JSON logging
    logger = logging.getLogger('high_perf_app')
    handler = logging.StreamHandler()
    
    # Use orjson formatter with indentation
    formatter = OrjsonFormatter(
        '%(levelname)s %(name)s %(message)s',
        json_indent=True
    )
    handler.setFormatter(formatter)
    logger.addHandler(handler)
    
    # High-speed JSON logging
    logger.info("Processing complete", extra={"records": 10000, "duration": 2.5})

Using MsgspecFormatter

import logging
from pythonjsonlogger.msgspec import MsgspecFormatter

# Check if msgspec is available
import pythonjsonlogger
if pythonjsonlogger.MSGSPEC_AVAILABLE:
    # Set up msgspec-based JSON logging  
    logger = logging.getLogger('msgspec_app')
    handler = logging.StreamHandler()
    
    formatter = MsgspecFormatter('%(levelname)s %(message)s')
    handler.setFormatter(formatter)
    logger.addHandler(handler)
    
    # Memory-efficient JSON logging
    logger.warning("Memory usage high", extra={"memory_mb": 1024, "threshold": 512})

Custom Default Functions

from pythonjsonlogger.orjson import OrjsonFormatter
import uuid

def custom_orjson_default(obj):
    if isinstance(obj, uuid.UUID):
        return str(obj)
    # Fall back to built-in default handling
    from pythonjsonlogger.orjson import orjson_default
    return orjson_default(obj)

formatter = OrjsonFormatter(
    '%(levelname)s %(message)s',
    json_default=custom_orjson_default
)

Conditional Formatter Selection

import logging
import pythonjsonlogger

def get_best_formatter():
    """Select the best available JSON formatter."""
    if pythonjsonlogger.ORJSON_AVAILABLE:
        from pythonjsonlogger.orjson import OrjsonFormatter
        return OrjsonFormatter('%(levelname)s %(name)s %(message)s')
    elif pythonjsonlogger.MSGSPEC_AVAILABLE:
        from pythonjsonlogger.msgspec import MsgspecFormatter
        return MsgspecFormatter('%(levelname)s %(name)s %(message)s')
    else:
        from pythonjsonlogger.json import JsonFormatter
        return JsonFormatter('%(levelname)s %(name)s %(message)s')

# Use the best available formatter
logger = logging.getLogger('adaptive_app')
handler = logging.StreamHandler()
handler.setFormatter(get_best_formatter())
logger.addHandler(handler)

Performance Considerations

orjson Benefits

Significantly faster JSON serialization than standard library
Better handling of large data structures
Native support for datetime objects
Supports indentation for readable output

msgspec Benefits

Extremely fast serialization with minimal memory allocation
Smallest memory footprint
Excellent for high-frequency logging scenarios
Built-in support for many Python types

Installation

# For orjson support (not available on PyPy)
pip install python-json-logger[orjson]

# For msgspec support (not available on PyPy)  
pip install python-json-logger[msgspec]

# For both high-performance options
pip install python-json-logger[dev]

Type Handling

Both orjson and msgspec formatters handle these types through their default functions:

Exception objects: Converted to "ExceptionClass: message" format
Traceback objects: Converted to formatted traceback strings
Enum objects: Converted to their values
bytes/bytearray: Converted to base64 strings (orjson only)
type objects: Converted to class names
Unknown types: Fallback to str() or repr(), or "could_not_encode"

Note: orjson and msgspec have native support for datetime objects, so they don't use the defaults module for those types.

Install with Tessl CLI

npx tessl i tessl/pypi-python-json-logger

docs

core-configuration.md

index.md

json-formatting.md

performance-formatting.md

type-handling.md

utilities.md

tile.json