Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/lfex/logjam

A custom formatter for the Erlang logger application that produces human-readable output
https://github.com/lfex/logjam

ansi-colors erlang formatter lfe logger logging

Last synced: 1 day ago
JSON representation

A custom formatter for the Erlang logger application that produces human-readable output

Awesome Lists containing this project

README 

        
# logjam



[![Build Status][gh-actions-badge]][gh-actions]

[![LFE Versions][lfe badge]][lfe]

[![Erlang Versions][erlang badge]][versions]

[![Tags][github tags badge]][github tags]



[![Project Logo][logo]][logo-large]



*A custom formatter for the logger application with LFE logging macros and human-readable output*



## Why?



The default formatter for Erlang is very difficult to read at a glance making troubleshooting and debugging of applications via log output during development phases rather cumbersome or even difficult.



With logjam, you get something nice and easy to read:



[![][screenshot]][screenshot]



## About



Previous versions of logjam wrapped older versions of the lager logging library. As of Erlang 21.0, Erlang has a new (and excellent) logging library, yet the same output is used (and thus the same problems regarding developer readability persist). The [flatlog][flatlog] library was created to provide structured logging support for the new logger library, and this project was used as the basis of logjam 1.0. Logjam provides additional configuration on top of the code inherited from flatlog, and while it does support much of the same structured logging that flatlog provides, its goals are completely different.



For versions of Erlang older than 21.0 (and for LFE 1.2), you may be able to use the [0.6.0 release](https://github.com/lfex/logjam/releases/tag/0.6.0) of logjam.



## Usage



There are two ways to use logjam:



1. Simply as a formatter, in which case it should be to the release apps and not included as a dependency. This assumes you will be using the logger macros included with Erlang/OTP.

1. As both a formatter as well as taking advantage of the logjam logging macros that have Lisp-style names (e.g., `log-debug`). In this case, you will want to include logjam as a dependency.



### Configuration



Once the project is added, replace the formatter of the default handler (or add a custom handler) for structured logging to your `sys.config` file:



```erlang

[

  {kernel, [

      {logger, [

          {handler, default, logger_std_h,

          #{level => info,

            formatter => {logjam,

              #{colored => true,

                time_designator => $\s,

                time_offset => "",

                time_unit => second,

                strip_tz => true,

                level_capitalize => true

              }

            }

           }

          }

      ]}

  ]}

].

```



This configuration was used to produce the screenshot above.



Note that if you are building a release, you will need to manually add

the `logjam` dependency to your `relx` configuration, since it is

technically not a direct dependency of any application in your system.



If you're not using an OTP release and just want to set up logging based upon a config file with the above entry in it, you can do the following:



```lisp

(logjam:set-config #(path "./path/to/thing.config"))

```



This is what is done in `./scripts/demo.lfe`.



If you have the config data already in above format (proplist with a `kernel` entry), you can just do this:



```lisp

(logjam:set-config config-data)

```



### Logging Calls



If you call the logger functions directly, your log output will not have reference to the module, function, arity, or line number where the logging call was made. For this info, you need to use the `logger` or `logjam` macros.



Include the `logger` calls with either:



```lisp

(include-lib "kernel/include/logger.hrl")

```



or



```erlang

-include_lib("kernel/include/logger.hrl").

```



This will let you call the logging macros such as `(LOG_DEBUG "my message")` or `?LOG_DEBUG("my message").`



If you'd like to use the `logjam` macros, use these instead:



```lisp

(include-lib "logjam/include/logjam.hrl")

```



or



```erlang

-include_lib("logjam/include/logjam.hrl").

```



This will let you call the logging macros such as `(log-debug "my message")` or `?'log-debug'("my message").`



Here is some example LFE usage:



```lisp

(log-debug "This is a debug-level message")

(log-info "This is an info-level message")

(log-notice "This is a notice-level message")

(log-warn "This is a warning-level message")

(log-error "This is an error-level message")

(log-crit "This is a critical-level message")

(log-alert "This is an alert-level message")

(log-emergency "This is an emergency-level message")

(log-info #m(some "structured" logging "examples" might "be useful too")))

```



## Demo



``` bash

rebar3 demo

```



## Test



```bash

rebar3 check

```



[//]: ---Named-Links---



[logo]: priv/images/logjam-crop-small.png

[logo-large]: priv/images/logjam.jpg

[screenshot]: priv/images/screenshot.png

[gh-actions-badge]: https://github.com/lfex/logjam/workflows/ci%2Fcd/badge.svg

[gh-actions]: https://github.com/lfex/logjam/actions

[lfe]: https://github.com/rvirding/lfe

[lfe badge]: https://img.shields.io/badge/lfe-2.1+-blue.svg

[erlang badge]: https://img.shields.io/badge/erlang-21%20to%2025-blue.svg

[versions]: https://github.com/lfex/logjam/blob/master/.travis.yml

[github tags]: https://github.com/lfex/logjam/tags

[github tags badge]: https://img.shields.io/github/tag/lfex/logjam.svg

[flatlog]: https://github.com/ferd/flatlog