From 0d3b793ac551f9c69f9e1c0c5a76186386f3cd04 Mon Sep 17 00:00:00 2001 From: Siri Hansen Date: Wed, 2 May 2018 11:50:49 +0200 Subject: Update logger documentation --- lib/kernel/doc/src/kernel_app.xml | 30 ++--- lib/kernel/doc/src/logger.xml | 6 +- lib/kernel/doc/src/logger_chapter.xml | 5 +- lib/kernel/doc/src/logger_formatter.xml | 217 +++++++++++++++++++------------- 4 files changed, 146 insertions(+), 112 deletions(-) (limited to 'lib/kernel/doc/src') diff --git a/lib/kernel/doc/src/kernel_app.xml b/lib/kernel/doc/src/kernel_app.xml index 554d675383..f96d946a5d 100644 --- a/lib/kernel/doc/src/kernel_app.xml +++ b/lib/kernel/doc/src/kernel_app.xml @@ -226,7 +226,7 @@

This configuration parameter is used both for the global logger level, and for the standard handler started by the Kernel application (see logger_dest variable above).

-

The default value is info

+

The default value is info.

logger_disk_log_type = halt | wrap @@ -251,14 +251,14 @@ logger_disk_log_maxbytes = 1048576

If this parameter is set to true, then the logger handler started by kernel will not log any progress-, crash-, or - supervisor reports. If the SASL application is starated, + supervisor reports. If the SASL application is started, these log events will be sent to a second handler instance - named sasl_h, according to values of the SASL environment - variables sasl_error_logger + named sasl_h, according to values of the SASL + environment variables sasl_error_logger and sasl_errlog_type, see SASL(6)

-

The default value is false

+

The default value is false.

See chapter Backwards compatibility with error_logger for more information about handling of the so called SASL reports.

@@ -271,7 +271,7 @@ logger_disk_log_maxbytes = 1048576 reports from supervisor and application_controller shall be logged or not.

-

If logger_sasl_compatible = false, +

If logger_sasl_compatible = true, then logger_log_progress is ignored.

 @@ -280,14 +280,6 @@ logger_disk_log_maxbytes = 1048576

Can be used to limit the size of the formatted output from the logger handlers.

-

This configuration parameter was introduced in OTP 18.1 - and is experimental. Based on user feedback, it - can be changed or improved in future releases, for example, - to gain better control over how to limit the size of the - formatted output. We have no plans to remove this - new feature entirely, unless it turns out to be - useless.

 -

Depth is a positive integer representing the maximum depth to which terms are printed by the logger handlers included in OTP. This @@ -312,11 +304,11 @@ logger_disk_log_maxbytes = 1048576 logger_max_size = integer() | unlimited -

This parameter specifies the maximum size (bytes) each - log event can have when printed by the standard logger - handler. If the resulting string after formatting an event - is bigger than this, it will be truncated before printed - to the handler's destination.

+

This parameter specifies a hard maximum size limit (number + of characters) each log event can have when printed by the + default logger formatter. If the resulting string after + formatting an event is bigger than this, it will be + truncated before printed to the handler's destination.

logger_utc = boolean() diff --git a/lib/kernel/doc/src/logger.xml b/lib/kernel/doc/src/logger.xml index 66e6e5c689..ded9c1fb37 100644 --- a/lib/kernel/doc/src/logger.xml +++ b/lib/kernel/doc/src/logger.xml @@ -131,8 +131,8 @@ #{mfa=>{?MODULE,?FUNCTION_NAME,?FUNCTION_ARITY}, - file=>?FILE, - line=>?LINE} + file=>?FILE, + line=>?LINE}

The call is wrapped in a case statement and will be evaluated @@ -297,7 +297,7 @@ print Pretty print all the current logger configuration to standard out. Example: - logger:i(). + logger:i(print). Current logger configuration: Level: info FilterDefault: log diff --git a/lib/kernel/doc/src/logger_chapter.xml b/lib/kernel/doc/src/logger_chapter.xml index 88dcfbe8d9..78d6f46c95 100644 --- a/lib/kernel/doc/src/logger_chapter.xml +++ b/lib/kernel/doc/src/logger_chapter.xml @@ -488,8 +488,9 @@ error_logger:add_report_handler/1,2. level => debug} 2> logger:add_handler(debug_handler,logger_std_h,Config). ok -

