Logger.Formatter.format/2

[David-Klemenc]

Elixir and Erlang/OTP versions

Erlang/OTP 27 [erts-15.1.2] [source] [64-bit] [smp:16:16] [ds:16:16:10] [async-threads:1] [dtrace]

Elixir 1.17.3 (compiled with Erlang/OTP 27)

Operating system

all

Current behavior

the function Logger.Formatter.format/2 has docs set to false -> @doc false

it is difficult to figure out what the correct setup is to properly use Logger.Formatter.new/1 and the proper setup.

Expected behavior

A config and implementation example would be welcome, something like:
example config.exs

import Config

config :example, :logger, [
  {:handler, :example_log, ExampleLoggerHandler,
   %{
     formatter:
       Logger.Formatter.new(
         format: "$time $metadata[$level] $message",
         # in case you want to save the msg to DB or send it via HTTP
         # the terminal color codes are not necessary
         colors: [enabled: false]
       )
   }}
]

example of logger_handler minimal implementation module:

defmodule ExampleLoggerHandler do
  @behaviour :logger_handler

  @spec log(:logger.log_event(), :logger_handler.config()) :: term()
  def log(event, config) do
    {formatter, formatterConfig} =
      Map.get(config, :formatter)

    message =
      apply(formatter, :format, [event, formatterConfig])
      |> IO.chardata_to_string()

    # you have a nicely formatted message now
    # you can save the message and meta-data into a DB, send it somewhere via HTTP
    # or do whatever you want
  end
end

Here I used apply/3 to make it more clear what is going on. Basically the Logger.Formatter.new/1 should hint at the existence of Logger.Formatter.format/2 and how it is supposed to be called.

[josevalim]

Logger.Formatter follows the standard specification of Erlang's formatter. The internal functions are not relevant for users, which is why they are @doc false. Only those implementing logger handlers care, which I assume to be you, but you then must follow the specification outlined by Erlang. If we document Logger.Formatter and you use the API specific to Logger.Formatter, then you may actually be incompatible with other formatters.

[josevalim]

Oops, premature send. Let me know if what I wrote above makes sense. But basically, I think the correct place is here: https://www.erlang.org/doc/apps/kernel/logger_chapter.html#formatters - perhaps we should link to it instead, specifying that we are implementing that contract?

[David-Klemenc]

Yes a link would be welcome - I think it would make things easier, since the docs have this:

  You can also build your own instances of this formatter by calling
  `new/1` and setting at the formatter of any `:logger` handler by
  settings its `:formatter` key to `Logger.Formatter.new(options)`.

and it was not clear to me at first that this relates to the Erlang formatters.

Maybe changing the text to:

You can also build your own instances of this formatter by calling
  `new/1` and setting at the formatter of any `:logger_handler` by
  settings its `:formatter` key to `Logger.Formatter.new(options)`.

would make it easy-er to search for the correct behaviour?