View Source Logger.Formatter (Logger v1.13.4)
Conveniences for formatting data for logs.
This module allows developers to specify a string that serves as template for log messages, for example:
$time $metadata[$level] $message\nWill print error messages as:
18:43:12.439 user_id=13 [error] Hello\nThe 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$levelpad- sets to a single space if level is 4 characters long, otherwise set to the empty space. Used to align the message after level.
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.
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.
Link to this section Summary
Functions
Compiles a format string into a data structure that format/5 can handle.
Takes a compiled format and injects the level, timestamp, message, and metadata keyword list and returns a properly formatted string.
Formats date as chardata.
Formats time as chardata.
Prunes invalid Unicode code points from lists and invalid UTF-8 bytes.
Link to this section Types
@type pattern() :: :date | :level | :levelpad | :message | :metadata | :node | :time
@type time() :: {{1970..10000, 1..12, 1..31}, {0..23, 0..59, 0..59, 0..999}}
Link to this section Functions
@spec compile(binary() | nil) :: [pattern() | binary()]
@spec compile(pattern) :: pattern when pattern: {module(), function :: atom()}
Compiles a format string 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] $levelpad$message\n"If you want to customize formatting through a custom formatter, you can
pass a {module, function} tuple as the pattern.
iex> Logger.Formatter.compile("$time $metadata [$level] $message\n")
[:time, " ", :metadata, " [", :level, "] ", :message, "\n"]
iex> Logger.Formatter.compile({MyLoggerFormatter, :format})
{MyLoggerFormatter, :format}@spec format( {atom(), atom()} | [pattern() | binary()], Logger.level(), Logger.message(), time(), keyword() ) :: IO.chardata()
Takes a compiled format and injects the level, timestamp, message, and metadata keyword list and returns a properly formatted string.
Examples
iex> pattern = Logger.Formatter.compile("[$level] $message")
iex> timestamp = {{1977, 01, 28}, {13, 29, 00, 000}}
iex> formatted = Logger.Formatter.format(pattern, :info, "hello", timestamp, [])
iex> IO.chardata_to_string(formatted)
"[info] hello"@spec format_date({1970..10000, 1..12, 1..31}) :: IO.chardata()
Formats date as chardata.
@spec format_time({0..23, 0..59, 0..59, 0..999}) :: IO.chardata()
Formats time as chardata.
@spec prune(IO.chardata()) :: IO.chardata()
Prunes invalid Unicode code points from lists and invalid UTF-8 bytes.
Typically called after formatting when the data cannot be printed.