File 3512-kernel-Expand-documentation-of-logger-log-... of Package erlang

Overview Repositories Revisions Requests Users Attributes Meta

File 3512-kernel-Expand-documentation-of-logger-log-with-fun.patch of Package erlang

From 4fe05a5dabd057ada2d637f38173e938e4e8468e Mon Sep 17 00:00:00 2001
From: Lukas Larsson <lukas@erlang.org>
Date: Thu, 11 Feb 2021 09:52:33 +0100
Subject: [PATCH 2/2] kernel: Expand documentation of logger:log with fun

---
 lib/kernel/doc/src/logger.xml         | 36 +++++++++++++++++++++++++--
 lib/kernel/doc/src/logger_chapter.xml | 18 +++++++++-----
 2 files changed, 46 insertions(+), 8 deletions(-)

diff --git a/lib/kernel/doc/src/logger.xml b/lib/kernel/doc/src/logger.xml
index 2f2417690b..acf695d112 100644
--- a/lib/kernel/doc/src/logger.xml
+++ b/lib/kernel/doc/src/logger.xml
@@ -450,12 +450,44 @@ logger:error("error happened because: ~p", [Reason]). % Without macro
 <type variable="FunArgs" name_i="4"/>
 <type variable="Metadata"/>
 <desc>
- Log the given message.
+ Create a log event at the given
+ <seeguide marker="logger_chapter#log_level">log level</seeguide>,
+ with the given <seeguide marker="logger_chapter#log_message">message</seeguide>
+ to be logged and
+ <seeguide marker="logger_chapter#metadata">metadata</seeguide>.
+ Examples:
+ <code>
+%% A plain string
+logger:log(info, "Hello World").
+%% A plain string with metadata
+logger:log(debug, "Hello World", #{ meta => data }).
+%% A format string with arguments
+logger:log(warning, "The roof is on ~ts",[Cause]).
+%% A report
+logger:log(warning, #{ what => roof, cause => Cause }).
+ </code>
+ The message and metadata can either be given directly in the arguments,
+ or returned from a fun. Passing a fun instead of the message/metadata directly is
+ useful in scenarios when the message/metadata is very expensive to compute.
+ This is because the fun is only evaluted when the message/metadata is
+ actually needed, which may be not at all if the log event is not
+ to be logged. Examples:
+ <code>
+%% A plain string with expensive metadata
+logger:info(fun([]) -> {"Hello World", #{ meta => expensive() }} end,[]).
+%% An expensive report
+logger:debug(fun(What) -> #{ what => What, cause => expensive() } end,roof).
+%% A plain string with expensive metadata and normal metadata
+logger:debug(fun([]) -> {"Hello World", #{ meta => expensive() }} end,[],
+ #{ meta => data }).
+ </code>
+ When metadata is given both as an argument and returned from the fun they
+ are merged. If equal keys exists the values are taken from the metadata
+ returned by the fun.
 </desc>
 </func>
 </funcs>
 
- 
 <funcs>
 <fsdescription>
 <marker id="configuration_API"/>
diff --git a/lib/kernel/doc/src/logger_chapter.xml b/lib/kernel/doc/src/logger_chapter.xml
index b082607751..c2c70ce884 100644
--- a/lib/kernel/doc/src/logger_chapter.xml
+++ b/lib/kernel/doc/src/logger_chapter.xml
@@ -192,8 +192,18 @@
 The log message contains the information to be logged. The
 	message can consist of a format string and arguments (given as
 	two separate parameters in the Logger API), a string or a
-	report. The latter, which is either a map or a key-value list,
-	can be accompanied by a report callback specified in
+ report.
+ Example, format string and arguments:
+ <code>logger:error("The file does not exist: ~ts",[Filename])</code>
+ Example, string:
+ <code>logger:notice("Something strange happened!")</code>
+ A report, which is either a map or a key-value list, is
+ the preferred way to log using Logger as it makes it possible
+ for different backends to filter and format the log event as it
+ needs to.
+ Example, report:
+ <code>?LOG_ERROR(#{ user => joe, filename => Filename, reason => enoent })</code>
+ Reports can be accompanied by a report callback specified in
 	the log event's <seeguide marker="#metadata">metadata</seeguide>.
 	The report callback is a convenience function that
 	the <seeguide marker="#formatters">formatter</seeguide> can use
@@ -219,10 +229,6 @@
 	contain line breaks or not. This variant is used when the
 	formatting of the report depends on the size or single line
 	parameters.
- Example, format string and arguments:
- <code>logger:error("The file does not exist: ~ts",[Filename])</code>
- Example, string:
- <code>logger:notice("Something strange happened!")</code>
 Example, report, and metadata with report callback:
 <code>
 logger:debug(#{got => connection_request, id => Id, state => State},
-- 
2.26.2

Places

File 3512-kernel-Expand-documentation-of-logger-log-with-fun.patch of Package erlang

Places