• Overview
• Usage
• Configuration
• Error logger integration
• Runtime loglevel changes

Overview

Lager (as in the beer) is a logging framework for Erlang. Its purpose is to provide a more traditional way to perform logging in an erlang application that plays nicely with traditional UNIX logging tools like logrotate and syslog.

Features

• Finer grained log levels (debug, info, notice, warning, error, critical, alert, emergency)

• Logger calls are transformed using a parse transform to allow capturing Module/Function/Line/Pid information

• When no handler is consuming a log level (eg. debug) no event is even sent to the log handler

• Supports multiple backends, including console, file and syslog.

Usage

To use lager in your application, you need to define it as a rebar dep or have some other way of including it in erlang's path. You can then add the following option to the erlang compiler flags

  {parse_transform, lager_transform}

Alternately, you can add it to the module you which to compile with logging enabled:

  -compile([{parse_transform, lager_transform}]).

Once you have built your code with lager, you can then generate log messages by doing the following:

  lager:error("Some message")

Or:

  lager:warning("Some message with a term: ~p", [Term])

The general form is lager:Severity() where Severity is one of the log levels mentioned above.

Configuration

To configure lager's backends, you use an application variable (probably in your app.config):

  {lager,
    {handlers, [
      {lager_console_backend, [info]},
      {lager_file_backend, [{"error.log", error}, {"console.log", info}]}
    ]}
  }.

The available configuration options for each backend are listed in their module's documentation.

Error logger integration

Lager is also supplied with a error_logger handler module that translates traditional erlang error messages into a friendlier format and sends them into lager itself to be treated like a regular lager log call. To disable this, set the lager application variable `error_logger_redirect' to `false'.

The error_logger handler will also log more complete error messages (protected with use of trunc_io) to a "crash log" which can be referred to for further information. The location of the crash log can be specified by the crash_log application variable. If undefined it is not written at all.

Runtime loglevel changes

You can change the log level of any lager backend at runtime by doing the following:

  lager:set_loglevel(lager_console_backend, debug).

Or, for the backend with multiple handles (files, mainly):

  lager:set_loglevel(lager_file_backend, "console.log" debug).

Lager keeps track of the minium log level being used by any backend and supresses generation of messages lower than that level. This means that debug log messages, when no backend is consuming debug messages, are effectively free. A simple benchmark of doing 1 million debug log messages while the the minimum threshold was above that takes less than half a second.