View Source Logger.Formatter (Logger v1.19.0-dev)

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]

You can also use Logger.Formatter.new/1 to create your own formatter, which can then be passed as a formatter to any :logger_handler. See Logger.Formatter.new/1 for all configuration 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.

When is user metadata printed?

The default Logger formatter requires the user's metadata to meet one of the following conditions to be printed:

Be a string (is_binary/1)
Be a number (either is_integer/1 or is_float/1)
Be a PID
Be an atom
Be a reference
Be a port
Implement the String.Chars protocol (except for charlists)

If none of the conditions above are true, the given metadata get discarded.

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.