# Logger v1.10.3 Logger.Formatter View Source

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\n

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
- `$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

## Types

pattern()
time()

## Functions

compile(pattern)

Compiles a format string into a data structure that `format/5` can handle.

format(config, level, msg, timestamp, metadata)

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

format_date(arg)

Formats date as chardata.

format_time(arg)

Formats time as chardata.

prune(binary)

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

# Link to this section Types

Link to this type

# pattern()

View Source

## Specs

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

Link to this type

# time()

View Source

## Specs

    time() :: {{1970..10000, 1..12, 1..31}, {0..23, 0..59, 0..59, 0..999}}

# Link to this section Functions

Link to this function

# compile(pattern)

View Source

## Specs

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

    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}

Link to this function

# format(config, level, msg, timestamp, metadata)

View Source

## Specs

    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"

Link to this function

# format_date(arg)

View Source

## Specs

    format_date({1970..10000, 1..12, 1..31}) :: IO.chardata()

Formats date as chardata.

Link to this function

# format_time(arg)

View Source

## Specs

    format_time({0..23, 0..59, 0..59, 0..999}) :: IO.chardata()

Formats time as chardata.

Link to this function

# prune(binary)

View Source

## Specs

    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.