Elixir 應用程式的記錄器。

此應用程式主要是 Erlang 的 :logger 功能的包裝器，提供訊息翻譯和格式化到 Elixir 項目。

總體而言，您會發現 Logger

• 提供所有 7 個 syslog 層級（儘管最常使用的是 debug、info、warning 和 error）。

• 同時支援基於訊息和結構化的記錄。

• 與 Erlang 的 :logger 整合，並支援自訂篩選器和處理常式。

• 在客戶端格式化和截斷訊息，以避免阻塞 Logger 處理常式。

• 在同步和非同步模式之間交替，以在需要時保持效能，但在壓力下也施加反壓力。

• 允許覆寫特定模組、應用程式或程序的記錄層級。

記錄對於追蹤系統中發生感興趣的事件時很有用。例如，每當使用者被刪除時記錄可能會很有幫助。

def delete_user(user) do
  Logger.info("Deleting user from the system: #{inspect(user)}")
  # ...
end

Logger.info/2 巨集在 :info 層級發出提供的訊息。請注意，傳遞給 info/2 的引數僅在記錄訊息時才會評估。例如，如果 Logger 層級設定為 :warning，則 :info 訊息永遠不會被記錄，因此上面給出的引數甚至不會被執行。

還有其他層級的額外巨集。

Logger 也允許透過 :compile_time_purge_matching 選項完全移除記錄命令（請參閱下方）。

對於動態記錄訊息，請參閱 bare_log/3。但請注意，bare_log/3 始終會評估其引數（除非引數是匿名函式）。

層級

支援的層級，按重要性排序，如下

• :emergency - 當系統無法使用時，會發生恐慌
• :alert - 對於警示，必須立即採取的動作，例如資料庫損毀
• :critical - 對於關鍵狀況
• :error - 對於錯誤
• :warning - 對於警告
• :notice - 對於一般但重要的訊息
• :info - 對於任何類型的資訊
• :debug - 對於除錯相關的訊息

例如，:info 優先於 :debug。如果您的記錄層級設定為 :info，則所有 :info、:notice 及以上將傳遞給處理常式。如果您的記錄層級設定為 :alert，則僅會列印 :alert 和 :emergency。

訊息

記錄器可用於記錄非結構化和結構化資料。

非結構化資料是字串或字串清單

Logger.info("hello world!")
Logger.info(["hello ", "world!"])

結構化資料，也稱為報告，是關鍵字清單和對應

Logger.info([new_user: user.id, account_type: :admin])
Logger.info(%{new_user: user.id, account_type: :admin})

記錄函數也接受零元匿名函數作為訊息

Logger.info(fn -> "hello world!" end)

匿名函數可以傳回訊息或包含訊息和額外元資料（將在下一節中說明）的元組。

在所有情況下，提供給 Logger 巨集的引數僅在目前記錄層級需要時才會評估。例外是 bare_log/3 函數，它是記錄的原始機制。

元資料

每當記錄訊息時，都可以透過元資料提供額外資訊。每個記錄操作，例如 Logger.info/2，允許將元資料作為引數提供。

此外，可以使用 Logger.metadata/1 為每個處理程序設定元資料。

但是，某些元資料會在可能的情況下由記錄器自動新增。這些是

• :application - 目前應用程式

• :mfa - 目前的模組、函式和元數

• :file - 目前的檔案

• :line - 目前的行數

• :pid - 目前的程序識別碼

• :initial_call - 啟動程序的初始呼叫

• :registered_name - 程序註冊名稱為原子

• :domain - 記錄訊息的網域清單。例如，所有 Elixir 報告預設為 [:elixir]。Erlang 報告可能從 [:otp] 或 [:sasl] 開始

• :crash_reason - 二元組，第一個引數為拋出/錯誤/結束原因，第二個引數為堆疊追蹤。拋出將永遠為 {:nocatch, term}。錯誤永遠是 Exception 結構。所有其他項目都是結束。預設格式化程式預設忽略此元資料，但對某些處理常式很有用，例如向第三方服務報告錯誤的處理常式

有兩個特殊的元資料金鑰，:module 和 :function，從 :mfa 中擷取相關位元。

請注意，所有元資料都是選用的，可能無法隨時取得。使用 Logger 巨集時，會自動包含 :mfa、:file、:line 和類似的元資料。預設情況下，Logger.bare_log/3 不包含 :pid 以外的任何元資料。其他元資料，例如 :crash_reason、:initial_call 和 :registered_name，僅在 GenServer、Supervisor 等行為中可用。

例如，您可能希望在記錄中包含自訂 :error_code 元資料

Logger.error("We have a problem", [error_code: :pc_load_letter])

預設情況下，不會記錄任何元資料。我們將在下一節學習如何啟用。

