From 195558496d9ed89fb98be6dbd139febe39ef1e94 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jos=C3=A9=20Valim?= Date: Sat, 11 Jun 2022 09:32:28 +0200 Subject: Move custom formatting docs to Logger.Formatter --- lib/logger/lib/logger.ex | 3 +- lib/logger/lib/logger/backends/console.ex | 48 +------------------------ lib/logger/lib/logger/formatter.ex | 58 ++++++++++++++++++++++++++++--- 3 files changed, 57 insertions(+), 52 deletions(-) (limited to 'lib/logger') diff --git a/lib/logger/lib/logger.ex b/lib/logger/lib/logger.ex index 9a90ebcab..9e25a197f 100644 --- a/lib/logger/lib/logger.ex +++ b/lib/logger/lib/logger.ex @@ -311,7 +311,8 @@ defmodule Logger do The available backends by default are: * `:console` - logs messages to the console (enabled by default). - `:console` is simply a shortcut for `Logger.Backends.Console`. + `:console` is simply a shortcut for `Logger.Backends.Console` + (see its documentation for more information) Developers may also implement their own backends, an option that is explored in more detail below. diff --git a/lib/logger/lib/logger/backends/console.ex b/lib/logger/lib/logger/backends/console.ex index ad67d1092..0ffa5982f 100644 --- a/lib/logger/lib/logger/backends/console.ex +++ b/lib/logger/lib/logger/backends/console.ex @@ -12,7 +12,7 @@ defmodule Logger.Backends.Console do Defaults to: `"\n$time $metadata[$level] $message\n"`. It may also be a `{module, function}` tuple that is invoked with the log level, the message, the current timestamp and - the metadata. + the metadata. See `Logger.Formatter`. * `:metadata` - the metadata to be printed by `$metadata`. Defaults to an empty list (no metadata). @@ -51,52 +51,6 @@ defmodule Logger.Backends.Console do format: "\n$time $metadata[$level] $message\n", metadata: [:user_id] - ## Custom formatting - - The console backend allows you to customize the format of your - log messages with the `:format` option. - - You may set `:format` to either a string or a `{module, function}` - tuple if you wish to provide your own format function. Here is an - example of how to configure the `:console` backend in a - `config/config.exs` file: - - config :logger, :console, - format: {MyConsoleLogger, :format} - - And here is an example of how you can define `MyConsoleLogger.format/4` - from the above configuration: - - defmodule MyConsoleLogger do - def format(level, message, timestamp, metadata) do - # Custom formatting logic... - end - end - - It is extremely important that **the formatting function does - not fail**, as it will bring that particular logger instance down, - causing your system to temporarily lose messages. If necessary, - wrap the function in a `rescue` and log a default message instead: - - defmodule MyConsoleLogger do - def format(level, message, timestamp, metadata) do - # Custom formatting logic... - rescue - _ -> "could not format: #{inspect({level, message, metadata})}" - end - end - - The `{module, function}` will be invoked with four arguments: - - * the log level: an atom - * the message: this is usually chardata, but in some cases it - may contain invalid data. Since the formatting function should - *never* fail, you need to prepare for the message being anything - * the current timestamp: a term of type `t:Logger.Formatter.time/0` - * the metadata: a keyword list - - You can read more about formatting in `Logger.Formatter`, especially - if you want to support custom formatting in a custom backend. """ @behaviour :gen_event diff --git a/lib/logger/lib/logger/formatter.ex b/lib/logger/lib/logger/formatter.ex index fa7f93f03..431cc226e 100644 --- a/lib/logger/lib/logger/formatter.ex +++ b/lib/logger/lib/logger/formatter.ex @@ -4,12 +4,21 @@ defmodule Logger.Formatter do @moduledoc ~S""" Conveniences for formatting data for logs. - This module allows developers to specify a string that - serves as template for log messages, for example: + This module allows developers to specify a `{module, function}` + or a string that serves as template for log messages. - $time $metadata[$level] $message\n + ## Formatting string - Will print error messages as: + The log messages can be controlled by a formatting string. + Here is an example of how to configure the `:console` backend + in a `config/config.exs` file: + + For example: + + config :logger, :console, + format: "$time $metadata[$level] $message\n" + + The above will print error messages as: 18:43:12.439 user_id=13 [error] Hello\n @@ -28,6 +37,47 @@ defmodule Logger.Formatter do runtime and `format/5` to format the compiled pattern into an actual IO data. + ## Formatting function + + You can also customize the format of your log messages to a + `{module, function}` tuple if you wish to provide your own + format function. Here is an example of how to configure the + `:console` backend in a `config/config.exs` file: + + config :logger, :console, + format: {MyConsoleLogger, :format} + + And here is an example of how you can define `MyConsoleLogger.format/4` + from the above configuration: + + defmodule MyConsoleLogger do + def format(level, message, timestamp, metadata) do + # Custom formatting logic... + end + end + + It is extremely important that **the formatting function does + not fail**, as it will bring that particular logger instance down, + causing your system to temporarily lose messages. If necessary, + wrap the function in a `rescue` and log a default message instead: + + defmodule MyConsoleLogger do + def format(level, message, timestamp, metadata) do + # Custom formatting logic... + rescue + _ -> "could not format: #{inspect({level, message, metadata})}" + end + end + + The `{module, function}` will be invoked with four arguments: + + * the log level: an atom + * the message: this is usually chardata, but in some cases it + may contain invalid data. Since the formatting function should + *never* fail, you need to prepare for the message being anything + * the current timestamp: a term of type `t:time/0` + * the metadata: a keyword list + ## Metadata Metadata to be sent to the logger can be read and written with -- cgit v1.2.1