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(-) 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