Logger v1.0.5 Logger

A logger for Elixir applications.

It includes many features:

  • Provides debug, info, warn and error levels.

  • Supports multiple backends which are automatically supervised when plugged into Logger.

  • Formats and truncates messages on the client to avoid clogging logger backends.

  • Alternates between sync and async modes to remain performant when required but also apply back-pressure when under stress.

  • Wraps OTP’s error_logger to prevent it from overflowing.


The supported levels are:

  • :debug - for debug-related messages
  • :info - for information of any kind
  • :warn - for warnings
  • :error - for errors


Logger supports a wide range of configurations.

This configuration is split in three categories:

  • Application configuration - must be set before the logger application is started

  • Runtime configuration - can be set before the logger application is started, but may be changed during runtime

  • Error logger configuration - configuration for the wrapper around OTP’s error_logger

Application configuration

The following configuration must be set via config files before the logger application is started.

  • :backends - the backends to be used. Defaults to [:console]. See the “Backends” section for more information.

  • :compile_time_purge_level - purge all calls that have log level lower than the configured value at compilation time. This means the Logger call will be completely removed at compile time, accruing no overhead at runtime. Defaults to :debug and only applies to the Logger.debug, Logger.info, etc style of calls.

Runtime Configuration

All configuration below can be set via config files but also changed dynamically during runtime via Logger.configure/1.

  • :level - the logging level. Attempting to log any message with severity less than the configured level will simply cause the message to be ignored. Keep in mind that each backend may have its specific level, too.

  • :utc_log - when true, uses UTC in logs. By default it uses local time (i.e. it defaults to false).

  • :truncate - the maximum message size to be logged. Defaults to 8192 bytes. Note this configuration is approximate. Truncated messages will have " (truncated)" at the end.

  • :sync_threshold - if the logger manager has more than sync_threshold messages in its queue, Logger will change to sync mode, to apply back-pressure to the clients. Logger will return to async mode once the number of messages in the queue is reduced to sync_threshold * 0.75 messages. Defaults to 20 messages.

Error logger configuration

The following configuration applies to the Logger wrapper around Erlang’s error_logger. All the configurations below must be set before the logger application starts.

  • :handle_otp_reports - redirects OTP reports to Logger so they are formatted in Elixir terms. This uninstalls Erlang’s logger that prints terms to terminal.

  • :handle_sasl_reports - redirects supervisor, crash and progress reports to Logger so they are formatted in Elixir terms. This uninstalls sasl’s logger that prints these reports to the terminal.

  • :discard_threshold_for_error_logger - a value that, when reached, triggers the error logger to discard messages. This value must be a positive number that represents the maximum number of messages accepted per second. Once above this threshold, the error_logger enters discard mode for the remainder of that second. Defaults to 500 messages.

Furthermore, Logger allows messages sent by Erlang’s error_logger to be translated into an Elixir format via translators. Translators can be dynamically added at any time with the add_translator/1 and remove_translator/1 APIs. Check Logger.Translator for more information.


Logger supports different backends where log messages are written to.

The available backends by default are:

  • :console - Logs messages to the console (enabled by default)

Developers may also implement their own backends, an option that is explored with detail below.

The initial backends are loaded via the :backends configuration, which must be set before the logger application is started.

Console backend

The console backend logs message to the console. It supports the following options:

  • :level - the level to be logged by this backend. Note that messages are first filtered by the general :level configuration in :logger

  • :format - the format message used to print logs. Defaults to: "$time $metadata[$level] $levelpad$message\n"

  • :metadata - the metadata to be printed by $metadata. Defaults to an empty list (no metadata)

  • :colors - a keyword list of coloring options.

The supported keys in the :colors keyword list are:

  • :enabled - boolean value that allows for switching the coloring on and off. Defaults to: IO.ANSI.enabled?

  • :debug - color for debug messages. Defaults to: :cyan

  • :info - color for info messages. Defaults to: :normal

  • :warn - color for warn messages. Defaults to: :yellow

  • :error - color for error messages. Defaults to: :red

See the IO.ANSI module for a list of colors and attributes.

Here is an example of how to configure the :console backend in a config/config.exs file:

