檢視原始碼 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"