=encoding utf8

=head1 NAME

B<jl> - pretty-print JSON logs

=head1 SYNOPSIS

B<jl> [I<options...>] [I<file>]

=head1 DESCRIPTION

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

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

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

B<jl> can read from a file:

    jl my-app-log.json

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

    tail -F app-log.json | jl

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

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

=head1 OPTIONS

A summary of options is included below.

=over

=item B<-color> B<auto>|B<yes>|B<no>

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

=item B<-format> B<compact>|B<logfmt>

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

=item B<-truncate>[B<=false>]

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

=back

=head1 FORMATTERS

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

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

The other option is B<-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.

=head1 LOG FORMATS

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

Other formats can be used after preprocessing with B<jq>.

=over

=item * 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..."
    }

=item * 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"
    }

=back

=head1 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 L<< <andrewsh@debian.org> >>
for the Debian project, and is distributed under the same license as the
original project.

=head1 SEE ALSO

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