查看源代码 Logger.Formatter (Logger v1.16.2)

日志的便利功能和内置格式化程序。

此模块定义了一个合适的 :logger 格式化程序，它将消息和报告格式化为 Elixir 项，并提供其他功能，例如时区转换、截断和着色。此格式化程序是 Logger 的默认格式化程序，您可以使用以下方法配置它：

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

有关所有配置选项，请参阅 Logger.Formatter.new/1。

您还可以通过调用 new/1 并设置任何 :logger 处理程序的格式化程序来构建此格式化程序的实例，方法是将其 :formatter 键设置为 Logger.Formatter.new(options)。

此模块还为希望编写自定义日志格式化程序的人提供了几个便利功能。

格式化

日志消息可以通过格式化字符串控制。以下是一个例子：

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

以上将打印错误消息为：

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

您可以使用的有效参数是

$time - 发送日志消息的时间
$date - 发送日志消息的日期
$message - 日志消息
$level - 日志级别
$node - 打印消息的节点
$metadata - 以 "key=val key2=val2 " 格式呈现的用户控制数据

格式化函数

如果您希望更改消息的格式但保留 Logger.Formatter 提供的所有其他功能（例如截断和着色），您还可以使用 {module, function_name} 元组来自定义日志消息的格式。但是，如果您想完全控制格式化，请考虑编写一个自定义的 :logger 格式化程序，它可以完全访问所有事件和元数据。

使用 {module, function_name} 时，该函数将使用级别、消息、时间戳和元数据调用，如下所示：

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

元数据

可以使用 Logger.metadata/0 和 Logger.metadata/1 函数读取和写入发送到记录器的元数据。例如，您可以设置 Logger.metadata([user_id: 13]) 将 user_id 元数据添加到当前进程。用户可以配置后端以选择要打印的元数据，它将替换 $metadata 值。

总结

类型

date()

date_time_ms()

pattern()

time_ms()

函数

compile(pattern_or_function)

将模式或函数编译成 format/5 可以处理的数据结构。

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

格式化由 compile/1 返回的 pattern_or_function。

format_date(date_tuple)

将日期格式化为 chardata。

format_event(log_event, truncate)

格式化日志事件的消息。

format_time(time_ms_tuple)

将时间格式化为 chardata。

new(options \\ [])

为 :logger 处理程序初始化格式化程序。

prune(binary)

从列表中修剪无效的 Unicode 代码点和无效的 UTF-8 字节。

system_time_to_date_time_ms(system_time, utc_log? \\ false)

将元数据中的系统时间（以微秒为单位）转换为 date_time_ms 元组。

truncate(chardata, n)

将 chardata 截断为 n 字节。

类型

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}

函数

compile(pattern_or_function)

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

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

将模式或函数编译成 format/5 可以处理的数据结构。

查看模块文档以获取有关将在模式中插值的有效参数的文档。如果您将 nil 作为模式传递，则模式默认为：

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

如果您想使用自定义函数自定义格式化，则可以传递一个 {module, function_name} 元组。

此函数与 format/5 一起是 Logger.Formatter.new/1 用于格式化消息的主要构建块。那些有兴趣构建自定义格式化程序的人也可以使用它。

示例

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()}

格式化由 compile/1 返回的 pattern_or_function。

它接受一个已编译的格式，并注入级别、时间戳、消息和元数据关键字列表，并返回一个格式正确的字符串。

如果 pattern_or_function 是一个 {module, function_name} 元组，则调用 module.function_name(level, message, timestamp, metadata) 来获取消息。

此函数与 compile/1 一起是 Logger.Formatter.new/1 用于格式化消息的主要构建块。那些有兴趣构建自定义格式化程序的人也可以使用它。

示例

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"