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

NAME

6       error_logger - Erlang error logger.
7

DESCRIPTION

9   Note:
10       In Erlang/OTP 21.0, a new API for logging was added. The old error_log‐
11       ger module can still be used by legacy code, but log events  are  redi‐
12       rected  to  the  new Logger API. New code should use the Logger API di‐
13       rectly.
14
15       error_logger is no longer started  by  default,  but  is  automatically
16       started  when  an  event  handler  is  added  with error_logger:add_re‐
17       port_handler/1,2. The error_logger module is then also added as a  han‐
18       dler to the new logger.
19
20       See  logger(3) and the Logging chapter in the User's Guide for more in‐
21       formation.
22
23
24       The Erlang error logger is an event manager (see OTP Design  Principles
25       and gen_event(3)), registered as error_logger.
26
27       Error  logger  is  no  longer  started by default, but is automatically
28       started when an event handler is added with add_report_handler/1,2. The
29       error_logger  module is then also added as a handler to the new logger,
30       causing log events to be forwarded from logger  to  error  logger,  and
31       consequently to all installed error logger event handlers.
32
33       User-defined event handlers can be added to handle application-specific
34       events.
35
36       Existing event handlers provided by STDLIB and SASL  are  still  avail‐
37       able, but are no longer used by OTP.
38
39       Warning events were introduced in Erlang/OTP R9C and are enabled by de‐
40       fault as from Erlang/OTP 18.0. To retain backwards  compatibility  with
41       existing  user-defined event handlers, the warning events can be tagged
42       as errors or info using command-line flag +W <e | i | w>, thus  showing
43       up as ERROR REPORT or INFO REPORT in the logs.
44

DATA TYPES

46       report() =
47           [{Tag :: term(), Data :: term()} | term()] | string() | term()
48

EXPORTS