組態

Logger 支援廣泛的組態。

此組態分為三種類別

• 開機組態 - 此組態在記錄程式啟動時讀取，並組態 Elixir 如何掛入 Erlang 自身的記錄程式

• 編譯組態 - 必須在編譯程式碼之前設定

• 執行時期設定 - 可在 :logger 應用程式啟動前設定，但可在執行時期變更

開機設定

當 Logger 啟動時，它會從 Erlang 設定 :default 記錄處理常式，以轉換和格式化 Elixir 項目。作為開發人員，您能夠自訂預設處理常式、預設格式化器和許多其他選項。

下列設定必須在您的應用程式啟動前，透過設定檔 (例如 config/config.exs) 在 :logger 鍵下設定

• :default_formatter - 一個關鍵字清單，用於設定預設處理常式所使用的預設格式化器。請參閱 Logger.Formatter 以取得完整設定清單。

• :default_handler - 此選項設定用於記錄的預設處理常式。預設處理常式是 :logger_std_h 執行個體，它也支援檔案記錄和記錄輪替。您可以將它設定為 false 以完全停用預設記錄。請參閱下列範例以取得更多資訊。

• :handle_otp_reports - 如果應該記錄 Erlang/OTP 訊息。預設為 true。

• :handle_sasl_reports - 如果應該記錄監督者、崩潰和進度報告。預設為 false。此選項僅在 :handle_otp_reports 為 true 時才會生效。

• :metadata - 要包含在所有記錄訊息中的全域主要元資料。預設為 []。這可以用 metadata/1 在程序層級覆寫，或在每個記錄呼叫中依需要覆寫。

例如，要設定 Logger 使用 config/config.exs 檔案重新導向所有 Erlang 訊息

config :logger,
  handle_otp_reports: true,
  handle_sasl_reports: true

要設定預設格式化器，例如，使用不同的格式並包含一些元資料

config :logger, :default_formatter,
  format: "[$level] $message $metadata\n",
  metadata: [:error_code, :file]

或要設定預設處理常式，例如，記錄到支援記錄輪替和壓縮的檔案中

config :logger, :default_handler,
  config: [
    file: ~c"system.log",
    filesync_repeat_interval: 5000,
    file_check: 5000,
    max_no_bytes: 10_000_000,
    max_no_files: 5,
    compress_on_rotate: true
  ]

請參閱 :logger_std_h 以取得所有相關設定，包括過載保護。或將 :default_handler 設定為 false 以完全停用預設記錄

config :logger, :default_handler, false

後面的章節會說明如何新增處理函式。

關鍵字或對應

