From a9a6b803a60793d42a74e0f1693a7594dffb6bc3 Mon Sep 17 00:00:00 2001 From: Siri Hansen Date: Thu, 17 May 2018 18:19:57 +0200 Subject: Improve documentation of logger and error_logger --- lib/stdlib/doc/src/gen_event.xml | 3 +-- lib/stdlib/doc/src/gen_server.xml | 6 ++--- lib/stdlib/doc/src/gen_statem.xml | 4 ++-- lib/stdlib/doc/src/proc_lib.xml | 50 ++++++++++++++++++++++++++++----------- 4 files changed, 41 insertions(+), 22 deletions(-) (limited to 'lib/stdlib/doc/src') diff --git a/lib/stdlib/doc/src/gen_event.xml b/lib/stdlib/doc/src/gen_event.xml index 012737c390..51378a6b73 100644 --- a/lib/stdlib/doc/src/gen_event.xml +++ b/lib/stdlib/doc/src/gen_event.xml @@ -458,8 +458,7 @@ gen_event:stop -----> Module:terminate/2 with the expected reason. Any other reason than normal, shutdown, or {shutdown,Term} causes an error report to be issued using - - error_logger:format/2. + logger(3). The default Reason is normal.

Timeout is an integer greater than zero that specifies how many milliseconds to wait for the event manager to diff --git a/lib/stdlib/doc/src/gen_server.xml b/lib/stdlib/doc/src/gen_server.xml index da74e793e6..27edbc8de7 100644 --- a/lib/stdlib/doc/src/gen_server.xml +++ b/lib/stdlib/doc/src/gen_server.xml @@ -486,8 +486,7 @@ gen_server:abcast -----> Module:handle_cast/2 with the expected reason. Any other reason than normal, shutdown, or {shutdown,Term} causes an error report to be issued using - - error_logger:format/2. + logger(3). The default Reason is normal.

Timeout is an integer greater than zero that specifies how many milliseconds to wait for the server to @@ -861,8 +860,7 @@ gen_server:abcast -----> Module:handle_cast/2 shutdown, or {shutdown,Term}, the gen_server process is assumed to terminate because of an error and an error report is issued using - - error_logger:format/2.

+ logger(3).

diff --git a/lib/stdlib/doc/src/gen_statem.xml b/lib/stdlib/doc/src/gen_statem.xml index e918e83df7..a808d3af55 100644 --- a/lib/stdlib/doc/src/gen_statem.xml +++ b/lib/stdlib/doc/src/gen_statem.xml @@ -1778,7 +1778,7 @@ handle_event(_, _, State, Data) -> with the expected reason. Any other reason than normal, shutdown, or {shutdown,Term} causes an error report to be issued through - error_logger:format/2. + logger(3). The default Reason is normal.

@@ -2286,7 +2286,7 @@ init(Args) -> erlang:error(not_implemented, [Args]). shutdown, or {shutdown,Term}, the gen_statem is assumed to terminate because of an error and an error report is issued using - error_logger:format/2. + logger(3).

diff --git a/lib/stdlib/doc/src/proc_lib.xml b/lib/stdlib/doc/src/proc_lib.xml index cb152d1935..c4fdf972e4 100644 --- a/lib/stdlib/doc/src/proc_lib.xml +++ b/lib/stdlib/doc/src/proc_lib.xml @@ -59,18 +59,16 @@

When a process that is started using proc_lib terminates abnormally (that is, with another exit reason than normal, shutdown, or {shutdown,Term}), a crash report - is generated, which is written to terminal by the default SASL - event handler. That is, the crash report is normally only visible - if the SASL application is started; see - sasl(6) and section - SASL Error Logging - in the SASL User's Guide.

+ is generated, which is written to terminal by the default logger + handler setup by Kernel. For more information about how crash reports + were logged before OTP-21, see + SASL Error Logging in the SASL User's Guide.

Unlike in "plain Erlang", proc_lib processes will not generate error reports, which are written to the terminal by the - emulator and do not require SASL to be started. All exceptions are + emulator. All exceptions are converted to exits which are ignored by the default - error_logger handler.

+ logger handler.

The crash report contains the previously stored information, such as ancestors and initial function, the termination reason, and @@ -115,12 +113,22 @@ Format a crash report. -

This function can be used by a user-defined event handler to + +

This function is deprecated in the sense that + the error_logger is no longer the preferred + interface for logging in Erlang/OTP. A + new logging + API was added in OTP-21, but + legacy error_logger handlers may still be used. New + logger handlers do not need to used this function, since + the formatting callback (report_cb) is included as + metadata in the log event.

+ +

This function can be used by a user-defined legacy + error_logger event handler to format a crash report. The crash report is sent using - - error_logger:error_report(crash_report, - CrashReport). - That is, the event to be handled is of the format + + logger(3), and the event to be handled is of the format {error_report, GL, {Pid, crash_report, CrashReport}}, where GL is the group leader pid of process @@ -132,7 +140,19 @@ Format a crash report. -

This function can be used by a user-defined event handler to + +

This function is deprecated in the sense that + the error_logger is no longer the preferred + interface for logging in Erlang/OTP. A + new logging + API was added in OTP-21, but + legacy error_logger handlers may still be used. New + logger handlers do not need to used this function, since + the formatting callback (report_cb) is included as + metadata in the log event.

+ +

This function can be used by a user-defined legacy + error_logger event handler to format a crash report. When Depth is specified as a positive integer, it is used in the format string to limit the output as follows: io_lib:format("~P", @@ -395,6 +415,8 @@ init(Parent) -> See Also

error_logger(3)

+

+ logger(3)

-- cgit v1.2.3