Skip to content
This repository

A logging framework for Erlang/OTP

Fetching latest commit…

Cannot retrieve the latest commit at this time

README.org

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 and file. More are planned.

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 wish 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, 10485760, "$D0", 5},
      {"console.log", info, 10485760, "$D0", 5}
    ]}
  ]}
]}.

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.

Messages in the crash log are subject to a maximum message size which can be specified via the crash_log_msg_size application variable.

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 minimum threshold was above that takes less than half a second.

Internal log rotation

Lager can rotate its own logs or have it done via an external process. To use internal rotation, use the last 3 values in the file backend’s configuration tuple. For example

{"error.log", error, 10485760, "$D0", 5}

This tells lager to log error and above messages to “error.log” and to rotate the file at midnight or when it reaches 10mb, whichever comes first and to keep 5 rotated logs, in addition to the current one. Setting the count to 0 does not disable rotation, it instead rotates the file and keeps no previous versions around. To disable rotation set the size to 0 and the date to “”.

The “$D0” syntax is taken from the syntax newsyslog uses in newsyslog.conf. The relevant extract follows:

Day, week and month time format: The lead-in character
for day, week and month specification is a `$'-sign.
The particular format of day, week and month
specification is: [Dhh], [Ww[Dhh]] and [Mdd[Dhh]],
respectively.  Optional time fields default to
midnight.  The ranges for day and hour specifications
are:

  hh      hours, range 0 ... 23
  w       day of week, range 0 ... 6, 0 = Sunday
  dd      day of month, range 1 ... 31, or the
          letter L or l to specify the last day of
          the month.

Some examples:
  $D0     rotate every night at midnight
  $D23    rotate every day at 23:00 hr
  $W0D23  rotate every week on Sunday at 23:00 hr
  $W5D16  rotate every week on Friday at 16:00 hr
  $M1D0   rotate on the first day of every month at
          midnight (i.e., the start of the day)
  $M5D6   rotate on every 5th day of the month at
          6:00 hr

To configure the crash log rotation, the following application variables are used:

  • crash_log_size
  • crash_log_date
  • crash_log_count

See the .app.src file for further details.

Syslog Support

Lager syslog output is provided as a seperate application; lager_syslog. It is packaged as a separate application so Lager itself doesn’t have an indirect dependancy on a port driver. Please see the lager_syslog README for configuration information.

Something went wrong with that request. Please try again.