aboutsummaryrefslogtreecommitdiffstats
path: root/lib/kernel/doc/src/error_logger.xml
blob: c9fe9484e43fc98916c97ab97e04c6d52151cc7e (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE erlref SYSTEM "erlref.dtd">

<erlref>
  <header>
    <copyright>
      <year>1996</year><year>2017</year>
      <holder>Ericsson AB. All Rights Reserved.</holder>
    </copyright>
    <legalnotice>
      Licensed under the Apache License, Version 2.0 (the "License");
      you may not use this file except in compliance with the License.
      You may obtain a copy of the License at
 
          http://www.apache.org/licenses/LICENSE-2.0

      Unless required by applicable law or agreed to in writing, software
      distributed under the License is distributed on an "AS IS" BASIS,
      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
      See the License for the specific language governing permissions and
      limitations under the License.
    
    </legalnotice>

    <title>error_logger</title>
    <prepared></prepared>
    <docno></docno>
    <date></date>
    <rev></rev>
  </header>
  <module>error_logger</module>
  <modulesummary>Erlang error logger.</modulesummary>
  <description>

    <note>
      <p>In OTP-21, a new API for logging was added to Erlang/OTP. The
	old <c>error_logger</c> module can still be used by legacy
	code, but new code should use the new API instead.</p>
      <p>See  <seealso marker="logger"><c>logger(3)</c></seealso> and
	the <seealso marker="logger_chapter">Logging</seealso> chapter
	in the user's guide for more information.</p>
    </note>

    <p>The Erlang <em>error logger</em> is an event manager (see
      <seealso marker="doc/design_principles:des_princ">OTP Design Principles</seealso> and
      <seealso marker="stdlib:gen_event"><c>gen_event(3)</c></seealso>),
      registered as <c>error_logger</c>. Errors, warnings, and info events
      are sent to the error logger from the Erlang runtime system and
      the different Erlang/OTP applications. The events are, by default,
      logged to the terminal. Notice that an event from a process <c>P</c> is
      logged at the node of the group leader of <c>P</c>. This means
      that log output is directed to the node from which a process was
      created, which not necessarily is the same node as where it is
      executing.</p>
    <p>Initially, <c>error_logger</c> has only a primitive event
      handler, which buffers and prints the raw event messages. During
      system startup, the Kernel application replaces this with a
      <em>standard event handler</em>, by default one that writes
      nicely formatted output to the terminal. Kernel can also be
      configured so that events are logged to a file instead, or not logged at all,
      see <seealso marker="kernel_app"><c>kernel(6)</c></seealso>.</p>
    <p>Also the SASL application, if started, adds its own event
      handler, which by default writes supervisor, crash, and progress
      reports to the terminal. See
      <seealso marker="sasl:sasl_app"><c>sasl(6)</c></seealso>.</p>
    <p>It is recommended that user-defined applications report
      errors through the error logger to get uniform reports.
      User-defined event handlers can be added to handle application-specific
      events, see
      <seealso marker="#add_report_handler/1"><c>add_report_handler/1,2</c></seealso>.
      Also, a useful event handler is provided in STDLIB for multi-file
      logging of events, see
      <seealso marker="stdlib:log_mf_h"><c>log_mf_h(3)</c></seealso>.</p>
    <p>Warning events were introduced in Erlang/OTP R9C and are enabled
      by default as from Erlang/OTP 18.0. To retain backwards compatibility
      with existing user-defined event handlers, the warning events can be
      tagged as <c>errors</c> or <c>info</c> using command-line flag
      <c><![CDATA[+W <e | i | w>]]></c>, thus showing up as
      <c>ERROR REPORT</c> or <c>INFO REPORT</c> in the logs.</p>
  </description>
  <datatypes>
    <datatype>
      <name name="report"/>
    </datatype>
  </datatypes>
  <funcs>
    <func>
      <name name="add_report_handler" arity="1"/>
      <name name="add_report_handler" arity="2"/>
      <fsummary>Add an event handler to the error logger.</fsummary>
      <desc>
        <p>Adds a new event handler to the error logger. The event
          handler must be implemented as a <c>gen_event</c> callback
          module, see
          <seealso marker="stdlib:gen_event"><c>gen_event(3)</c></seealso>.</p>
        <p><c><anno>Handler</anno></c> is typically the name of the callback module
          and <c><anno>Args</anno></c> is an optional term (defaults to []) passed
          to the initialization callback function <c><anno>Handler</anno>:init/1</c>.
          The function returns <c>ok</c> if successful.</p>
        <p>The event handler must be able to handle the events in this module, see
          section <seealso marker="#events">Events</seealso>.</p>
      </desc>
    </func>
    <func>
      <name name="delete_report_handler" arity="1"/>
      <fsummary>Delete an event handler from the error logger.</fsummary>
      <desc>
        <p>Deletes an event handler from the error logger by calling
          <c>gen_event:delete_handler(error_logger, <anno>Handler</anno>, [])</c>,
          see <seealso marker="stdlib:gen_event"><c>gen_event(3)</c></seealso>.</p>
      </desc>
    </func>
    <func>
      <name name="error_msg" arity="1"/>
      <name name="error_msg" arity="2"/>
      <name name="format" arity="2"/>
      <fsummary>Send a standard error event to the error logger.</fsummary>
      <desc>
        <p>Sends a standard error event to the error logger.
          The <c><anno>Format</anno></c> and <c><anno>Data</anno></c> arguments
	  are the same as the arguments of
	  <seealso marker="stdlib:io#format/2"><c>io:format/2</c></seealso>
	  in STDLIB.
	  The event is handled by the standard event handler.</p>
	<p><em>Example:</em></p>
        <pre>
1> <input>error_logger:error_msg("An error occurred in ~p~n", [a_module]).</input>

=ERROR REPORT==== 11-Aug-2005::14:03:19 ===
An error occurred in a_module
ok</pre>
        <warning>
          <p>If called with bad arguments, this function can crash
            the standard event handler, meaning no further events are
            logged. When in doubt, use
	  <seealso marker="#error_report/1"><c>error_report/1</c></seealso>
	  instead.</p>
        </warning>
        <warning>
          <p>If the Unicode translation modifier (<c>t</c>) is used in
            the format string, all error handlers must ensure that the
            formatted output is correctly encoded for the I/O
            device.</p>
        </warning>
      </desc>
    </func>
    <func>
      <name name="error_report" arity="1"/>
      <fsummary>Send a standard error report event to the error logger.</fsummary>
      <desc>
        <p>Sends a standard error report event to the error logger.
          The event is handled by the standard event handler.</p>
	<p><em>Example:</em></p>
        <pre>
2> <input>error_logger:error_report([{tag1,data1},a_term,{tag2,data}]).</input>

=ERROR REPORT==== 11-Aug-2005::13:45:41 ===
    tag1: data1
    a_term
    tag2: data
ok
3> <input>error_logger:error_report("Serious error in my module").</input>

=ERROR REPORT==== 11-Aug-2005::13:45:49 ===
Serious error in my module
ok</pre>
      </desc>
    </func>
    <func>
      <name name="error_report" arity="2"/>
      <fsummary>Send a user-defined error report event to the error logger.</fsummary>
      <desc>
        <p>Sends a user-defined error report event to the error logger.
          An event handler to handle the event is supposed to have been
          added. The event is ignored by the standard event handler.</p>
        <p>It is recommended that <c><anno>Report</anno></c> follows the same
          structure as for
	<seealso marker="#error_report/1"><c>error_report/1</c></seealso>.</p>
      </desc>
    </func>
    <func>
      <name name="get_format_depth" arity="0"/>
      <fsummary>Get the value of the Kernel application variable
                <c>error_logger_format_depth</c>.</fsummary>
      <desc>
	<p>Returns <c>max(10, Depth)</c>, where <c>Depth</c> is the
	value of <c>error_logger_format_depth</c>
	in the Kernel application, if Depth is an integer. Otherwise,
	<c>unlimited</c> is returned.</p>
	<note>
	  <p>The <c>error_logger_format_depth</c> variable
	    is <seealso marker="kernel_app#deprecated-configuration-parameters">
	    deprecated</seealso> since
	    the <seealso marker="logger">Logger API</seealso> was
	    introduced in OTP-21. The variable, and this function, are
	    kept for backwards compatibility since they still might be
	    used by legacy report handlers.</p>
	</note>
      </desc>
    </func>
    <func>
      <name name="info_msg" arity="1"/>
      <name name="info_msg" arity="2"/>
      <fsummary>Send a standard information event to the error logger.</fsummary>
      <desc>
        <p>Sends a standard information event to the error logger.
          The <c><anno>Format</anno></c> and <c><anno>Data</anno></c> arguments
	  are the same as the arguments of
	  <seealso marker="stdlib:io#format/2"><c>io:format/2</c></seealso>
	  in STDLIB. The event is handled by the standard event handler.</p>
	<p><em>Example:</em></p>
        <pre>
1> <input>error_logger:info_msg("Something happened in ~p~n", [a_module]).</input>

=INFO REPORT==== 11-Aug-2005::14:06:15 ===
Something happened in a_module
ok</pre>
        <warning>
          <p>If called with bad arguments, this function can crash
            the standard event handler, meaning no further events are
            logged. When in doubt, use <c>info_report/1</c> instead.</p>
        </warning>
        <warning>
          <p>If the Unicode translation modifier (<c>t</c>) is used in
            the format string, all error handlers must ensure that the
            formatted output is correctly encoded for the I/O
            device.</p>
        </warning>
      </desc>
    </func>
    <func>
      <name name="info_report" arity="1"/>
      <fsummary>Send a standard information report event to the error logger.</fsummary>
      <desc>
        <p>Sends a standard information report event to the error
          logger. The event is handled by the standard event handler.</p>
	<p><em>Example:</em></p>
        <pre>
2> <input>error_logger:info_report([{tag1,data1},a_term,{tag2,data}]).</input>

=INFO REPORT==== 11-Aug-2005::13:55:09 ===
    tag1: data1
    a_term
    tag2: data
ok
3> <input>error_logger:info_report("Something strange happened").</input>

=INFO REPORT==== 11-Aug-2005::13:55:36 ===
Something strange happened
ok</pre>
      </desc>
    </func>
    <func>
      <name name="info_report" arity="2"/>
      <fsummary>Send a user-defined information report event to the error logger.</fsummary>
      <desc>
        <p>Sends a user-defined information report event to the error
          logger. An event handler to handle the event is supposed to
          have been added. The event is ignored by the standard event
          handler.</p>
        <p>It is recommended that <c><anno>Report</anno></c> follows the same
          structure as for
	<seealso marker="#info_report/1"><c>info_report/1</c></seealso>.</p>
      </desc>
    </func>
    <func>
      <name name="logfile" arity="1" clause_i="1"/>
      <name name="logfile" arity="1" clause_i="2"/>
      <name name="logfile" arity="1" clause_i="3"/>
      <fsummary>Enable or disable error printouts to a file.</fsummary>
      <type variable="Filename"/>
      <type variable="OpenReason" name_i="1"/>
      <type variable="CloseReason" name_i="2"/>
      <type variable="FilenameReason" name_i="3"/>
      <type name="open_error"/>
      <desc>
        <p>Enables or disables printout of standard events to a file.</p>
        <p>This is done by adding or deleting the standard event handler
          for output to file. Thus, calling this function overrides
          the value of the Kernel <c>error_logger</c> configuration
          parameter.</p>
        <p>Enabling file logging can be used together with calling
          <c>tty(false)</c>, to have a silent system where
          all standard events are logged to a file only.
          Only one log file can be active at a time.</p>
        <p><c>Request</c> is one of the following:</p>
        <taglist>
          <tag><c>{open, <anno>Filename</anno>}</c></tag>
          <item>
            <p>Opens log file <c><anno>Filename</anno></c>. Returns <c>ok</c> if
              successful, or <c>{error, allready_have_logfile}</c> if
              logging to file is already enabled, or an error tuple if
              another error occurred (for example, if <c><anno>Filename</anno></c>
              cannot be opened). The file is opened with encoding UTF-8.</p>
          </item>
          <tag><c>close</c></tag>
          <item>
            <p>Closes the current log file. Returns <c>ok</c>, or
              <c>{error, module_not_found}</c>.</p>
          </item>
          <tag><c>filename</c></tag>
          <item>
            <p>Returns the name of the log file <c><anno>Filename</anno></c>, or
              <c>{error, no_log_file}</c> if logging to file is not
              enabled.</p>
          </item>
        </taglist>
      </desc>
    </func>
    <func>
      <name name="tty" arity="1"/>
      <fsummary>Enable or disable printouts to the terminal.</fsummary>
      <desc>
        <p>Enables (<c><anno>Flag</anno> == true</c>) or disables
          (<c><anno>Flag</anno> == false</c>) printout of standard events
	  to the terminal.</p>
        <p>This is done by adding or deleting the standard event handler
          for output to the terminal. Thus, calling this function overrides
          the value of the Kernel <c>error_logger</c> configuration parameter.</p>
      </desc>
    </func>
    <func>
      <name name="warning_map" arity="0"/>
      <fsummary>Return the current mapping for warning events.</fsummary>
      <desc>
        <p>Returns the current mapping for warning events. Events sent
          using <c>warning_msg/1,2</c> or <c>warning_report/1,2</c>
          are tagged as errors, warnings (default), or info, depending
          on the value of command-line flag <c>+W</c>.</p>
	<p><em>Example:</em></p>
        <pre>
os$ <input>erl</input>
Erlang (BEAM) emulator version 5.4.8 [hipe] [threads:0] [kernel-poll]

Eshell V5.4.8  (abort with ^G)
1> <input>error_logger:warning_map().</input>
warning
2> <input>error_logger:warning_msg("Warnings tagged as: ~p~n", [warning]).</input>

=WARNING REPORT==== 11-Aug-2005::15:31:55 ===
Warnings tagged as: warning
ok
3>
User switch command
 --> q
os$ <input>erl +W e</input>
Erlang (BEAM) emulator version 5.4.8 [hipe] [threads:0] [kernel-poll]

Eshell V5.4.8  (abort with ^G)
1> <input>error_logger:warning_map().</input>
error
2> <input>error_logger:warning_msg("Warnings tagged as: ~p~n", [error]).</input>

=ERROR REPORT==== 11-Aug-2005::15:31:23 ===
Warnings tagged as: error
ok</pre>
      </desc>
    </func>
    <func>
      <name name="warning_msg" arity="1"/>
      <name name="warning_msg" arity="2"/>
      <fsummary>Send a standard warning event to the error logger.</fsummary>
      <desc>
        <p>Sends a standard warning event to the error logger.
          The <c><anno>Format</anno></c> and <c><anno>Data</anno></c> arguments
	  are the same as the arguments of
	  <seealso marker="stdlib:io#format/2"><c>io:format/2</c></seealso>
	  in STDLIB.
	  The event is handled by the standard event handler. It is tagged
	  as an error, warning, or info, see
          <seealso marker="#warning_map/0"><c>warning_map/0</c></seealso>.</p>
        <warning>
          <p>If called with bad arguments, this function can crash
            the standard event handler, meaning no further events are
            logged. When in doubt, use <c>warning_report/1</c> instead.</p>
        </warning>
        <warning>
          <p>If the Unicode translation modifier (<c>t</c>) is used in
            the format string, all error handlers must ensure that the
            formatted output is correctly encoded for the I/O
            device.</p>
        </warning>
      </desc>
    </func>
    <func>
      <name name="warning_report" arity="1"/>
      <fsummary>Send a standard warning report event to the error logger.</fsummary>
      <desc>
        <p>Sends a standard warning report event to the error logger.
          The event is handled by the standard event handler. It is
          tagged as an error, warning, or info, see
          <seealso marker="#warning_map/0"><c>warning_map/0</c></seealso>.</p>
      </desc>
    </func>
    <func>
      <name name="warning_report" arity="2"/>
      <fsummary>Send a user-defined warning report event to the error logger.</fsummary>
      <desc>
        <p>Sends a user-defined warning report event to the error
          logger. An event handler to handle the event is supposed to
          have been added. The event is ignored by the standard event
          handler. It is tagged as an error, warning, or info,
          depending on the value of
          <seealso marker="#warning_map/0"><c>warning_map/0</c></seealso>.</p>
      </desc>
    </func>
  </funcs>

  <section>
    <marker id="events"></marker>
    <title>Events</title>
    <p>All event handlers added to the error logger must handle
      the following events. <c>Gleader</c> is the group leader pid of
      the process that sent the event, and <c>Pid</c> is the process
      that sent the event.</p>
    <taglist>
      <tag><c>{error, Gleader, {Pid, Format, Data}}</c></tag>
      <item>
        <p>Generated when <c>error_msg/1,2</c> or <c>format</c> is
          called.</p>
      </item>
      <tag><c>{error_report, Gleader, {Pid, std_error, Report}}</c></tag>
      <item>
        <p>Generated when <c>error_report/1</c> is called.</p>
      </item>
      <tag><c>{error_report, Gleader, {Pid, Type, Report}}</c></tag>
      <item>
        <p>Generated when <c>error_report/2</c> is called.</p>
      </item>
      <tag><c>{warning_msg, Gleader, {Pid, Format, Data}}</c></tag>
      <item>
        <p>Generated when <c>warning_msg/1,2</c> is called
          if warnings are set to be tagged as warnings.</p>
      </item>
      <tag><c>{warning_report, Gleader, {Pid, std_warning, Report}}</c></tag>
      <item>
        <p>Generated when <c>warning_report/1</c> is called
          if warnings are set to be tagged as warnings.</p>
      </item>
      <tag><c>{warning_report, Gleader, {Pid, Type, Report}}</c></tag>
      <item>
        <p>Generated when <c>warning_report/2</c> is called
          if warnings are set to be tagged as warnings.</p>
      </item>
      <tag><c>{info_msg, Gleader, {Pid, Format, Data}}</c></tag>
      <item>
        <p>Generated when <c>info_msg/1,2</c> is called.</p>
      </item>
      <tag><c>{info_report, Gleader, {Pid, std_info, Report}}</c></tag>
      <item>
        <p>Generated when <c>info_report/1</c> is called.</p>
      </item>
      <tag><c>{info_report, Gleader, {Pid, Type, Report}}</c></tag>
      <item>
        <p>Generated when <c>info_report/2</c> is called.</p>
      </item>
    </taglist>
    <p>Notice that some system-internal events can also be
      received. Therefore a catch-all clause last in the definition of
      the event handler callback function <c>Module:handle_event/2</c>
      is necessary. This also applies for
      <c>Module:handle_info/2</c>, as the event handler must also take care of
      some system-internal messages.</p>
  </section>
  <section>
    <title>See Also</title>
    <p><seealso marker="stdlib:gen_event"><c>gen_event(3)</c></seealso>,
       <seealso marker="stdlib:log_mf_h"><c>log_mf_h(3)</c></seealso>
       <seealso marker="kernel_app"><c>kernel(6)</c></seealso>
       <seealso marker="sasl:sasl_app"><c>sasl(6)</c></seealso></p>
  </section>
</erlref>