Conveniences for formatting data for logs.

This module allows developers to specify a {module, function} or a string that serves as template for log messages.

Formatting string

The log messages can be controlled by a formatting string. Here is an example of how to configure the :console backend in a config/config.exs file:

For example:

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

The above will print error messages as:

18:43:12.439 user_id=13 [error] Hello\n

The valid parameters you can use are:

• $time - the time the log message was sent
• $date - the date the log message was sent
• $message - the log message
• $level - the log level
• $node - the node that prints the message
• $metadata - user controlled data presented in "key=val key2=val2 " format

Backends typically allow developers to supply such control strings via configuration files. This module provides compile/1, which compiles the string into a format for fast operations at runtime and format/5 to format the compiled pattern into an actual IO data.

Formatting function

You can also customize the format of your log messages to a {module, function} tuple if you wish to provide your own format function. Here is an example of how to configure the :console backend in a config/config.exs file:

config :logger, :console,
  format: {MyConsoleLogger, :format}

And here is an example of how you can define MyConsoleLogger.format/4 from the above configuration:

defmodule MyConsoleLogger do
  @spec format(atom, term, Logger.Formatter.time(), keyword()) :: IO.chardata()
  def format(level, message, timestamp, metadata) do
    # Custom formatting logic that must return chardata.
    # ...
  end
end

The format/4 function must not fail. If it does, it will bring that particular logger instance down, causing your system to temporarily lose log messages. If necessary, wrap the function in a rescue and log a default message instead:

defmodule MyConsoleLogger do
  def format(level, message, timestamp, metadata) do
    # Custom formatting logic
  rescue
    _ -> "could not format: #{inspect({level, message, metadata})}"
  end
end

The {module, function} will be invoked with four arguments:

• the log level: an atom (atom/0)
• the message: this is usually IO.chardata/0, but in some cases it may contain invalid data. Since the formatting function must never fail, you need to prepare for the message being anything
• the current timestamp: a term of type Logger.Formatter.time/0
• the metadata: a keyword list (keyword/0)

The {module, function} must return a term of type IO.chardata/0.

Metadata

Metadata to be sent to the logger can be read and written with the Logger.metadata/0 and Logger.metadata/1 functions. For example, you can set Logger.metadata([user_id: 13]) to add user_id metadata to the current process. The user can configure the backend to choose which metadata it wants to print and it will replace the $metadata value.