lager/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

#+BEGIN_EXAMPLE
  {parse_transform, lager_transform}
#+END_EXAMPLE

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

#+BEGIN_EXAMPLE
  -compile([{parse_transform, lager_transform}]).
#+END_EXAMPLE

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

#+BEGIN_EXAMPLE
  lager:error("Some message")
#+END_EXAMPLE

  Or:

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

  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):

#+BEGIN_EXAMPLE
  {lager,
    {handlers, [
      {lager_console_backend, [info]},
      {lager_file_backend, [{"error.log", error}, {"console.log", info}]}
    ]}
  }.
#+END_EXAMPLE

  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:

#+BEGIN_EXAMPLE
  lager:set_loglevel(lager_console_backend, debug).
#+END_EXAMPLE

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

#+BEGIN_EXAMPLE
  lager:set_loglevel(lager_file_backend, "console.log" debug).
#+END_EXAMPLE

  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.