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 backpressure when under stress.
Integrates with Erlang's
:logger
to convert terms to Elixir syntax.
Logging is useful for tracking when an event of interest happens in your system. For example, it may be helpful to log whenever a user is deleted.
def delete_user(user) do Logger.info("Deleting user from the system: #{inspect(user)}") # ... end
The Logger.info/2
macro emits the provided message at the :info
level. Note the arguments given to info/2
will only be evaluated if a message is logged. For instance, if the Logger level is set to :warning
, :info
messages are never logged and therefore the arguments given above won't even be executed.
There are additional macros for other levels.
Logger also allows log commands to be removed altogether via the :compile_time_purge_matching
option (see below).
For dynamically logging messages, see bare_log/3
. But note that bare_log/3
always evaluates its arguments (unless the argument is an anonymous function).
Levels
The supported levels, ordered by importance, are:
-
:emergency
- when system is unusable, panics -
:alert
- for alerts, actions that must be taken immediately, ex. corrupted database -
:critical
- for critical conditions -
:error
- for errors -
:warning
- for warnings -
:notice
- for normal, but significant, messages -
:info
- for information of any kind -
:debug
- for debug-related messages
For example, :info
takes precedence over :debug
. If your log level is set to :info
, then all :info
, :notice
and above will be passed to backends. If your log level is set to :alert
, only :alert
and :emergency
will be printed.
Metadata
Whenever a message is logged, additional information can be given via metadata. Each log operation, such as Logger.info/2
, allows metadata to be given as argument.
Furthermore, metadata can be set per process with Logger.metadata/1
.
Some metadata, however, is always added automatically by Logger whenever possible. Those are:
:application
- the current application:mfa
- the current module, function and arity:file
- the current file:line
- the current line:pid
- the current process identifier:initial_call
- the initial call that started the process:registered_name
- the process registered name as an atom:domain
- a list of domains for the logged message. For example, all Elixir reports default to[:elixir]
. Erlang reports may start with[:otp]
or[:sasl]
:crash_reason
- a two-element tuple with the throw/error/exit reason as first argument and the stacktrace as second. A throw will always be{:nocatch, term}
. An error is always anException
struct. All other entries are exits. The console backend ignores this metadata by default but it can be useful to other backends, such as the ones that report errors to third-party services
Note that all metadata is optional and may not always be available. The :mfa
, :file
, :line
, and similar metadata are automatically included when using Logger
macros. Logger.bare_log/3
does not include any metadata beyond the :pid
by default. Other metadata, such as :crash_reason
, :initial_call
, and :registered_name
are available only inside behaviours such as GenServer, Supervisor, and others.
For example, you might wish to include a custom :error_code
metadata in your logs:
Logger.error("We have a problem", [error_code: :pc_load_letter])
In your app's logger configuration, you would need to include the :error_code
key and you would need to include $metadata
as part of your log format template:
config :logger, :console, format: "[$level] $message $metadata\n", metadata: [:error_code, :file]
Your logs might then receive lines like this:
[error] We have a problem error_code=pc_load_letter file=lib/app.ex
Configuration
Logger
supports a wide range of configurations.
This configuration is split in three categories:
Application configuration - must be set before the
:logger
application is startedRuntime configuration - can be set before the
:logger
application is started, but may be changed during runtimeErlang configuration - options that handle integration with Erlang's logging facilities
Application configuration
The following configuration must be set via config files (such as config/config.exs
) before the :logger
application is started.
:backends
- the backends to be used. Defaults to[:console]
. See the "Backends" section for more information.:compile_time_application
- sets the:application
metadata value to the configured value at compilation time. This configuration is automatically set by Mix and made available as metadata when logging.-
:compile_time_purge_matching
- purges at compilation time all calls that match the given conditions. This means thatLogger
calls with level lower than this option will be completely removed at compile time, accruing no overhead at runtime. This configuration expects a list of keyword lists. Each keyword list contains a metadata key and the matching value that should be purged. Some special keys are supported:-
:level_lower_than
- purges all messages with a lower logger level -
:module
- purges all messages with the matching module -
:function
- purges all messages with the "function/arity" Remember that if you want to purge log calls from a dependency, the dependency must be recompiled.
-
:start_options
- passes start options to Logger's main process, such as:spawn_opt
and:hibernate_after
. All options inGenServer.option/0
are accepted, except:name
.
For example, to configure the :backends
and purge all calls that happen at compile time with level lower than :info
in a config/config.exs
file:
config :logger, backends: [:console], compile_time_purge_matching: [ [level_lower_than: :info] ]
If you want to purge all log calls from an application named :foo
and only keep errors from Bar.foo/3
, you can set up two different matches:
config :logger, compile_time_purge_matching: [ [application: :foo], [module: Bar, function: "foo/3", level_lower_than: :error] ]
Runtime Configuration
All configuration below can be set via config files (such as config/config.exs
) 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. In addition to levels mentioned above it also support 2 "meta-levels":-
:all
- all messages will be logged, conceptually identical to:debug
-
:none
- no messages will be logged at all
-
:utc_log
- whentrue
, uses UTC in logs. By default it uses local time (i.e., it defaults tofalse
).:truncate
- the maximum message size to be logged (in bytes). Defaults to 8192 bytes. Note this configuration is approximate. Truncated messages will have" (truncated)"
at the end. The atom:infinity
can be passed to disable this behavior.:sync_threshold
- if theLogger
manager has more than:sync_threshold
messages in its queue,Logger
will change to sync mode, to apply backpressure to the clients.Logger
will return to async mode once the number of messages in the queue is reduced to one below thesync_threshold
. Defaults to 20 messages.:sync_threshold
can be set to0
to force sync mode.:discard_threshold
- if theLogger
manager has more than:discard_threshold
messages in its queue,Logger
will change to discard mode and messages will be discarded directly in the clients.Logger
will return to sync mode once the number of messages in the queue is reduced to one below thediscard_threshold
. Defaults to 500 messages.:discard_threshold_periodic_check
- a periodic check that checks and reports if logger is discarding messages. It logs a warning message whenever the system is (or continues) in discard mode and it logs a warning message whenever if the system was discarding messages but stopped doing so after the previous check. By default it runs every30_000
milliseconds.:translator_inspect_opts
- when translating OTP reports and errors, the last message and state must be inspected in the error reports. This configuration allow developers to change how much and how the data should be inspected.
For example, to configure the :level
and :truncate
options in a config/config.exs
file:
config :logger, level: :warning, truncate: 4096
Erlang/OTP integration
From Elixir v1.10, Elixir's Logger is fully integrated with Erlang's logger. They share the same Logger.level/0
, any metadata set with Logger.metadata/1
applies to both, and so on.
Elixir also supports formatting Erlang reports using Elixir syntax. This can be controlled with two configurations:
:handle_otp_reports
- redirects OTP reports toLogger
so they are formatted in Elixir terms. This effectively disables Erlang standard logger. Defaults totrue
.:handle_sasl_reports
- redirects supervisor, crash and progress reports toLogger
so they are formatted in Elixir terms. Your application must guarantee:sasl
is started before:logger
. This means you may see some initial reports written in Erlang syntax until the Logger application kicks in. Defaults tofalse
. This option only has an effect if:handle_otp_reports
is true.
For example, to configure Logger
to redirect all Erlang messages using a config/config.exs
file:
config :logger, handle_otp_reports: true, handle_sasl_reports: true
Furthermore, Logger
allows messages sent by Erlang to be translated into an Elixir format via translators. Translators can be added at any time with the add_translator/1
and remove_translator/1
APIs. Check Logger.Translator
for more information.
Backends
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).:console
is simply a shortcut forLogger.Backends.Console
.
Developers may also implement their own backends, an option that is explored in more detail below.
The initial backends are loaded via the :backends
configuration, which must be set before the :logger
application is started. However, it preferred to add and remove backends via add_backend/2
and remove_backend/2
functions. This is often done in your Application.start/2
callback:
@impl true def start(_type, _args) do Logger.add_backend(MyCustomBackend)
The backend can be configured either on the add_backend/2
call:
@impl true def start(_type, _args) do Logger.add_backend(MyCustomBackend, some_config: ...)
Or in your config files:
config :logger, MyCustomBackend, some_config: ...
Elixir custom backends
Any developer can create their own Logger
backend. Since Logger
is an event manager powered by :gen_event
, writing a new backend is a matter of creating an event handler, as described in the :gen_event
documentation.
From now on, we will be using the term "event handler" to refer to your custom backend, as we head into implementation details.
Once the :logger
application starts, it installs all event handlers listed under the :backends
configuration into the Logger
event manager. The event manager and all added event handlers are automatically supervised by Logger
.
Note that if a backend fails to start by returning {:error, :ignore}
from its init/1
callback, then it's not added to the backends but nothing fails. If a backend fails to start by returning {:error, reason}
from its init/1
callback, the :logger
application will fail to start.
Once initialized, the handler should be designed to handle the following events:
-
{level, group_leader, {Logger, message, timestamp, metadata}}
where:-
level
is one of:debug
,:info
,:warn
, or:error
, as previously described (for compatibility with pre 1.10 backends the:notice
will be translated to:info
and all messages above:error
will be translated to:error
) -
group_leader
is the group leader of the process which logged the message -
{Logger, message, timestamp, metadata}
is a tuple containing information about the logged message:- the first element is always the atom
Logger
-
message
is the actual message (as chardata) -
timestamp
is the timestamp for when the message was logged, as a{{year, month, day}, {hour, minute, second, millisecond}}
tuple -
metadata
is a keyword list of metadata used when logging the message
- the first element is always the atom
-
:flush
It is recommended that handlers ignore messages where the group leader is in a different node than the one where the handler is installed. For example:
def handle_event({_level, gl, {Logger, _, _, _}}, state) when node(gl) != node() do {:ok, state} end
In the case of the event :flush
handlers should flush any pending data. This event is triggered by Logger.flush/0
.
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
. For example:
def handle_call({:configure, options}, state) do new_state = reconfigure_state(state, options) {:ok, :ok, new_state} end
It is recommended that backends support at least the following configuration options:
-
:level
- the logging level for that backend -
:format
- the logging format for that backend -
:metadata
- the metadata to include in that backend
Check the Logger.Backends.Console
implementation in Elixir's codebase for examples on how to handle the recommendations in this section and how to process the existing options.
Erlang/OTP handlers
While Elixir Logger provides backends, Erlang/OTP logger provides handlers. They represent the same concept: the ability to integrate into the logging system to handle each logged message/event.
However, implementation-wise, they have the following differences:
Elixir backends run in a separate process which comes with overload protection. However, because this process is a single GenEvent, any long running action should be avoided, as it can lead to bottlenecks in the system
Erlang handlers run in the same process as the process logging the message/event. This gives developers more flexibility but they should avoid performing any long running action in such handlers, as it may slow down the action being executed considerably. At the moment, there is no built-in overload protection for Erlang handlers, so it is your responsibility to implement it
The good news is that developers can use third-party implementations of both Elixir backends and Erlang handlers. We have already covered Elixir backends, so let's see how to add Erlang/OTP handlers.
Erlang/OTP handlers must be listed under your own application:
config :my_app, :logger, [ {:handler, :name_of_the_handler, ACustomHandler, configuration = %{}} ]
And then, explicitly attached in your Application.start/2
callback:
:logger.add_handlers(:my_app)
Note we do not recommend configuring Erlang/OTP's logger directly under the :kernel
application in your config/config.exs
, like this:
# Not recommended: config :kernel, :logger, ...
This is because by the time Elixir starts, Erlang's kernel has already been started, which means the configuration above would have no effect.
Summary
Types
Functions
- add_backend(backend, opts \\ [])
Adds a new backend.
- add_translator(translator)
Adds a new translator.
- alert(message_or_fun, metadata \\ [])
Logs a alert message.
- bare_log(level, message_or_fun, metadata \\ [])
Logs a message dynamically.
- compare_levels(left, right)
Compares log levels.
- configure(options)
Configures the logger.
- configure_backend(backend, options)
Configures the given backend.
- critical(message_or_fun, metadata \\ [])
Logs a critical message.
- debug(message_or_fun, metadata \\ [])
Logs a debug message.
- delete_all_module_levels()
Deletes logging level for all modules to primary level
- delete_module_level(module)
Deletes logging level for given module to primary level.
- disable(pid)
Disables logging for the current process.
- emergency(message_or_fun, metadata \\ [])
Logs a emergency message.
- enable(pid)
Enables logging for the current process.
- enabled?(pid)
Returns whether the logging is enabled for given process.
- error(message_or_fun, metadata \\ [])
Logs a error message.
- flush()
Flushes the logger.
- get_module_level(mod)
Gets logging level for given module.
- info(message_or_fun, metadata \\ [])
Logs a info message.
- log(level, message_or_fun, metadata \\ [])
Logs a message with the given
level
.- metadata()
Reads the current process metadata.
- metadata(keyword)
Alters the current process metadata according the given keyword list.
- notice(message_or_fun, metadata \\ [])
Logs a notice message.
- put_module_level(mod, level)
Puts logging level for given module.
- remove_backend(backend, opts \\ [])
Removes a backend.
- remove_translator(translator)
Removes a translator.
- reset_metadata(keyword \\ [])
Resets the current process metadata to the given keyword list.
- warn(message_or_fun, metadata \\ [])
Logs a warning message.
- warning(message_or_fun, metadata \\ [])
Logs a warning message.
Types
backend()Source
Specs
backend() :: :gen_event.handler()
level()Source
Specs
level() :: :emergency | :alert | :critical | :error | :warning | :warn | :notice | :info | :debug
message()Source
Specs
message() :: :unicode.chardata() | String.Chars.t() | report()
metadata()Source
Specs
metadata() :: keyword()
report()Source
Specs
report() :: map() | keyword()
Functions
add_backend(backend, opts \\ [])Source
Specs
add_backend(backend(), keyword()) :: Supervisor.on_start_child()
Adds a new backend.
Adding a backend calls the init/1
function in that backend with the name of the backend as its argument. For example, calling
Logger.add_backend(MyBackend)
will call MyBackend.init(MyBackend)
to initialize the new backend. If the backend's init/1
callback returns {:ok, _}
, then this function returns {:ok, pid}
. If the handler returns {:error, :ignore}
from init/1
, this function still returns {:ok, pid}
but the handler is not started. If the handler returns {:error, reason}
from init/1
, this function returns {:error, {reason, info}}
where info
is more information on the backend that failed to start.
Backends added by this function are not persisted. Therefore if the Logger application or supervision tree is restarted, the backend won't be available. If you need this guarantee, then configure the backend via the application environment:
config :logger, :backends, [MyBackend]
Options
-
:flush
- whentrue
, guarantees all messages currently sent toLogger
are processed before the backend is added
Examples
{:ok, _pid} = Logger.add_backend(MyBackend, flush: true)
add_translator(translator)Source
Specs
add_translator({module(), function :: atom()}) :: :ok
Adds a new translator.
alert(message_or_fun, metadata \\ [])Source
Logs a alert message.
Returns :ok
.
This is reported as "error" in Elixir's logger backends for backwards compatibility reasons.
Examples
Logging a message (string or iodata):
Logger.alert("this is a alert message")
Report message (maps or keywords):
# as keyword list Logger.alert([something: :reported, this: :alert]) # as map Logger.alert(%{something: :reported, this: :alert})
bare_log(level, message_or_fun, metadata \\ [])Source
Specs
bare_log( level(), message() | (() -> message() | {message(), keyword()}), keyword() ) :: :ok
Logs a message dynamically.
Opposite to log/3
, debug/2
, info/2
, and friends, the arguments given to bare_log/3
are always evaluated. However, you can pass anonymous functions to bare_log/3
and they will only be evaluated if there is something to be logged.
compare_levels(left, right)Source
Specs
compare_levels(level(), level()) :: :lt | :eq | :gt
Compares log levels.
Receives two log levels and compares the left
level against the right
level and returns:
-
:lt
ifleft
is less thanright
-
:eq
ifleft
andright
are equal -
:gt
ifleft
is greater thanright
Examples
iex> Logger.compare_levels(:debug, :warning) :lt iex> Logger.compare_levels(:error, :info) :gt
configure(options)Source
Specs
configure(keyword()) :: :ok
Configures the logger.
See the "Runtime Configuration" section in the Logger
module documentation for the available options. The changes done here are automatically persisted to the :logger
application environment.
configure_backend(backend, options)Source
Specs
configure_backend(backend(), keyword()) :: term()
Configures the given backend.
The backend needs to be started and running in order to be configured at runtime.
critical(message_or_fun, metadata \\ [])Source
Logs a critical message.
Returns :ok
.
This is reported as "error" in Elixir's logger backends for backwards compatibility reasons.
Examples
Logging a message (string or iodata):
Logger.critical("this is a critical message")
Report message (maps or keywords):
# as keyword list Logger.critical([something: :reported, this: :critical]) # as map Logger.critical(%{something: :reported, this: :critical})
debug(message_or_fun, metadata \\ [])Source
Logs a debug message.
Returns :ok
.
Examples
Logging a message (string or iodata):
Logger.debug("this is a debug message")
Report message (maps or keywords):
# as keyword list Logger.debug([something: :reported, this: :debug]) # as map Logger.debug(%{something: :reported, this: :debug})
delete_all_module_levels()Source
Specs
delete_all_module_levels() :: :ok
Deletes logging level for all modules to primary level
delete_module_level(module)Source
Specs
delete_module_level(module() | [module()]) :: :ok
Deletes logging level for given module to primary level.
disable(pid)Source
Specs
disable(pid()) :: :ok
Disables logging for the current process.
Currently the only accepted PID is self()
.
emergency(message_or_fun, metadata \\ [])Source
Logs a emergency message.
Returns :ok
.
This is reported as "error" in Elixir's logger backends for backwards compatibility reasons.
Examples
Logging a message (string or iodata):
Logger.emergency("this is a emergency message")
Report message (maps or keywords):
# as keyword list Logger.emergency([something: :reported, this: :emergency]) # as map Logger.emergency(%{something: :reported, this: :emergency})
enable(pid)Source
Specs
enable(pid()) :: :ok
Enables logging for the current process.
Currently the only accepted PID is self()
.
enabled?(pid)Source
Specs
enabled?(pid()) :: boolean()
Returns whether the logging is enabled for given process.
Currently the only accepted PID is self()
.
error(message_or_fun, metadata \\ [])Source
Logs a error message.
Returns :ok
.
Examples
Logging a message (string or iodata):
Logger.error("this is a error message")
Report message (maps or keywords):
# as keyword list Logger.error([something: :reported, this: :error]) # as map Logger.error(%{something: :reported, this: :error})
flush()Source
Specs
flush() :: :ok
Flushes the logger.
This guarantees all messages sent to Logger
prior to this call will be processed. This is useful for testing and it should not be called in production code.
get_module_level(mod)Source
Specs
get_module_level(module() | [module()]) :: [{module(), level() | :all | :none}]
Gets logging level for given module.
Returned value will be the effective value used. If no value was set for given module, then it will not be present in the returned list.
info(message_or_fun, metadata \\ [])Source
Logs a info message.
Returns :ok
.
Examples
Logging a message (string or iodata):
Logger.info("this is a info message")
Report message (maps or keywords):
# as keyword list Logger.info([something: :reported, this: :info]) # as map Logger.info(%{something: :reported, this: :info})
level()Source
Specs
level() :: level()
Retrieves the Logger
level.
The Logger
level can be changed via configure/1
.
log(level, message_or_fun, metadata \\ [])Source
Logs a message with the given level
.
Returns :ok
.
The macros debug/2
, info/2
, notice/2
, warning/2
, error/2
, critical/2
, alert/2
, and emergency/2
are preferred over this macro as they can automatically eliminate the call to Logger
altogether at compile time if desired (see the documentation for the Logger
module).
metadata()Source
Specs
metadata() :: metadata()
Reads the current process metadata.
metadata(keyword)Source
Specs
metadata(metadata()) :: :ok
Alters the current process metadata according the given keyword list.
This function will merge the given keyword list into the existing metadata, with the exception of setting a key to nil
, which will remove that key from the metadata.
notice(message_or_fun, metadata \\ [])Source
Logs a notice message.
Returns :ok
.
This is reported as "info" in Elixir's logger backends for backwards compatibility reasons.
Examples
Logging a message (string or iodata):
Logger.notice("this is a notice message")
Report message (maps or keywords):
# as keyword list Logger.notice([something: :reported, this: :notice]) # as map Logger.notice(%{something: :reported, this: :notice})
put_module_level(mod, level)Source
Specs
put_module_level(module(), level() | :all | :none) :: :ok | {:error, term()}
Puts logging level for given module.
This will take priority over the primary level set, so it can be used to increase or decrease verbosity of some parts of the project.
Example
defmodule Foo do require Logger def log, do: Logger.debug("foo") end Logger.configure(level: :error) Logger.put_module_level(Foo, :all) Foo.log() # This will print the message even if global level is :error
remove_backend(backend, opts \\ [])Source
Specs
remove_backend(backend(), keyword()) :: :ok | {:error, term()}
Removes a backend.
Options
-
:flush
- whentrue
, guarantees all messages currently sent toLogger
are processed before the backend is removed
remove_translator(translator)Source
Specs
remove_translator({module(), function :: atom()}) :: :ok
Removes a translator.
reset_metadata(keyword \\ [])Source
Specs
reset_metadata(metadata()) :: :ok
Resets the current process metadata to the given keyword list.
warn(message_or_fun, metadata \\ [])Source
Logs a warning message.
Returns :ok
.
This macro is deprecated in favour of warning/2
.
Examples
Logger.warn("knob turned too far to the right")
warning(message_or_fun, metadata \\ [])Source
Logs a warning message.
Returns :ok
.
This is reported as "warn" in Elixir's logger backends for backwards compatibility reasons.
Examples
Logging a message (string or iodata):
Logger.warning("this is a warning message")
Report message (maps or keywords):
# as keyword list Logger.warning([something: :reported, this: :warning]) # as map Logger.warning(%{something: :reported, this: :warning})
© 2012 Plataformatec
Licensed under the Apache License, Version 2.0.
https://hexdocs.pm/logger/1.12.0/Logger.html