By default, the handler receives all events, so we need to add a filter - to stop all non-debug events:

+

By default, the handler receives all events + (filter_defalt=log), so we need to add a filter to stop + all non-debug events:

 3> Fun = fun(#{level:=debug}=Log,_) -> Log; (_,_) -> stop end.
 #Fun<erl_eval.12.98642416>
diff --git a/lib/kernel/doc/src/logger_formatter.xml b/lib/kernel/doc/src/logger_formatter.xml
index 6a17e3641f..a0940100ee 100644
--- a/lib/kernel/doc/src/logger_formatter.xml
+++ b/lib/kernel/doc/src/logger_formatter.xml
@@ -37,116 +37,157 @@
 
   
     
Default formatter for the Logger application.

-  
-
-  
-    
-      
-      
-      
-    
-  
-
-  
-    
-      
-      Formats the given message.
-      
-        
Formats the given message.

-	
The template is a list of atoms, tuples and strings. Atoms
-	  can be level or msg, which are placeholders
-	  for the severity level and the log message,
-	  repectively. Tuples are interpreted as placeholders for
-	  metadata. Each element in the tuple must be an atom which
-	  matches a key in the nested metadata map, e.g. the
-	  tuple {key1,key2} will be replaced by the value of
-	  the key2 field in this nested map (the value vill be
-	  converted to a string):

-
-
-#{key1=>#{key2=>my_value,
-          ...},
-  ...}
-
-
-        
 Strings are printed literally.

-
-	
depth is a positive integer representing the maximum
-	  depth to which terms shall be printed by this
-	  formatter. Format strings passed to this formatter are
-	  rewritten. The format controls ~p and ~w are replaced with
-	  ~P and ~W, respectively, and the value is used as the depth
-	  parameter. For details, see
-	  io:format/2,3
-	  in STDLIB.

-
-	
chars_limit is a positive integer representing the
-	  value of the option with the same name to be used when calling
-	  io:format/3. This
-	  value limits the total number of characters printed bu the
-	  formatter. Notes that this is a soft limit. For a hard
-	  truncation limit, see option max_size.

-
-	
max_size is a positive integer representing the
-	  maximum size a string returned from this formatter can
-	  have. If the formatted string is longer, after possibly
-	  being limited by depth and/or chars_limit, it
-	  will be truncated.

-
-	
utc is a boolean. If set to true, all dates are
-	  displayed in Universal Coordinated Time. Default
-	  is false.

 
-	
report_cb must be a function with arity 1,
-	  returning {Format,Args}. This function will replace
-	  any report_cb found in metadata.

-
-	
If single_line=true, all newlines in the message are
-	  replaced with ", ", and whitespaces following directly
-	  after newlines are removed. Note that newlines added by the
-	  formatter template are not replaced.

+  
 
-	
If legacy_header=true a header field is added to
+  

+    Configuration
+    
The following configuration parameters can be set
+      for logger_formatter:

+    
+      single_line = boolean()
+      
+	
If set to true, all newlines in the message are
+	  replaced with ", ", and whitespaces following
+	  directly after newlines are removed. Note that newlines
+	  added by the formatter template are not replaced.

+	
Default is true.

+      
+      legacy_header = boolen()
+      
+	
If set to true a header field is added to
 	  logger_formatter's part of Metadata. The value of
 	  this field is a string similar to the header created by the
 	  old error_logger event handlers. It can be included
 	  in the log event by adding the
-	  tuple {logger_formatter,header} to the template.

-
-	
The default template when legacy_header=true is

-
-	[{logger_formatter,header},"\n",msg,"\n"]
+	  tuple {logger_formatter,header} to the
+	  template. See Default
+	  Templates for more information

+	
Default is false.

+      
+      report_cb = fun((logger:report()) -> {io:format(),[term()]})
+      
+	
A function with arity 1,
+	  returning {Format,Args}. This function will replace
+	  any report_cb found in metadata.