config :logger, :console,
  format: "\n$date $time [$level] $metadata$message",
  metadata: [:user_id]

You can read more about formatting in Logger.Formatter.

Custom backends

Any developer can create their own backend for Logger. Since Logger is an event manager powered by GenEvent, writing a new backend is a matter of creating an event handler, as described in the GenEvent module.

From now on, we will be using the term “event handler” to refer to your custom backend, as we head into implementation details.

Once Logger starts, it installs all event handlers under the :backends configuration into the Logger event manager. The event manager and all added event handlers are automatically supervised by Logger.

Once initialized, the handler should be designed to handle events in the following format:

{level, group_leader,
  {Logger, message, timestamp, metadata}}

The level is one of :error, :info, :warn or :error, as previously described, the group leader is the group leader of the process who logged the message, followed by a tuple starting with the atom Logger, the message as iodata, the timestamp and a keyword list of metadata.

It is recommended that handlers ignore messages where the group leader is in a different node than the one the handler is installed.

Furthermore, backends can be configured via the configure_backend/2 function which requires event handlers to handle calls of the following format:

{:configure, options}

where options is a keyword list. The result of the call is the result returned by configure_backend/2. The recommended return value for successful configuration is :ok.

It is recommended that backends support at least the following configuration values:

  • level - the logging level for that backend
  • format - the logging format for that backend
  • metadata - the metadata to include the backend

Check the implementation for Logger.Backends.Console for examples on how to handle the recommendations in this section and how to process the existing options.



Adds a new translator

Compare log levels

Configures the logger

Configures the given backend

Disables logging for the current process

Enables logging for the current process

Flushes the Logger

Retrieves the logger level

Reads the current process metadata

Adds the given keyword list to the current process metadata

Removes a translator


level :: :error | :info | :warn | :debug


add_backend(backend, opts \\ [])

Adds a new backend.


  • :flush - when true, guarantees all messages currently sent to both Logger and Erlang’s error_logger are processed before the backend is added

Adds a new translator.

compare_levels(level, level)


compare_levels(level, level) :: :lt | :eq | :gt

Compare log levels.

Receives two log levels and compares the left against right and returns :lt, :eq or :gt.


Configures the logger.

See the “Runtime Configuration” section in Logger module documentation for the available options.

configure_backend(backend, options)


configure_backend(backend, Keyword.t) :: term

Configures the given backend.

The backends needs to be started and running in order to be configured at runtime.


Disables logging for the current process.

Currently the only accepted process is self().


Enables logging for the current process.

Currently the only accepted process is self().



flush :: :ok

Flushes the Logger.

This basically guarantees all messages sent to the Logger prior to this call will be processed. This is useful for testing and it should not be called in production code.



Retrieves the logger level.

The logger level can be changed via configure/1.

log(level, chardata, metadata \\ [])


log(level, message | (() -> message), Keyword.t) ::
  :ok |
  {:error, :noproc} |
  {:error, term}

Logs a message.

Developers should use the macros Logger.debug/2, Logger.warn/2, Logger.info/2 or Logger.error/2 instead of this function as they automatically include caller metadata and can eliminate the Logger call altogether at compile time if desired.

Use this function only when there is a need to log dynamically or you want to explicitly avoid embedding metadata.


Reads the current process metadata.


Adds the given keyword list to the current process metadata.

remove_backend(backend, opts \\ [])

Removes a backend.


  • :flush - when true, guarantees all messages currently sent to both Logger and Erlang’s error_logger are processed before the backend is removed

Removes a translator.


debug(chardata, metadata \\ [])

Logs a debug message.


Logger.debug "hello?"
Logger.debug fn -> "expensive to calculate debug" end
error(chardata, metadata \\ [])

Logs an error.


Logger.error "oops"
Logger.error fn -> "expensive to calculate error" end
info(chardata, metadata \\ [])

Logs some info.


Logger.info "mission accomplished"
Logger.info fn -> "expensive to calculate info" end
warn(chardata, metadata \\ [])

Logs a warning.


Logger.warn "knob turned too far to the right"
Logger.warn fn -> "expensive to calculate warning" end