1logger_formatter(3)        Erlang Module Definition        logger_formatter(3)
2
3
4

NAME

6       logger_formatter - Default formatter for Logger.
7

DESCRIPTION

9       Each  Logger  handler  has a configured formatter specified as a module
10       and a configuration term. The purpose of the formatter is to  translate
11       the  log  events to a final printable string (unicode:chardata()) which
12       can be written to the output device of the handler. See  sections  Han‐
13       dlers and Formatters in the Kernel User's Guide for more information.
14
15       logger_formatter is the default formatter used by Logger.
16

DATA TYPES

18       config() =
19           #{chars_limit => integer() >= 1 | unlimited,
20             depth => integer() >= 1 | unlimited,
21             legacy_header => boolean(),
22             max_size => integer() >= 1 | unlimited,
23             report_cb => logger:report_cb(),
24             single_line => boolean(),
25             template => template(),
26             time_designator => byte(),
27             time_offset => integer() | [byte()]}
28
29              The  configuration  term  for logger_formatter is a map, and the
30              following keys can be set as configuration parameters:
31
32                chars_limit = integer() > 0 | unlimited:
33                  A positive integer representing the value of the option with
34                  the  same name to be used when calling io_lib:format/3. This
35                  value limits the total number of characters printed for each
36                  log  event.  Notice  that  this  is a soft limit. For a hard
37                  truncation limit, see option max_size.
38
39                  Defaults to unlimited.
40
41                depth = integer() > 0 | unlimited:
42                  A positive integer representing the maximum depth  to  which
43                  terms  shall  be  printed  by this formatter. Format strings
44                  passed to this formatter are rewritten. The format  controls
45                  ~p and ~w are replaced with ~P and ~W, respectively, and the
46                  value is used as  the  depth  parameter.  For  details,  see
47                  io:format/2,3 in STDLIB.
48
49                  Defaults to unlimited.
50
51                legacy_header = boolean():
52                  If set to true a header field is added to logger_formatter's
53                  part of Metadata. The value of this field is a string  simi‐
54                  lar to the header created by the old error_logger event han‐
55                  dlers. It can be included in the log  event  by  adding  the
56                  list  [logger_formatter,header] to the template. See the de‐
57                  scription of the template() type for more information.
58
59                  Defaults to false.
60
61                max_size = integer() > 0 | unlimited:
62                  A positive integer representing the absolute maximum size  a
63                  string returned from this formatter can have. If the format‐
64                  ted string  is  longer,  after  possibly  being  limited  by
65                  chars_limit or depth, it is truncated.
66
67                  Defaults to unlimited.
68
69                report_cb = logger:report_cb():
70                  A  report callback is used by the formatter to transform log
71                  messages on report form to a format  string  and  arguments.
72                  The report callback can be specified in the metadata for the
73                  log event. If no report callback exists  in  metadata,  log‐
74                  ger_formatter  will  use  logger:format_report/1  as default
75                  callback.
76
77                  If this configuration parameter is set, it replaces both the
78                  default  report  callback,  and any report callback found in
79                  metadata. That is, all reports are converted by this config‐
80                  ured function.
81
82                single_line = boolean():
83                  If  set to true, each log event is printed as a single line.
84                  To achieve this, logger_formatter sets the field width to  0
85                  for  all  ~p and ~P control sequences in the format a string
86                  (see io:format/2), and replaces all newlines in the  message
87                  with  ",  ".  White spaces following directly after newlines
88                  are removed. Notice that newlines added by the template  pa‐
89                  rameter are not replaced.
90
91                  Defaults to true.
92
93                template = template():
94                  The  template describes how the formatted string is composed
95                  by combining different data values from the log  event.  See
96                  the  description of the template() type for more information
97                  about this.
98
99                time_designator = byte():
100                  Timestamps are formatted according to RFC3339, and the  time
101                  designator is the character used as date and time separator.
102
103                  Defaults to $T.
104
105                  The  value  of this parameter is used as the time_designator
106                  option to calendar:system_time_to_rcf3339/2.
107
108                time_offset = integer() | [byte()]:
109                  The time offset, either a string or an integer, to  be  used
110                  when formatting the timestamp.
111
112                  An  empty  string  is  interpreted as local time. The values
113                  "Z", "z" or 0 are interpreted as Universal Coordinated  Time
114                  (UTC).
115
116                  Strings,  other  than  "Z",  "z", or "", must be on the form
117                  ±[hh]:[mm], for example "-02:00" or "+00:00".
118
119                  Integers must be in microseconds, meaning  that  the  offset
120                  7200000000 is equivalent to "+02:00".
121
122                  Defaults  to  an  empty  string, meaning that timestamps are
123                  displayed in local time. However, for backwards  compatibil‐
124                  ity,  if  the SASL configuration parameter utc_log=true, the
125                  default is changed to "Z", meaning that timestamps are  dis‐
126                  played in UTC.
127
128                  The  value of this parameter is used as the offset option to
129                  calendar:system_time_to_rcf3339/2.
130
131       metakey() = atom() | [atom()]
132
133       template() =
134           [metakey() |
135            {metakey(), template(), template()} |
136            unicode:chardata()]
137
138              The template is a list of atoms, atom lists, tuples and strings.
139              The  atoms  level  or  msg,  are treated as placeholders for the
140              severity level and the log message, respectively. Other atoms or
141              atom  lists  are interpreted as placeholders for metadata, where
142              atoms are expected to match top level keys, and atom lists  rep‐
143              resent  paths to sub keys when the metadata is a nested map. For
144              example the list [key1,key2] is replaced by  the  value  of  the
145              key2  field in the nested map below. The atom key1 on its own is
146              replaced by the complete value of the key1 field. The values are
147              converted to strings.
148
149              #{key1 => #{key2 => my_value,
150                          ...}
151                ...}
152
153              Tuples in the template express if-exist tests for metadata keys.
154              For example, the following tuple says that if key1 exists in the
155              metadata  map, print "key1=Value", where Value is the value that
156              key1 is associated with in the metadata map. If  key1  does  not
157              exist, print nothing.
158
159              {key1, ["key1=",key1], []}
160
161              Strings in the template are printed literally.
162
163              The  default  value for the template configuration parameter de‐
164              pends on the value of the single_line and legacy_header configu‐
165              ration parameters as follows.
166
167              The log event used in the examples is:
168
169              ?LOG_ERROR("name: ~p~nexit_reason: ~p", [my_name, "It crashed"])
170
171                legacy_header = true, single_line = false:
172                  Default template: [[logger_formatter,header],"\n",msg,"\n"]
173
174                  Example log entry:
175
176                =ERROR REPORT==== 17-May-2018::18:30:19.453447 ===
177                name: my_name
178                exit_reason: "It crashed"
179
180                  Notice  that  all eight levels can occur in the heading, not
181                  only ERROR, WARNING or INFO as  error_logger  produces.  And
182                  microseconds are added at the end of the timestamp.
183
184                legacy_header = true, single_line = true:
185                  Default template: [[logger_formatter,header],"\n",msg,"\n"]
186
187                  Notice  that  the  template  is  here  the  same as for sin‐
188                  gle_line=false, but the resulting log entry differs in  that
189                  there is only one line after the heading:
190
191                =ERROR REPORT==== 17-May-2018::18:31:06.952665 ===
192                name: my_name, exit_reason: "It crashed"
193
194                legacy_header = false, single_line = true:
195                  Default template: [time," ",level,": ",msg,"\n"]
196
197                  Example log entry:
198
199                2018-05-17T18:31:31.152864+02:00 error: name: my_name, exit_reason: "It crashed"
200
201                legacy_header = false, single_line = false:
202                  Default template: [time," ",level,":\n",msg,"\n"]
203
204                  Example log entry:
205
206                2018-05-17T18:32:20.105422+02:00 error:
207                name: my_name
208                exit_reason: "It crashed"
209

