Skip to main content

Convert structured JSON logs to human-readable output

Project description


A human readable formatter for JSON logs.

It's built for use with jsonlog but will work well with any log format that uses line delimited JSON.

Example output


See jsonlog --help for all options.

Key-value mode

Pass a file as the only argument to jsonlog, or read from STDIN by default.

jsonlog kv docs/example.log
python docs/ | jsonlog kv
cat docs/example.log | jsonlog

Only show the timestamp and message fields:

jsonlog kv --key timestamp --key message docs/example.log

Configure the keys of multiline values you want to display (can be specified multiple times, and defaults to the traceback key.)

jsonlog kv --key timestamp --key message --multiline-key traceback docs/example.log

Configure the key to extract and use as the records level, controlling the colour each line is printed in (defaults to the level key).

jsonlog kv --level-key level --key timestamp --key message --multiline-key traceback docs/example.log

Template mode

Only show the timestamp and message fields:

jsonlog template --format "{timestamp} {message}" docs/example.log

Also show a multiline key when it's present:

jsonlog template --format "{timestamp} {message}" --multiline-key traceback docs/example.log


Named "patterns" are supported as a way of collecting a set of options for jsonlog's key-value and template modes. If ~/.config/jsonlog/config.json exists, it will be loaded at startup. All fields should be optional.

The example configuration file below creates patterns named basic and comprehensive for the key-value and template modes. The patterns will each show the timestamp and message fields of incoming logs. The patterns named comprehensive override all fields, setting their their default values.

Creating a pattern named default will set the default options used if no pattern is specified. Command line options always override options from the application's default configuration, the configuration file and the selected pattern.

  "keyvalues": {
    "basic": {
      "priority_keys": ["timestamp", "message"]
    "comprehensive": {
      "level_key": "level",
      "multiline_json": false,
      "multiline_keys": [],
      "priority_keys": [],
      "removed_keys": []
  "templates": {
    "basic": {
      "format": "{timestamp} {message}"
    "comprehensive": {
      "level_key": "level",
      "multiline_json": false,
      "multiline_keys": [],
      "format": "{timestamp} {message}" 

The multiline_json option will parse incoming data using a buffer. This is rarely useful, but some applications (e.g. ElasticSearch) output JSON split across multiple lines. Incoming data will be buffered until the whole buffer can be parsed as JSON or a new line starts with {. Incoming lines that can be immediately parsed as JSON are not buffered (flushing the buffer first).


The jsonlog CLI has some flags that are useful when debugging. The following will print internal logs as JSON to STDERR.

jsonlog --log-path=- --log-level=debug kv ...


Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

jsonlog-cli-6.3.0.tar.gz (11.1 kB view hashes)

Uploaded Source

Built Distribution

jsonlog_cli-6.3.0-py3-none-any.whl (12.3 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page