雖然 Erlang 的記錄器預期 :config 為對應，但 Elixir 的記錄器允許使用關鍵字清單設定預設處理函式組態。例如，這允許您的 config/*.exs 檔案，例如 config/dev.exs，覆寫 config/config.exs 中定義的個別金鑰。

使用 Erlang 的 API 讀取處理函式組態時，組態會始終以對應的形式讀取（和寫入）。

編譯組態

在編譯程式碼之前，必須透過組態檔案（例如 config/config.exs）在 :logger 應用程式下設定下列組態

• :always_evaluate_messages - 如果訊息應評估，即使記錄層級低於組態的最低層級。預設為 false。這對於測試環境中的記錄層級較高（例如 :error）的情況很有用，這很常見，目的是避免記錄與測試輸出混雜。在這種情況下，您可能會在將程式碼部署到生產環境（記錄層級較低，例如 :info）時，才會發現包含執行時期錯誤的記錄訊息。這些執行時期錯誤可能是由某些未實作 String.Chars 協定的東西在記錄訊息中內插所造成，例如 "PID: #{self()}"（因為 PID 無法使用 String.Chars 轉換為字串）。

• :compile_time_application - 在編譯時將 :application 元資料值設定為組態值。此組態會由 Mix 自動設定，並在記錄時作為元資料提供。

• :compile_time_purge_matching - 在編譯時清除所有符合給定條件的呼叫。這表示 Logger 呼叫的層級低於此選項，將在編譯時完全移除，在執行時不會產生任何負擔。此組態需要一個關鍵字清單清單。每個關鍵字清單包含一個元資料金鑰和應該清除的相符值。支援一些特殊金鑰

  • :level_lower_than - 清除所有層級較低的訊息
  • :module - 清除所有具有相符模組的訊息
  • :function - 清除所有具有「函式/元數」的訊息

  請記住，如果你想清除依賴項目的記錄呼叫，必須重新編譯該依賴項。

例如，要在 config/config.exs 檔案中清除所有在編譯時發生的層級低於 :info 的呼叫

config :logger,
  compile_time_purge_matching: [
    [level_lower_than: :info]
  ]

如果你想清除名為 :foo 的應用程式中的所有記錄呼叫，並只保留 Bar.foo/3 的錯誤，你可以設定兩個不同的相符

config :logger,
  compile_time_purge_matching: [
    [application: :foo],
    [module: Bar, function: "foo/3", level_lower_than: :error]
  ]

執行時組態

以下所有組態都可以透過組態檔案設定（例如 config/config.exs），也可以在執行時透過 Logger.configure/1 動態變更。

• :level - 記錄層級。嘗試記錄任何嚴重性低於組態層級的訊息，只會導致訊息遭到忽略。請記住，每個處理常式也可能有其特定層級。除了上述層級之外，它還支援 2 個「元層級」

  • :all - 將記錄所有訊息，概念上與 :debug 相同
  • :none - 根本不會記錄任何訊息

• :translator_inspect_opts - 在轉譯 OTP 報告和錯誤時，必須在錯誤報告中檢查最後的訊息和狀態。此組態允許開發人員變更要檢查多少資料以及如何檢查資料。

例如，要在 config/config.exs 檔案中組態 :level 選項

config :logger, level: :warning

此外，Logger 允許透過轉譯器將 Erlang 傳送的訊息轉譯成 Elixir 格式。可以使用 add_translator/1 和 remove_translator/1 API 隨時新增轉譯器。請查看 Logger.Translator 以取得更多資訊。

Erlang/OTP 處理器

處理器代表整合到記錄系統中以處理每個記錄的訊息/事件的能力。Elixir 會自動設定預設處理器，但你可以使用 Erlang 的 :logger 模組來新增其他處理器。

Erlang/OTP 處理器必須列在你的應用程式之下。例如，要設定一個額外的處理器，以便寫入主控台和檔案

config :my_app, :logger, [
  {:handler, :file_log, :logger_std_h, %{
     config: %{
       file: ~c"system.log",
       filesync_repeat_interval: 5000,
       file_check: 5000,
       max_no_bytes: 10_000_000,
       max_no_files: 5,
       compress_on_rotate: true
     },
     formatter: Logger.Formatter.new()
   }}
]

每個處理器的形狀為 {:handler, name, handler_module, config_map}。定義後，處理器可以在你的 Application.start/2 回呼中使用 add_handlers/1 明確附加。

Logger.add_handlers(:my_app)

你也可以開發自己的處理器。處理器在與記錄訊息/事件的處理器相同的處理程序中執行。這讓開發人員有彈性，但他們應避免在這些處理器中執行任何長時間執行的動作，因為這可能會大幅減慢正在執行的動作。目前，Erlang 處理器沒有內建的過載防護，因此實作它的責任在你。

或者，你可以使用 :logger_backends 專案。它會設定一個具有過載防護的記錄處理器，並允許將傳入事件分派到多個後端。

過濾

你可以將過濾器新增到 Erlang 的 :logger。例如，要過濾掉包含特定字串的記錄，你可以建立一個模組

defmodule LogFilter do
  def filter(log_event, _opts) do
    case log_event do
      %{msg: msg} when is_binary(msg) ->
        if msg =~ "password" do
          :stop
        else
          :ignore
        end

      _ ->
        :ignore
    end
  end
end

然後，當你啟動應用程式時，例如在 Application.start/2 回呼中

:logger.add_primary_filter(:word_filter, {&LogFilter.filter/2, []})

後端和後向相容性

在 Elixir v1.15 之前，可以使用 Logger 後端來達成自訂記錄。寫入 Logger 後端的 API 已主要移至 :logger_backends 專案。但是，後端 API 仍是 Elixir 的一部分，以確保後向相容性。

重要事項

• 如果設定 :backends 鍵，且它沒有 :console 項目，我們假設您想要停用內建記錄。您可以透過設定 config :logger, :default_handler, [] 來強制記錄。

• :console 後端設定會自動對應到預設處理常式和預設格式化器。先前，您會設定

  config :logger, :console,
    level: :error,
    format: "$time $message $metadata"

  這現在等同於

  config :logger, :default_handler,
    level: :error
  
  config :logger, :default_formatter,
    format: "$time $message $metadata"

  除了 :level 以外，所有先前的主控台設定現在都移到 :default_formatter 下。

• 如果您想要使用基於記錄器後端的先前 :console 實作，您仍然可以設定 backends: [Logger.Backends.Console]，並將設定放在 config :logger, Logger.Backends.Console 下。不過，建議在這種情況下使用 :logger_backends 專案，因為 Logger.Backends.Console 本身會在未來的版本中被棄用

• Logger.Backends 只接收 :debug、:info、:warning 和 :error 訊息。 :notice 對應到 :info。 :warn 對應到 :warnings。所有其他對應到 :error