+      
+      depth = pos_integer() | unlimited
+      
+	
A positive integer representing the maximum depth to
+	  which terms shall be printed by this formatter. Format
+	  strings passed to this formatter are rewritten. The format
+	  controls ~p and ~w are replaced with ~P and ~W,
+	  respectively, and the value is used as the depth
+	  parameter. For details, see
+	  io:format/2,3
+	  in STDLIB.

+	
Default is unlimited.

+      
+      chars_limit = pos_integer() | unlimited
+      
+	
A positive integer representing the value of the option
+	  with the same name to be used when calling
+	  io_lib:format/3.
+	  This value limits the total number of characters printed
+	  for each log event. Note that this is a soft limit. For a
+	  hard truncation limit, see option max_size.

+	
Default is unlimited.

+      
+      max_size = pos_integer() | unlimited
+      
+	
A positive integer representing the absolute maximum size
+	  a string returned from this formatter can have. If the
+	  formatted string is longer, after possibly being limited
+	  by depth and/or chars_limit, it will be
+	  truncated.

+	
Default is unlimited.

+      
+      template = template()
+      
+	
The template is a list of atoms, tuples and strings. The
+	  atoms level or msg, are treated as
+	  placeholders for the severity level and the log message,
+	  repectively. Other atoms or tuples are interpreted as
+	  placeholders for metadata, where atoms are expected to
+	  match top level keys, and tuples represent paths to sub
+	  keys in a nested map. For example the
+	  tuple {key1,key2} will be replaced by the value of
+	  the key2 field in the nested map below. The
+	  atom key1 on its own would be replaced by the
+	  complete value of the key1 field. The values are
+	  converted to strings.

 
-	
which will cause log entries like this:

+
+#{key1=>#{key2=>my_value,
+          ...}
+  ...}
 
-	=ERROR REPORT==== 29-Dec-2017::13:30:51.245123 ===
+        
Strings are printed literally.

+	
The default template differs depending on the values
+	  of legacy_header
+	  and single_line. See Default
+	  Templates for more information

+      
+      utc = boolean()
+      
+	
If set to true, all dates are displayed in Universal
+	  Coordinated Time. Default is false.

+      
+    
+  

+
+  

+    
+    Default templates
+    
The default template when legacy_header=true is

+
+    [{logger_formatter,header},"\n",msg,"\n"]
+
+    
which will cause log entries like this:

+
+    =ERROR REPORT==== 29-Dec-2017::13:30:51.245123 ===
     process: <0.74.0>
     exit_reason: "Something went wrong"
 
-	
Note that all eight levels might occur here, not
-	  only ERROR, WARNING or INFO. And also
-	  that micro seconds are added at the end of the
-	  timestamp.

+    
Note that all eight levels might occur here, not
+      only ERROR, WARNING or INFO. And also that
+      micro seconds are added at the end of the timestamp.

 
-	
The default template when single_line=true is

+    
The default template when single_line=true is

 
-	[time," ",level,": ",msg,"\n"]
+    [time," ",level,": ",msg,"\n"]
 
-	
which will cause log entries like this:

+    
which will cause log entries like this:

 
-	2017-12-29 13:31:49.640317 error: process: <0.74.0>, exit_reason: "Something went wrong"
+    2017-12-29 13:31:49.640317 error: process: <0.74.0>, exit_reason: "Something went wrong"
 
-	
The default template when both legacy_header and
-	  single_line are set to false is:

+    
The default template when both legacy_header and
+      single_line are set to false is:

 
-	[time," ",level,":\n",msg,"\n"]
+    [time," ",level,":\n",msg,"\n"]
 
-	
which will cause log entries like this:

+    
which will cause log entries like this:

 
-	2017-12-29 13:32:25.191925 error:
+    2017-12-29 13:32:25.191925 error:
     process: <0.74.0>
     exit_reason: "Something went wrong"
+  

+
+  
+    
+      
+      
+      
+    
+  
 
+  
+    
+      
+      Formats the given message.
+      
+	
This the callback function to be called from handlers. It
+	  formats the given messages.

       
     
 
-- 
cgit v1.2.3


From de2965827bfb903dcfcd0a97603548b2f8e3a807 Mon Sep 17 00:00:00 2001
From: Siri Hansen 
Date: Wed, 2 May 2018 18:55:10 +0200
Subject: Change return type from logger_formatter:format/2

