1error_logger(3) Erlang Module Definition error_logger(3)
2
6 error_logger - Erlang error logger.
7
9 The Erlang error logger is an event manager (see OTP Design Principles
10 and gen_event(3)), registered as error_logger. Errors, warnings, and
11 info events are sent to the error logger from the Erlang runtime system
12 and the different Erlang/OTP applications. The events are, by default,
13 logged to the terminal. Notice that an event from a process P is logged
14 at the node of the group leader of P. This means that log output is
15 directed to the node from which a process was created, which not neces‐
16 sarily is the same node as where it is executing.
17 Initially, error_logger has only a primitive event handler, which buf‐
19 fers and prints the raw event messages. During system startup, the Ker‐
20 nel application replaces this with a standard event handler, by default
21 one that writes nicely formatted output to the terminal. Kernel can
22 also be configured so that events are logged to a file instead, or not
23 logged at all, see kernel(6).
24 Also the SASL application, if started, adds its own event handler,
26 which by default writes supervisor, crash, and progress reports to the
27 terminal. See sasl(6).
28 It is recommended that user-defined applications report errors through
30 the error logger to get uniform reports. User-defined event handlers
31 can be added to handle application-specific events, see add_report_han‐
32 dler/1,2. Also, a useful event handler is provided in STDLIB for multi-
33 file logging of events, see log_mf_h(3).
34 Warning events were introduced in Erlang/OTP R9C and are enabled by
36 default as from Erlang/OTP 18.0. To retain backwards compatibility with
37 existing user-defined event handlers, the warning events can be tagged
38 as errors or info using command-line flag +W <e | i | w>, thus showing
39 up as ERROR REPORT or INFO REPORT in the logs.
40
42 report() =
43 [{Tag :: term(), Data :: term()} | term()] | string() | term()
44
46 add_report_handler(Handler) -> any()
47 add_report_handler(Handler, Args) -> Result
49 Types:
51 Handler = module()
53 Args = gen_event:handler_args()
54 Result = gen_event:add_handler_ret()
55 Adds a new event handler to the error logger. The event handler
57 must be implemented as a gen_event callback module, see
58 gen_event(3).
59 Handler is typically the name of the callback module and Args is
61 an optional term (defaults to []) passed to the initialization
62 callback function Handler:init/1. The function returns ok if
63 successful.
64 The event handler must be able to handle the events in this mod‐
66 ule, see section Events.
67 delete_report_handler(Handler) -> Result
69 Types:
71 Handler = module()
73 Result = gen_event:del_handler_ret()
74 Deletes an event handler from the error logger by calling
76 gen_event:delete_handler(error_logger, Handler, []), see
77 gen_event(3).
78 error_msg(Format) -> ok
80 error_msg(Format, Data) -> ok
82 format(Format, Data) -> ok
84 Types:
86 Format = string()
88 Data = list()
89 Sends a standard error event to the error logger. The Format and
91 Data arguments are the same as the arguments of io:format/2 in
92 STDLIB. The event is handled by the standard event handler.
93 Example:
95 1> error_logger:error_msg("An error occurred in ~p~n", [a_module]).
97 =ERROR REPORT==== 11-Aug-2005::14:03:19 ===
99 An error occurred in a_module
100 ok
101 Warning:
103 If called with bad arguments, this function can crash the stan‐
104 dard event handler, meaning no further events are logged. When
105 in doubt, use error_report/1 instead.
106 Warning:
109 If the Unicode translation modifier (t) is used in the format
110 string, all error handlers must ensure that the formatted output
111 is correctly encoded for the I/O device.
112 error_report(Report) -> ok
115 Types:
117 Report = report()
119 Sends a standard error report event to the error logger. The
121 event is handled by the standard event handler.
122 Example:
124 2> error_logger:error_report([{tag1,data1},a_term,{tag2,data}]).
126 =ERROR REPORT==== 11-Aug-2005::13:45:41 ===
128 tag1: data1
129 a_term
130 tag2: data
131 ok
132 3> error_logger:error_report("Serious error in my module").
133 =ERROR REPORT==== 11-Aug-2005::13:45:49 ===
135 Serious error in my module
136 ok
137 error_report(Type, Report) -> ok
139 Types:
141 Type = term()
143 Report = report()
144 Sends a user-defined error report event to the error logger. An
146 event handler to handle the event is supposed to have been
147 added. The event is ignored by the standard event handler.
148 It is recommended that Report follows the same structure as for
150 error_report/1.
151 get_format_depth() -> unlimited | integer() >= 1
153 Returns max(10, Depth), where Depth is the value of error_log‐
155 ger_format_depth in the Kernel application, if Depth is an inte‐
156 ger. Otherwise, unlimited is returned.
157 info_msg(Format) -> ok
159 info_msg(Format, Data) -> ok
161 Types:
163 Format = string()
165 Data = list()
166 Sends a standard information event to the error logger. The For‐
168 mat and Data arguments are the same as the arguments of io:for‐
169 mat/2 in STDLIB. The event is handled by the standard event han‐
170 dler.
171 Example:
173 1> error_logger:info_msg("Something happened in ~p~n", [a_module]).
175 =INFO REPORT==== 11-Aug-2005::14:06:15 ===
177 Something happened in a_module
178 ok
179 Warning:
181 If called with bad arguments, this function can crash the stan‐
182 dard event handler, meaning no further events are logged. When
183 in doubt, use info_report/1 instead.
184 Warning:
187 If the Unicode translation modifier (t) is used in the format
188 string, all error handlers must ensure that the formatted output
189 is correctly encoded for the I/O device.
190 info_report(Report) -> ok
193 Types:
195 Report = report()
197 Sends a standard information report event to the error logger.
199 The event is handled by the standard event handler.
200 Example:
202 2> error_logger:info_report([{tag1,data1},a_term,{tag2,data}]).
204 =INFO REPORT==== 11-Aug-2005::13:55:09 ===
206 tag1: data1
207 a_term
208 tag2: data
209 ok
210 3> error_logger:info_report("Something strange happened").
211 =INFO REPORT==== 11-Aug-2005::13:55:36 ===
213 Something strange happened
214 ok
215 info_report(Type, Report) -> ok
217 Types:
219 Type = any()
221 Report = report()
222 Sends a user-defined information report event to the error log‐
224 ger. An event handler to handle the event is supposed to have
225 been added. The event is ignored by the standard event handler.
226 It is recommended that Report follows the same structure as for
228 info_report/1.
229 logfile(Request :: {open, Filename}) -> ok | {error, OpenReason}
231 logfile(Request :: close) -> ok | {error, CloseReason}
233 logfile(Request :: filename) -> Filename | {error, FilenameReason}
235 Types:
237 Filename = file:name()
239 OpenReason = allready_have_logfile | open_error()
240 CloseReason = module_not_found
241 FilenameReason = no_log_file
242 open_error() = file:posix() | badarg | system_limit
243 Enables or disables printout of standard events to a file.
245 This is done by adding or deleting the standard event handler
247 for output to file. Thus, calling this function overrides the
248 value of the Kernel error_logger configuration parameter.
249 Enabling file logging can be used together with calling
251 tty(false), to have a silent system where all standard events
252 are logged to a file only. Only one log file can be active at a
253 time.
254 Request is one of the following:
256 {open, Filename}:
258 Opens log file Filename. Returns ok if successful, or
259 {error, allready_have_logfile} if logging to file is already
260 enabled, or an error tuple if another error occurred (for
261 example, if Filename cannot be opened). The file is opened
262 with encoding UTF-8.
263 close:
265 Closes the current log file. Returns ok, or {error, mod‐
266 ule_not_found}.
267 filename:
269 Returns the name of the log file Filename, or {error,
270 no_log_file} if logging to file is not enabled.
271 tty(Flag) -> ok
273 Types:
275 Flag = boolean()
277 Enables (Flag == true) or disables (Flag == false) printout of
279 standard events to the terminal.
280 This is done by adding or deleting the standard event handler
282 for output to the terminal. Thus, calling this function over‐
283 rides the value of the Kernel error_logger configuration parame‐
284 ter.
285 warning_map() -> Tag
287 Types:
289 Tag = error | warning | info
291 Returns the current mapping for warning events. Events sent
293 using warning_msg/1,2 or warning_report/1,2 are tagged as
294 errors, warnings (default), or info, depending on the value of
295 command-line flag +W.
296 Example:
298 os$ erl
300 Erlang (BEAM) emulator version 5.4.8 [hipe] [threads:0] [kernel-poll]
301 Eshell V5.4.8 (abort with ^G)
303 1> error_logger:warning_map().
304 warning
305 2> error_logger:warning_msg("Warnings tagged as: ~p~n", [warning]).
306 =WARNING REPORT==== 11-Aug-2005::15:31:55 ===
308 Warnings tagged as: warning
309 ok
310 3>
311 User switch command
312 --> q
313 os$ erl +W e
314 Erlang (BEAM) emulator version 5.4.8 [hipe] [threads:0] [kernel-poll]
315 Eshell V5.4.8 (abort with ^G)
317 1> error_logger:warning_map().
318 error
319 2> error_logger:warning_msg("Warnings tagged as: ~p~n", [error]).
320 =ERROR REPORT==== 11-Aug-2005::15:31:23 ===
322 Warnings tagged as: error
323 ok
324 warning_msg(Format) -> ok
326 warning_msg(Format, Data) -> ok
328 Types:
330 Format = string()
332 Data = list()
333 Sends a standard warning event to the error logger. The Format
335 and Data arguments are the same as the arguments of io:format/2
336 in STDLIB. The event is handled by the standard event handler.
337 It is tagged as an error, warning, or info, see warning_map/0.
338 Warning:
340 If called with bad arguments, this function can crash the stan‐
341 dard event handler, meaning no further events are logged. When
342 in doubt, use warning_report/1 instead.
343 Warning:
346 If the Unicode translation modifier (t) is used in the format
347 string, all error handlers must ensure that the formatted output
348 is correctly encoded for the I/O device.
349 warning_report(Report) -> ok
352 Types:
354 Report = report()
356 Sends a standard warning report event to the error logger. The
358 event is handled by the standard event handler. It is tagged as
359 an error, warning, or info, see warning_map/0.
360 warning_report(Type, Report) -> ok
362 Types:
364 Type = any()
366 Report = report()
367 Sends a user-defined warning report event to the error logger.
369 An event handler to handle the event is supposed to have been
370 added. The event is ignored by the standard event handler. It is
371 tagged as an error, warning, or info, depending on the value of
372 warning_map/0.
373
375 All event handlers added to the error logger must handle the following
376 events. Gleader is the group leader pid of the process that sent the
377 event, and Pid is the process that sent the event.
378 {error, Gleader, {Pid, Format, Data}}:
380 Generated when error_msg/1,2 or format is called.
381 {error_report, Gleader, {Pid, std_error, Report}}:
383 Generated when error_report/1 is called.
384 {error_report, Gleader, {Pid, Type, Report}}:
386 Generated when error_report/2 is called.
387 {warning_msg, Gleader, {Pid, Format, Data}}:
389 Generated when warning_msg/1,2 is called if warnings are set to be
390 tagged as warnings.
391 {warning_report, Gleader, {Pid, std_warning, Report}}:
393 Generated when warning_report/1 is called if warnings are set to be
394 tagged as warnings.
395 {warning_report, Gleader, {Pid, Type, Report}}:
397 Generated when warning_report/2 is called if warnings are set to be
398 tagged as warnings.
399 {info_msg, Gleader, {Pid, Format, Data}}:
401 Generated when info_msg/1,2 is called.
402 {info_report, Gleader, {Pid, std_info, Report}}:
404 Generated when info_report/1 is called.
405 {info_report, Gleader, {Pid, Type, Report}}:
407 Generated when info_report/2 is called.
408 Notice that some system-internal events can also be received. Therefore
410 a catch-all clause last in the definition of the event handler callback
411 function Module:handle_event/2 is necessary. This also applies for Mod‐
412 ule:handle_info/2, as the event handler must also take care of some
413 system-internal messages.
414
416 gen_event(3), log_mf_h(3) kernel(6) sasl(6)
417Ericsson AB kernel 5.4.3.2 error_logger(3)