Logrex <img src="https://i.imgur.com/UEbtVhA.jpg" width="40" height="40" alt=":trex:" class="emoji" title=":trex:"/>

An Elixir package for more easily adding Logger metadata and formatting the console output so it's easier for humans to parse.

It lets you write code like this:

user = "Matt"
login_info = %{total_logins: 10, from: "example.com"}

Logrex.info "New login", [user, login_info.from, login_info.total_logins]

To display this:

INFO 20:56:40 New login               user=Matt from=example.com total_logins=10

Getting Started

To start using Logrex, install it via Hex.

Installation

The latest version of Logrex is available in Hex. Add it to your list of dependencies in your mix.exs file:

def deps do
  [
    {:logrex, "~> 0.5.0"}
  ]
end

Use Logrex

To call Logrex functions in your modules, add use Logrex to the top.

defmodule SomeModule do
  use Logrex

  def some_fun do
    foo = "bar"
    Logrex.info "some message", foo
  end
end

Logrex requires Logger for you.

Logrex Features

There are two features in Logrex that can be used together or separately; generation of metadata and the console formatter.

Metadata Generation

Using metadata fields to capture metrics and other values of interest in log output works really well, but a common pattern arises where variable names and their corresponding keys are duplicated. Take the following example:

%{name: name, login_count: login_count} = user
Logger.info "User login", name: name, login_count: login_count

Logrex exposes macros, matching the Logger macros, which generate the keyword list passed as the metadata parameter to the Logger functions. Both of the examples below will generate the same Logger.info/2 output as the example above.

You can use the matched variables directly:

%{name: name, login_count: login_count} = user
Logrex.info "User login", [name, login_count]

Or you can access the map keys, which will be used for the metadata keys:

Logrex.info "User login", [user.name, user.login_count]

For metadata generation, you must use Logrex at the top of your module, which itself requires Logger.

Note that Elixir syntax rules apply, if you want to mix variables and keyword tuples via shorthand, you have to place them inside brackets and the tuples have to be last. For example, this is valid:

Logrex.info "msg", [a, b, c: 1]

And these aren't:

Logrex.info "msg", a, b

Logrex.info "msg", [c: 1, a, b]

Console Formatter

By default, the Elixir Logger defines a whitelist of metadata fields and requires that any additional fields be explicitly added. The Logrex formatter instead allows for dynamic metadata fields and separates them from the inline log text.

To use the Logrex console formatter, set it as the console formatter in your logger configuration, and set it to passthrough all metadata fields.

config :logger, :console,
  format: {Logrex, :format},
  metadata: :all

That will pass log output to the formatter with its default options:

iex> require Logger
iex> Logger.info "message", foo: 1, bar: 2
INFO 02:31:06 message                                      foo=1 bar=2

Note in the example above that the formatter does not rely on using Logrex's metadata generation, you can use it by itself with Logger.

Additionally, Logrex has its own optional formatting configuration.

Formatter Configuration Options

Config | Default | Description -------| ------- | ----------- auto_inspect | true | the Logrex formatter will automatically call inspect on metadata values which are lists, maps, pids, or tuples metadata_format | empty string | the format for system metadata fields, as described in the Logger docs; system metadata is displayed between the time and the log message meta_level | :debug | the level to log Logrex.meta/1 messages padding | 44 | the minimum character width of the main log message pad_empty_messages | false | the Logrex formatter will not apply padding to empty messages, unless set to 'true' full_level_names | false | display DEBUG and ERROR instead of their four-letter equivalents (DEBG, EROR) show_elixir_prefix | false | remove the Elixir. module prefix when displaying the module name show_date | false | includes the date in the log timestamp

Example Formatter Configuration Setup:

config :logrex,
  metadata_format: "$module $function:$line",
  meta_level: :info,
  padding: 50

Colors

Logrex defers to Logger color settings -- use that configuration to disable or change level colors.

Documentation

Logrex documenation is published at https://hexdocs.pm/logrex.

Running the tests

$ mix test

License

This project is licensed under the MIT License - see the LICENSE.md file for details

Acknowledgments

• Logrus