1error_logger(3) Erlang Module Definition error_logger(3)
2
6 error_logger - Erlang error logger.
7
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 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 See logger(3) and the Logging chapter in the User's Guide for more in‐
21 formation.
22 The Erlang error logger is an event manager (see OTP Design Principles
25 and gen_event(3)), registered as error_logger.
26 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 User-defined event handlers can be added to handle application-specific
34 events.
35 Existing event handlers provided by STDLIB and SASL are still avail‐
37 able, but are no longer used by OTP.
38 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
46 report() =
47 [{Tag :: term(), Data :: term()} | term()] | string() | term()
48
50 add_report_handler(Handler) -> any()
51 add_report_handler(Handler, Args) -> Result
53 Types:
55 Handler = module()
57 Args = gen_event:handler_args()
58 Result = gen_event:add_handler_ret()
59 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 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 The event handler must be able to handle the events in this mod‐
70 ule, see section Events.
71 The first time this function is called, error_logger is added as
73 a Logger handler, and the error_logger process is started.
74 delete_report_handler(Handler) -> Result
76 Types:
78 Handler = module()
80 Result = gen_event:del_handler_ret()
81 Deletes an event handler from the error logger by calling
83 gen_event:delete_handler(error_logger, Handler, []), see
84 gen_event(3).
85 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 error_msg(Format) -> ok
91 error_msg(Format, Data) -> ok
93 format(Format, Data) -> ok
95 Types:
97 Format = string()
99 Data = list()
100 Log a standard error event. The Format and Data arguments are
102 the same as the arguments of io:format/2 in STDLIB.
103 Error logger forwards the event to Logger, including metadata
105 that allows backwards compatibility with legacy error logger
106 event handlers.
107 The event is handled by the default Logger handler.
109 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 Example:
115 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 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 error_report(Report) -> ok
128 Types:
130 Report = report()
132 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 The event is handled by the default Logger handler.
138 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 Example:
144 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 error_report(Type, Report) -> ok
157 Types:
159 Type = term()
161 Report = report()
162 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 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 It is recommended that Report follows the same structure as for
173 error_report/1.
174 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 get_format_depth() -> unlimited | integer() >= 1
180 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 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 info_msg(Format) -> ok
193 info_msg(Format, Data) -> ok
195 Types:
197 Format = string()
199 Data = list()
200 Log a standard information event. The Format and Data arguments
202 are the same as the arguments of io:format/2 in STDLIB.
203 Error logger forwards the event to Logger, including metadata
205 that allows backwards compatibility with legacy error logger
206 event handlers.
207 The event is handled by the default Logger handler.
209 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 Example:
215 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 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 info_report(Report) -> ok
228 Types:
230 Report = report()
232 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 The event is handled by the default Logger handler.
238 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 Example:
244 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 info_report(Type, Report) -> ok
257 Types:
259 Type = any()
261 Report = report()
262 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 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 It is recommended that Report follows the same structure as for
273 info_report/1.
274 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 logfile(Request :: {open, Filename}) -> ok | {error, OpenReason}
280 logfile(Request :: close) -> ok | {error, CloseReason}
282 logfile(Request :: filename) -> Filename | {error, FilenameReason}
284 Types:
286 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 Enables or disables printout of standard events to a file.
294 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 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 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 Request is one of the following:
311 {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 close:
320 Closes the current log file. Returns ok, or {error, mod‐
321 ule_not_found}.
322 filename:
324 Returns the name of the log file Filename, or {error,
325 no_log_file} if logging to file is not enabled.
326 tty(Flag) -> ok
328 Types:
330 Flag = boolean()
332 Enables (Flag == true) or disables (Flag == false) printout of
334 standard events to the terminal.
335 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 warning_map() -> Tag
343 Types:
345 Tag = error | warning | info
347 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 Example:
354 os$ erl
356 Erlang (BEAM) emulator version 5.4.8 [hipe] [threads:0] [kernel-poll]
357 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 =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 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 =ERROR REPORT==== 11-Aug-2005::15:31:23 ===
378 Warnings tagged as: error
379 ok
380 warning_msg(Format) -> ok
382 warning_msg(Format, Data) -> ok
384 Types:
386 Format = string()
388 Data = list()
389 Log a standard warning event. The Format and Data arguments are
391 the same as the arguments of io:format/2 in STDLIB.
392 Error logger forwards the event to Logger, including metadata
394 that allows backwards compatibility with legacy error logger
395 event handlers.
396 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 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 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 warning_report(Report) -> ok
411 Types:
413 Report = report()
415 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 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 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 warning_report(Type, Report) -> ok
428 Types:
430 Type = any()
432 Report = report()
433 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 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 The log level can be changed to error or info, see warn‐
444 ing_map/0.
445 It is recommended that Report follows the same structure as for
447 warning_report/1.
448 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
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 {error, Gleader, {Pid, Format, Data}}:
459 Generated when error_msg/1,2 or format is called.
460 {error_report, Gleader, {Pid, std_error, Report}}:
462 Generated when error_report/1 is called.
463 {error_report, Gleader, {Pid, Type, Report}}:
465 Generated when error_report/2 is called.
466 {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 {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 {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 {info_msg, Gleader, {Pid, Format, Data}}:
480 Generated when info_msg/1,2 is called.
481 {info_report, Gleader, {Pid, std_info, Report}}:
483 Generated when info_report/1 is called.
484 {info_report, Gleader, {Pid, Type, Report}}:
486 Generated when info_report/2 is called.
487 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
495 gen_event(3), logger(3), log_mf_h(3), kernel(6), sasl(6)
496Ericsson AB kernel 9.1 error_logger(3)