python-json-logger

Format Python's standard logging output as structured JSON

Library
PyPI
v4.2.0
278 stars
BSD-2-Clause

Repository Health

Pre-computed score based on development activity, maintenance, community, maturity, and trend momentum. How we score it →
80 /100 Excellent
Development Activity 88
Maintenance 88
Community 68
Maturity 48
Momentum 28

Technical Analysis

AI-assessed by reading the actual repository — architecture, code quality, innovation, and documentation. How we score it →
76 /100 Good
Architecture 74
Code Quality 78
Innovation 68
Learning Curve 82

python-json-logger is a lightweight formatter for Python’s built-in logging module that renders log records as JSON objects instead of plain text. Because JSON logs are machine-readable, they slot directly into log aggregation and observability pipelines (ELK, Datadog, CloudWatch, Loki) without custom parsing rules.

It ships as a drop-in logging.Formatter subclass, so existing logging configuration (handlers, levels, filters) keeps working unchanged — only the output format changes. The library also supports pluggable serializers (stdlib json, orjson, msgspec) and encodes common non-JSON-native types like exceptions, datetimes, and dataclasses automatically.

What You Get

  • A JsonFormatter class that plugs into any existing logging.Handler via setFormatter()
  • Automatic JSON-safe encoding of exceptions, tracebacks, datetimes, enums, bytes, and dataclasses
  • Optional high-performance serialization backends via orjson and msgspec extras
  • Configurable field renaming, static fields, and reserved-attribute exclusion for controlling log shape
  • Full typing support (py.typed) for type-checked logging configuration

Common Use Cases

  • Shipping application logs to Elasticsearch/OpenSearch or Loki without a separate log-parsing layer
  • Emitting structured logs for cloud-native platforms (CloudWatch, Stackdriver, Datadog) that index JSON fields natively
  • Standardizing log format across microservices so every service emits the same JSON schema
  • Correlating request/trace IDs and custom context fields directly as top-level JSON keys for querying

Under The Hood

Architecture - The package centers on core.BaseJsonFormatter (src/pythonjsonlogger/core.py), which extracts fields from a logging.LogRecord, strips reserved attributes, merges in extra fields and any static fields configured at init, then hands the resulting dict to a serializer-specific subclass. json.py implements the default JsonFormatter using stdlib json.dumps plus a custom JsonEncoder that dispatches unencodable types (datetimes, exceptions, enums, bytes, dataclasses) to helper functions in defaults.py. Optional orjson.py and msgspec.py modules provide alternate formatter subclasses that swap in faster serializers while reusing the same core field-extraction logic, so the format contract stays identical across backends.

Tech Stack - Pure Python (100% of the codebase), targeting Python 3.10+, with zero required runtime dependencies — orjson and msgspec are optional extras rather than core requirements. Build tooling uses setuptools with pyproject.toml-only configuration, mypy for type checking (with a dedicated mypy.ini), pylint for linting, and mkdocs/mkdocs-material for documentation, reflecting a deliberately dependency-light design appropriate for a logging shim used across many downstream projects.

Code Quality - The tests/ directory contains 5 test modules covering the core formatter, JSON/orjson/msgspec backends, and default-encoding behavior, run via pytest and tox across supported Python versions. The codebase is fully typed (py.typed marker, TypeAlias usage, strict mypy.ini), uses consistent section-comment banners (### IMPORTS, ### CLASSES) for navigability, and documents deprecations explicitly (e.g. the __getattr__ shim in json.py warns when the old RESERVED_ATTRS location is accessed). Docstrings follow a consistent Google-style format with Args:/Note: sections throughout.

API Design - Because JsonFormatter is a drop-in logging.Formatter subclass, adopting it requires zero changes to existing logger/handler setup beyond handler.setFormatter(JsonFormatter()) — a very low integration cost. Constructor kwargs (json_default, json_encoder, json_serializer, json_indent, json_ensure_ascii) map directly onto familiar json.dumps parameters, minimizing new concepts for Python developers. The main ergonomic rough edge is the historical API churn (v3 moved RESERVED_ATTRS out of the main module), mitigated by deprecation warnings rather than hard breaks.

Used by 4 apps in this directory

Python
64%
Other

Keep

Automation · Devops · Monitoring

12,499

The open-source AIOps and alert management platform that unifies 130+ monitoring tools into a single pane of glass with AI-powered correlation, deduplication, and workflow automation.

View details
87
Repo Health
79
Technical
66
Dependency
Built with
Python 64%
TypeScript 36%
Updated 1 weeks ago
TypeScript
39%
Apache 2.0

Label Studio

AI Development · Data Engineering

28,643

Label Studio is an open-source, multi-type data labeling platform that lets teams annotate images, text, audio, video, and time series data with a configurable XML-based UI and export annotations in formats ready for any ML framework.

View details
93
Repo Health
87
Technical
65
Dependency
Built with
TypeScript 39%
JavaScript 26%
Python 25%
Updated 1 weeks ago
Python
55%
Other

Onyx

AI Agents · AI Assistants · Knowledge Management

33,262

Self-hostable AI platform with agentic RAG, 50+ connectors, deep research, code execution, and support for every major LLM provider.

View details
92
Repo Health
83
Technical
68
Dependency
Built with
Python 55%
TypeScript 22%
JavaScript 16%
Updated 1 weeks ago
TypeScript
92%
Other

OpenHands

AI Code Assistants · AI Development

92,842

The self-hosted developer control center for running AI coding agents — locally, in Docker, on VMs, or across cloud backends — with automation workflows for GitHub, Slack, and more.

View details
91
Repo Health
82
Technical
67
Dependency
Built with
TypeScript 92%
Updated 1 weeks ago

Join founders buildingwith open source

Opinionated takes, migration guides, cost-saving tips, and insights from the open source ecosystem.

Subscribe on Substack
Join 750+ subscribers