NAME¶

jl - pretty-print JSON logs

SYNOPSIS¶

jl [options...] [file]

DESCRIPTION¶

jl is a parser and formatter for JSON logs, making machine-readable JSON logs human readable again.

jl consumes JSON logs from stdin and writes human-readable logs to stdout. To use jl, just pipe your JSON logs through it:

    ./my-app-executable | jl
    cat app-log.json | jl

jl can read from a file:

    jl my-app-log.json

jl itself doesn't support following log files, but since it can consume from a pipe, you can use tail:

    tail -F app-log.json | jl

You can page jl's colorised output using less with the -R flag:

    jl my-app-log.json | less -R

OPTIONS¶

A summary of options is included below.

-color auto|yes|no

Set the color mode. The options are "auto", "yes", and "no". "auto" disables color if stdout is not a TTY (default: "auto")

-format compact|logfmt

Formatter for logs. The options are "compact" and "logfmt" (default: "compact")

-truncate[=false]

Whether to truncate strings in the compact formatter (default: true)

FORMATTERS¶

jl currently supports two formatters, with plans to make the formatters customizable.

The default is -format compact, which extracts only important fields from the JSON log, like message, timestamp, level, colorises and presents them in a easy to skim way. It drops unrecognised fields from the logs.

The other option is -format logfmt, which formats the JSON logs in a way that closely resembles logfmt This option emits all fields from each log line.

Both formatters echo non-JSON log lines as-is.

LOG FORMATS¶

JSON application logs tend to have some core shared fields, like level, timestamp, and message which jl tries to discover and prioritise for formatting. For now, the following formats work best with jl. For string fields other than level, only the keys matter.

Other formats can be used after preprocessing with jq.

• Java-like:

      {
        "level": "error",
        "timestamp": "2019-02-02 15:39:45",
        "logger": "HelloWorldService",
        "thread": "main",
        "message": "hello world",
        "exception": "java.lang.IllegalArgumentException: The world isn't here\n...stacktraces..."
      }
      

• Go/Logrus-like:

      {
        "level": "error",
        "timestamp": "2019-02-02 15:39:45",
        "msg": "hello world",
        "error": "hello error",
        "stack": "\nhello\n\thello.go\nworld\n\tworld.go"
      }
      

COPYRIGHT¶

Copyright (C) 2019-2023 Yunchi Luo

License: MIT/Expat

This manual page is based on the README document by the author. It was reformatted and adapted by Andrej Shadura <andrewsh@debian.org> for the Debian project, and is distributed under the same license as the original project.

SEE ALSO¶

jq(1), <https://blog.codeship.com/logfmt-a-log-format-thats-easy-to-read-and-write/>