View Source Logger.Formatter (Logger v1.16.0)

Conveniences and built-in formatter for logs.

This modules defines a suitable :logger formatter which formats messages and reports as Elixir terms and also provides additional functionality, such as timezone conversion, truncation, and coloring. This formatter is used by default by Logger and you can configure it using:

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

See Logger.Formatter.new/1 for all configuration options.

You can also build your own instances of this formatter by calling new/1 and setting at the formatter of any :logger handler by settings its :formatter key to Logger.Formatter.new(options).

This module also provides several conveniences for those who wish to write their custom logger formatters.

Formatting

The log messages can be controlled by a formatting string. Here is an example:

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

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

Formatting function

You can also customize the format of your log messages with a {module, function_name} tuple if you wish to change how messages are formatted but keep all other features provided by Logger.Formatter such as truncation and coloring. However, if you want to get full control of formatting, consider writing a custom :logger formatter instead, which has complete access to all events and metadata.

When using a {module, function_name}, the function will be invoked with the level, the message, the timestamp, and metadata, like this:

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

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.

Summary

Types

date()

date_time_ms()

pattern()

time_ms()

Functions

compile(pattern_or_function)

Compiles a pattern or function into a data structure that format/5 can handle.

format(pattern_or_function, level, message, timestamp, metadata)

Formats a pattern_or_function returned by compile/1.

format_date(date_tuple)

Formats date as chardata.

format_event(log_event, truncate)

Formats the message of a log event.

format_time(time_ms_tuple)

Formats time as chardata.

new(options \\ [])

Initializes a formatter for :logger handlers.

prune(binary)

Prunes invalid Unicode code points from lists and invalid UTF-8 bytes.

system_time_to_date_time_ms(system_time, utc_log? \\ false)

Converts the system time (in microseconds) from metadata into a date_time_ms tuple.

truncate(chardata, n)

Truncates a chardata into n bytes.

Types

date()

@type date() :: {1970..10000, 1..12, 1..31}

date_time_ms()

@type date_time_ms() :: {date(), time_ms()}

pattern()

@type pattern() :: :date | :level | :levelpad | :message | :metadata | :node | :time

time_ms()

@type time_ms() :: {0..23, 0..59, 0..59, 0..999}

Functions

compile(pattern_or_function)

@spec compile(binary() | nil) :: [pattern() | binary()]

@spec compile(pattern) :: pattern when pattern: {module(), function :: atom()}

Compiles a pattern or function into a data structure that format/5 can handle.

Check the module doc for documentation on the valid parameters that will be interpolated in the pattern. If you pass nil as the pattern, the pattern defaults to:

"\n$time $metadata[$level] $message\n"

If you want to customize formatting with a custom function, you can pass a {module, function_name} tuple.

This function, alongside format/5, is the main building block used by Logger.Formatter.new/1 for formatting messages. It can also be used by those interested in building custom formatters.

Examples

iex> Logger.Formatter.compile("$time $metadata [$level] $message\n")
[:time, " ", :metadata, " [", :level, "] ", :message, "\n"]

iex> Logger.Formatter.compile({MyLoggerFormatter, :format})
{MyLoggerFormatter, :format}

format(pattern_or_function, level, message, timestamp, metadata)

@spec format(
  mod_and_fun | [pattern() | binary()],
  Logger.level(),
  Logger.message(),
  date_time_ms(),
  keyword()
) :: IO.chardata()
when mod_and_fun: {atom(), atom()}

Formats a pattern_or_function returned by compile/1.

It takes a compiled format and injects the level, timestamp, message, and metadata keyword list and returns a properly formatted string.

If pattern_or_function is a {module, function_name} tuple, then module.function_name(level, message, timestamp, metadata) is invoked to get the message.

This function, alongside compile/1, is the main building block used by Logger.Formatter.new/1 for formatting messages. It can also be used by those interested in building custom formatters.