This used to be string() is now changed to unicode:chardata().
---
 lib/kernel/doc/src/logger_chapter.xml | 22 ++++------------------
 1 file changed, 4 insertions(+), 18 deletions(-)

(limited to 'lib/kernel/doc/src')

diff --git a/lib/kernel/doc/src/logger_chapter.xml b/lib/kernel/doc/src/logger_chapter.xml
index 78d6f46c95..36f5f6dea3 100644
--- a/lib/kernel/doc/src/logger_chapter.xml
+++ b/lib/kernel/doc/src/logger_chapter.xml
@@ -157,7 +157,7 @@
 	  
A formatter is defined as a module exporting the following
 	    function:

 
-	  format(Log,Extra) -> string()
+	  format(Log,Extra) -> unicode:chardata()
 
 	  
The formatter plugin is called by each handler, and the
 	    returned string can be printed to the handler's destination
@@ -322,19 +322,6 @@
 	    return ignore.

 	  
Default is log.

 	
-        depth = pos_integer() | unlimited
-	
-	  
Specifies if the depth of terms in the log events shall
-	    be limited by using control characters ~P
-	    and ~W instead of ~p and ~w,
-	    respectively. See
-	    io:format.

-	
-        max_size = pos_integer() | unlimited
-	
-	  
Specifies if the size of a log event shall be limited by
-	    truncating the formatted string.

-	
 	formatter = {Module::module(),Extra::term()}
 	
 	  
See Formatter for more
@@ -347,10 +334,9 @@
 
       
Note that level and filters are obeyed by
 	Logger itself before forwarding the log events to each
-	handler, while depth, max_size
-	and formatter are left to the handler
-	implementation. All Logger's built-in handlers do apply these
-	configuration parameters before printing.

+	handler, while formatter is left to the handler
+	implementation. All Logger's built-in handlers will call the
+	given formatter before printing.

     
 
   
-- 
cgit v1.2.3


From 336e7eed4e44fe9267234e4702db6fd613064dcd Mon Sep 17 00:00:00 2001
From: Siri Hansen 
Date: Wed, 2 May 2018 18:57:23 +0200
Subject: Improve documentation of logger:set_*_config functions

---
 lib/kernel/doc/src/logger.xml | 38 ++++++++++++++++++++++++++++++++++++--
 1 file changed, 36 insertions(+), 2 deletions(-)

(limited to 'lib/kernel/doc/src')

diff --git a/lib/kernel/doc/src/logger.xml b/lib/kernel/doc/src/logger.xml
index ded9c1fb37..2beefd1240 100644
--- a/lib/kernel/doc/src/logger.xml
+++ b/lib/kernel/doc/src/logger.xml
@@ -404,21 +404,55 @@ Current logger configuration:
 
     
       
+      Set configuration data for the logger.
+      
+        
Set configuration data for the logger. This overwrites the
+          current logger configuration.

+	
To modify the existing configuration,
+	  use set_logger_config/2
+	  , or read the current configuration
+	  with get_logger_config/0
+	  , then merge in your added or updated
+	  associations before writing it back.

+      
+    
+
+    
       
       Add or update configuration data for the logger.
       
-        
Add or update configuration data for the logger.

+        
Add or update configuration data for the logger. If the
+          given Key already exists, its associated
+          value will be set to Value. If it
+          doesn't exist, it will be added.

       
     
 
     
       
+      Set configuration data for the specified handler.
+      
+        
Set configuration data for the specified handler. This
+          overwrites the current handler configuration.

+	
To modify the existing configuration,
+	  use set_handler_config/3
+	  , or read the current configuration
+	  with get_handler_config/1
+	  , then merge in your added or updated
+	  associations before writing it back.

+      
+    
+
+    
       
       Add or update configuration data for the specified
         handler.
       
         
Add or update configuration data for the specified
-          handler.

+          handler. If the
+          given Key already exists, its associated
+          value will be set to Value. If it
+          doesn't exist, it will be added.

       
     
 
-- 
cgit v1.2.3