50       add_report_handler(Handler) -> any()
51
52       add_report_handler(Handler, Args) -> Result
53
54              Types:
55
56                 Handler = module()
57                 Args = gen_event:handler_args()
58                 Result = gen_event:add_handler_ret()
59
60              Adds  a new event handler to the error logger. The event handler
61              must  be  implemented  as  a  gen_event  callback  module,   see
62              gen_event(3).
63
64              Handler is typically the name of the callback module and Args is
65              an optional term (defaults to []) passed to  the  initialization
66              callback  function  Handler:init/1.  The  function returns ok if
67              successful.
68
69              The event handler must be able to handle the events in this mod‐
70              ule, see section Events.
71
72              The first time this function is called, error_logger is added as
73              a Logger handler, and the error_logger process is started.
74
75       delete_report_handler(Handler) -> Result
76
77              Types:
78
79                 Handler = module()
80                 Result = gen_event:del_handler_ret()
81
82              Deletes an event  handler  from  the  error  logger  by  calling
83              gen_event:delete_handler(error_logger,    Handler,    []),   see
84              gen_event(3).
85
86              If no more event handlers exist after the deletion, error_logger
87              is  removed as a Logger handler, and the error_logger process is
88              stopped.
89
90       error_msg(Format) -> ok
91
92       error_msg(Format, Data) -> ok
93
94       format(Format, Data) -> ok
95
96              Types:
97
98                 Format = string()
99                 Data = list()
100
101              Log a standard error event. The Format and  Data  arguments  are
102              the same as the arguments of io:format/2 in STDLIB.
103
104              Error  logger  forwards  the event to Logger, including metadata
105              that allows backwards compatibility  with  legacy  error  logger
106              event handlers.
107
108              The event is handled by the default Logger handler.
109
110              These  functions  are  kept for backwards compatibility and must
111              not be used by new code. Use the ?LOG_ERROR macro or  logger:er‐
112              ror/1,2,3 instead.
113
114              Example:
115
116              1> error_logger:error_msg("An error occurred in ~p", [a_module]).
117              =ERROR REPORT==== 22-May-2018::11:18:43.376917 ===
118              An error occurred in a_module
119              ok
120
121          Warning:
122              If  the  Unicode  translation modifier (t) is used in the format
123              string, all event handlers must ensure that the formatted output
124              is correctly encoded for the I/O device.
125
126
127       error_report(Report) -> ok
128
129              Types:
130
131                 Report = report()
132
133              Log  a  standard error event. Error logger forwards the event to
134              Logger, including metadata that allows  backwards  compatibility
135              with legacy error logger event handlers.
136
137              The event is handled by the default Logger handler.
138
139              This  functions is kept for backwards compatibility and must not
140              be used by new code. Use  the  ?LOG_ERROR  macro  or  logger:er‐
141              ror/1,2,3 instead.
142
143              Example:
144
145              2> error_logger:error_report([{tag1,data1},a_term,{tag2,data}]).
146              =ERROR REPORT==== 22-May-2018::11:24:23.699306 ===
147                  tag1: data1
148                  a_term
149                  tag2: data
150              ok
151              3> error_logger:error_report("Serious error in my module").
152              =ERROR REPORT==== 22-May-2018::11:24:45.972445 ===
153              Serious error in my module
154              ok
155
156       error_report(Type, Report) -> ok
157
158              Types:
159
160                 Type = term()
161                 Report = report()
162
163              Log  a user-defined error event. Error logger forwards the event
164              to Logger, including metadata that allows backwards  compatibil‐
165              ity with legacy error logger event handlers.
166
167              Error  logger also adds a domain field with value [Type] to this
168              event's metadata, causing the filters of the default Logger han‐
169              dler to discard the event. A different Logger handler, or an er‐
170              ror logger event handler, must be added to handle this event.
171
172              It is recommended that Report follows the same structure as  for
173              error_report/1.
174
175              This  functions is kept for backwards compatibility and must not
176              be used by new code. Use  the  ?LOG_ERROR  macro  or  logger:er‐
177              ror/1,2,3 instead.
178
179       get_format_depth() -> unlimited | integer() >= 1
180
181              Returns  max(10,  Depth), where Depth is the value of error_log‐
182              ger_format_depth in the Kernel application, if Depth is an inte‐
183              ger. Otherwise, unlimited is returned.
184
185          Note:
186              The  error_logger_format_depth variable is  deprecated since the
187              Logger API was introduced in Erlang/OTP 21.0. The variable,  and
188              this  function,  are kept for backwards compatibility since they
189              still might be used by legacy report handlers.
190
191
192       info_msg(Format) -> ok
193
194       info_msg(Format, Data) -> ok
195
196              Types:
197
198                 Format = string()
199                 Data = list()
200
201              Log a standard information event. The Format and Data  arguments
202              are the same as the arguments of io:format/2 in STDLIB.
203
204              Error  logger  forwards  the event to Logger, including metadata
205              that allows backwards compatibility  with  legacy  error  logger
206              event handlers.
207
208              The event is handled by the default Logger handler.
209
210              These  functions  are  kept for backwards compatibility and must
211              not be used by  new  code.  Use  the  ?LOG_INFO  macro  or  log‐
212              ger:info/1,2,3 instead.
213
214              Example:
215
216              1> error_logger:info_msg("Something happened in ~p", [a_module]).
217              =INFO REPORT==== 22-May-2018::12:03:32.612462 ===
218              Something happened in a_module
219              ok
220
221          Warning:
222              If  the  Unicode  translation modifier (t) is used in the format
223              string, all event handlers must ensure that the formatted output
224              is correctly encoded for the I/O device.
225
226
227       info_report(Report) -> ok
228
229              Types:
230
231                 Report = report()
232
233              Log  a  standard  information  event.  Error logger forwards the
234              event to Logger, including metadata that allows  backwards  com‐
235              patibility with legacy error logger event handlers.
236
237              The event is handled by the default Logger handler.
238
239              This  functions is kept for backwards compatibility and must not
240              be  used  by  new  code.  Use  the  ?LOG_INFO  macro   or   log‐
241              ger:info/1,2,3 instead.
242
243              Example:
244
245              2> error_logger:info_report([{tag1,data1},a_term,{tag2,data}]).
246              =INFO REPORT==== 22-May-2018::12:06:35.994440 ===
247                  tag1: data1
248                  a_term
249                  tag2: data
250              ok
251              3> error_logger:info_report("Something strange happened").
252              =INFO REPORT==== 22-May-2018::12:06:49.066872 ===
253              Something strange happened
254              ok
255
256       info_report(Type, Report) -> ok
257
258              Types:
259
260                 Type = any()
261                 Report = report()
262
263              Log  a user-defined information event. Error logger forwards the
264              event to Logger, including metadata that allows  backwards  com‐
265              patibility with legacy error logger event handlers.
266
267              Error  logger also adds a domain field with value [Type] to this
268              event's metadata, causing the filters of the default Logger han‐
269              dler to discard the event. A different Logger handler, or an er‐
270              ror logger event handler, must be added to handle this event.
271
272              It is recommended that Report follows the same structure as  for
273              info_report/1.
274
275              This  functions is kept for backwards compatibility and must not
276              be  used  by  new  code.  Use  the  ?LOG_INFO  macro   or   log‐
277              ger:info/1,2,3 instead.
278
279       logfile(Request :: {open, Filename}) -> ok | {error, OpenReason}
280
281       logfile(Request :: close) -> ok | {error, CloseReason}
282
283       logfile(Request :: filename) -> Filename | {error, FilenameReason}
284
285              Types:
286
287                 Filename = file:name()
288                 OpenReason = allready_have_logfile | open_error()
289                 CloseReason = module_not_found
290                 FilenameReason = no_log_file
291                 open_error() = file:posix() | badarg | system_limit
292
293              Enables or disables printout of standard events to a file.
294
295              This is done by adding or deleting the error_logger_file_h event
296              handler, and thus indirectly adding  error_logger  as  a  Logger
297              handler.
298
299              Notice that this function does not manipulate the Logger config‐
300              uration directly, meaning that if the default Logger handler  is
301              already  logging  to a file, this function can potentially cause
302              logging to a second file.
303
304              This function is useful as a  shortcut  during  development  and
305              testing,  but  must not be used in a production system. See sec‐
306              tion Logging in the Kernel User's Guide, and the logger(3)  man‐
307              ual  page for information about how to configure Logger for live
308              systems.
309
310              Request is one of the following:
311
312                {open, Filename}:
313                  Opens log file Filename. Returns ok if successful,  or  {er‐
314                  ror,  allready_have_logfile}  if  logging to file is already
315                  enabled, or an error tuple if another  error  occurred  (for
316                  example,  if  Filename cannot be opened). The file is opened
317                  with encoding UTF-8.
318
319                close:
320                  Closes the current log file. Returns  ok,  or  {error,  mod‐
321                  ule_not_found}.
322
323                filename:
324                  Returns  the  name  of  the  log  file  Filename, or {error,
325                  no_log_file} if logging to file is not enabled.
326
327       tty(Flag) -> ok
328
329              Types:
330
331                 Flag = boolean()
332
333              Enables (Flag == true) or disables (Flag == false)  printout  of
334              standard events to the terminal.
335
336              This is done by manipulating the Logger configuration. The func‐
337              tion is useful as a shortcut during development and testing, but
338              must  not be used in a production system. See section Logging in
339              the Kernel User's Guide, and the logger(3) manual page  for  in‐
340              formation about how to configure Logger for live systems.
341
342       warning_map() -> Tag
343
344              Types:
345
346                 Tag = error | warning | info
347
348              Returns  the current mapping for warning events. Events sent us‐
349              ing warning_msg/1,2 or warning_report/1,2 are tagged as  errors,
350              warnings  (default), or info, depending on the value of command-
351              line flag +W.
352
353              Example:
354
355              os$ erl
356              Erlang (BEAM) emulator version 5.4.8 [hipe] [threads:0] [kernel-poll]
357
358              Eshell V5.4.8  (abort with ^G)
359              1> error_logger:warning_map().
360              warning
361              2> error_logger:warning_msg("Warnings tagged as: ~p~n", [warning]).
362
363              =WARNING REPORT==== 11-Aug-2005::15:31:55 ===
364              Warnings tagged as: warning
365              ok
366              3>
367              User switch command
368               --> q
369              os$ erl +W e
370              Erlang (BEAM) emulator version 5.4.8 [hipe] [threads:0] [kernel-poll]
371
372              Eshell V5.4.8  (abort with ^G)
373              1> error_logger:warning_map().
374              error
375              2> error_logger:warning_msg("Warnings tagged as: ~p~n", [error]).
376
377              =ERROR REPORT==== 11-Aug-2005::15:31:23 ===
378              Warnings tagged as: error
379              ok
380
381       warning_msg(Format) -> ok
382
383       warning_msg(Format, Data) -> ok
384
385              Types:
386
387                 Format = string()
388                 Data = list()
389
390              Log a standard warning event. The Format and Data arguments  are
391              the same as the arguments of io:format/2 in STDLIB.
392
393              Error  logger  forwards  the event to Logger, including metadata
394              that allows backwards compatibility  with  legacy  error  logger
395              event handlers.
396
397              The  event  is  handled  by  the default Logger handler. The log
398              level can be changed to error or info, see warning_map/0.
399
400              These functions are kept for backwards  compatibility  and  must
401              not  be  used  by  new  code. Use the ?LOG_WARNING macro or log‐
402              ger:warning/1,2,3 instead.
403
404          Warning:
405              If the Unicode translation modifier (t) is used  in  the  format
406              string, all event handlers must ensure that the formatted output
407              is correctly encoded for the I/O device.
408
409
410       warning_report(Report) -> ok
411
412              Types:
413
414                 Report = report()
415
416              Log a standard warning event. Error logger forwards the event to
417              Logger,  including  metadata that allows backwards compatibility
418              with legacy error logger event handlers.
419
420              The event is handled by the  default  Logger  handler.  The  log
421              level can be changed to error or info, see warning_map/0.
422
423              This  functions is kept for backwards compatibility and must not
424              be used by new code. Use the ?LOG_WARNING macro or  logger:warn‐
425              ing/1,2,3 instead.
426
427       warning_report(Type, Report) -> ok
428
429              Types:
430
431                 Type = any()
432                 Report = report()
433
434              Log  a  user-defined  warning  event.  Error logger forwards the
435              event to Logger, including metadata that allows  backwards  com‐
436              patibility with legacy error logger event handlers.
437
438              Error  logger also adds a domain field with value [Type] to this
439              event's metadata, causing the filters of the default Logger han‐
440              dler to discard the event. A different Logger handler, or an er‐
441              ror logger event handler, must be added to handle this event.
442
443              The log level can  be  changed  to  error  or  info,  see  warn‐
444              ing_map/0.
445
446              It  is recommended that Report follows the same structure as for
447              warning_report/1.
448
449              This functions is kept for backwards compatibility and must  not
450              be  used by new code. Use the ?LOG_WARNING macro or logger:warn‐
451              ing/1,2,3 instead.
452