EXPORTS

211       check_config(Config) -> ok | {error, term()}
212
213              Types:
214
215                 Config = config()
216
217              The  function  is called by Logger when the formatter configura‐
218              tion for a handler is set or modified. It returns ok if the con‐
219              figuration is valid, and {error,term()} if it is faulty.
220
221              The following Logger API functions can trigger this callback:
222
223                * logger:add_handler/3
224
225                * logger:set_handler_config/2,3
226
227                * logger:update_handler_config/2
228
229                * logger:update_formatter_config/2
230
231       format(LogEvent, Config) -> unicode:chardata()
232
233              Types:
234
235                 LogEvent = logger:log_event()
236                 Config = config()
237
238              This the formatter callback function to be called from handlers.
239              The log event is processed as follows:
240
241                * If the message is on report form, it is converted  to  {For‐
242                  mat,Args}  by  calling  the report callback. See section Log
243                  Message in the Kernel  User's  Guide  for  more  information
244                  about report callbacks and valid forms of log messages.
245
246                * The  message size is limited according to the values of con‐
247                  figuration parameters chars_limit and depth.
248
249                * The full log entry is composed according to the template.
250
251                * If the final string is too long, it is  truncated  according
252                  to the value of configuration parameter max_size.
253

SEE ALSO

255       calendar(3),  error_logger(3),  io(3),  io_lib(3),  logger(3), maps(3),
256       sasl(6), unicode(3)
257
258
259
260Ericsson AB                      kernel 8.1.3              logger_formatter(3)
Impressum