From 3cef0524e4332ebf547180ec0d0feafe0a559b5c Mon Sep 17 00:00:00 2001
From: Siri Hansen 
Date: Wed, 2 May 2018 19:20:27 +0200
Subject: Add logger:update_process_metadata/1

---
 lib/kernel/doc/src/logger.xml | 22 ++++++++++++++++++----
 1 file changed, 18 insertions(+), 4 deletions(-)

(limited to 'lib/kernel/doc/src')

diff --git a/lib/kernel/doc/src/logger.xml b/lib/kernel/doc/src/logger.xml
index 2beefd1240..2f7feb5eef 100644
--- a/lib/kernel/doc/src/logger.xml
+++ b/lib/kernel/doc/src/logger.xml
@@ -471,10 +471,9 @@ Current logger configuration:
       
       Set metadata to use when logging from current process.
       
-        
Set metadata which logger automatically inserts it
-          in all log events produced on the current
-          process. Subsequent calls will overwrite previous data set
-          by this function.

+        
Set metadata which logger automatically inserts in
+          all log events produced on the current process. Subsequent
+          calls will overwrite previous data set by this function.

 	
When logging, location data produced by the log macros,
 	  and/or metadata given as argument to the log call (API
 	  function or macro), will be merged with the process
@@ -485,6 +484,21 @@ Current logger configuration:
       
     
 
+    
+      
+      Update metadata to use when logging from current process.
+      
+	
Update metadata to use when logging from current process

+	
This function behaves as if it was implemented as follows:

+	
+logger:set_process_metadata(maps:merge(logger:get_process_metadata(),Meta))
+	
+	
If no process metadata exists, the function behaves as
+	  set_process_metadata/1
+	  .

+      
+    
+
     
       
       Retrieve data set with set_process_metadata/1.
-- 
cgit v1.2.3


From 3c9e4adff06a3f74513cb6658405e43e674133c1 Mon Sep 17 00:00:00 2001
From: Siri Hansen 
Date: Fri, 4 May 2018 16:40:55 +0200
Subject: Change logger callback removing_handler/1 to removing_handler/2

---
 lib/kernel/doc/src/logger_chapter.xml | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

(limited to 'lib/kernel/doc/src')

diff --git a/lib/kernel/doc/src/logger_chapter.xml b/lib/kernel/doc/src/logger_chapter.xml
index 36f5f6dea3..519df2ba48 100644
--- a/lib/kernel/doc/src/logger_chapter.xml
+++ b/lib/kernel/doc/src/logger_chapter.xml
@@ -503,7 +503,7 @@ ok

It may also implement the following callbacks:

adding_handler(logger:handler_id(),logger:config()) -> {ok,logger:config()} | {error,term()} -removing_handler(logger:handler_id()) -> ok +removing_handler(logger:handler_id(),logger:config()) -> ok changing_config(logger:handler_id(),logger:config(),logger:config()) -> {ok,logger:config()} | {error,term()}

When logger:add_handler(Id,Module,Config) is called, logger @@ -513,7 +513,7 @@ changing_config(logger:handler_id(),logger:config(),logger:config()) -> {ok,logg events as calls to Module:log/2.

A handler can be removed by calling logger:remove_handler(Id). logger will call - Module:removing_handler(Id), and then remove the handler's + Module:removing_handler(Id,Config), and then remove the handler's configuration from the configuration database.

When logger:set_handler_config is called, logger calls Module:changing_config(Id,OldConfig,NewConfig). If this function @@ -534,7 +534,7 @@ log(Log,#{formatter:={FModule,FConfig}) -> this:

-module(myhandler). --export([adding_handler/2, removing_handler/1, log/2]). +-export([adding_handler/2, removing_handler/2, log/2]). -export([init/1, handle_call/3, handle_cast/2, terminate/2]). adding_handler(Id,Config) -> @@ -563,7 +563,7 @@ log(Log,#{myhandler_fd:=Fd,formatter:={FModule,FConfig}}) -> single process.

-module(myhandler). --export([adding_handler/2, removing_handler/1, log/2]). +-export([adding_handler/2, removing_handler/2, log/2]). -export([init/1, handle_call/3, handle_cast/2, terminate/2]). adding_handler(Id,Config) -> -- cgit v1.2.3