EVENTS

454       All event handlers added to the error logger must handle the  following
455       events.  Gleader  is  the group leader pid of the process that sent the
456       event, and Pid is the process that sent the event.
457
458         {error, Gleader, {Pid, Format, Data}}:
459           Generated when error_msg/1,2 or format is called.
460
461         {error_report, Gleader, {Pid, std_error, Report}}:
462           Generated when error_report/1 is called.
463
464         {error_report, Gleader, {Pid, Type, Report}}:
465           Generated when error_report/2 is called.
466
467         {warning_msg, Gleader, {Pid, Format, Data}}:
468           Generated when warning_msg/1,2 is called if warnings are set to  be
469           tagged as warnings.
470
471         {warning_report, Gleader, {Pid, std_warning, Report}}:
472           Generated when warning_report/1 is called if warnings are set to be
473           tagged as warnings.
474
475         {warning_report, Gleader, {Pid, Type, Report}}:
476           Generated when warning_report/2 is called if warnings are set to be
477           tagged as warnings.
478
479         {info_msg, Gleader, {Pid, Format, Data}}:
480           Generated when info_msg/1,2 is called.
481
482         {info_report, Gleader, {Pid, std_info, Report}}:
483           Generated when info_report/1 is called.
484
485         {info_report, Gleader, {Pid, Type, Report}}:
486           Generated when info_report/2 is called.
487
488       Notice that some system-internal events can also be received. Therefore
489       a catch-all clause last in the definition of the event handler callback
490       function Module:handle_event/2 is necessary. This also applies for Mod‐
491       ule:handle_info/2, as the event handler must also  take  care  of  some
492       system-internal messages.
493

SEE ALSO

495       gen_event(3), logger(3), log_mf_h(3), kernel(6), sasl(6)
496
497
498
499Ericsson AB                     kernel 8.5.4.2                 error_logger(3)
Impressum