Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 136 lines (106 sloc) 5.523 kb
2a18c9c1 »
2010-11-10 Add README.md, LICENSE files
1 riak_err: Limiting the maximum size of Erlang/OTP error_logger messages
2 =======================================================================
3
4 The `riak_err` OTP application replaces about 90% of the default
5 Erlang/OTP info/error/warning event handling mechanism.
6 The replacement places strict limits on the maximum size of a
7 formatted message.
8
9 Why replace the default error handlers?
10 ---------------------------------------
11
12 The Erlang/OTP default event handler will format a message using a
13 user-supplied formatting string or a default `"~p"` formatting string
14 (for report-style messages). Using `~p` and/or `~w` formatting can
15 consume enormous amounts of RAM, due to how Erlang strings are
16 handled. It isn't uncommon to submit an error message that is only
17 5MB, but formatting that message can use anywhere from 80MB to 320MB
18 on CPUs with a 64-bit word size.
19
20 A very brief tour of the error_logger
21 -------------------------------------
22
23 The OTP `kernel` application starts a system-wide event handler named
24 `error_logger` to receive events, format them, and write them to the
25 tty/console/CLI.
26
27 $ erl -sname asdf -pz ./b/src/riak_err/ebin
28 Erlang R13B04 (erts-5.7.5) [source] [64-bit] [smp:4:4] [rq:4] [async-threads:0] [hipe] [kernel-poll:false]
29
30 Eshell V5.7.5 (abort with ^G)
31 (asdf@sbb)1> gen_event:which_handlers(error_logger).
32 [error_logger,error_logger_tty_h]
33
34 The OTP `sasl` application adds more handlers, specifically for
35 formatting events from processes that use `supervisor`, `gen_server`,
36 `gen_event`, and `gen_fsm` behavior (as well as any process that uses
37 `proc_lib` helper functions).
38
39 (asdf@sbb)2> application:start(sasl).
40 ok
41 (asdf@sbb)3> gen_event:which_handlers(error_logger).
42 [sasl_report_tty_h,error_logger,error_logger_tty_h]
43
44 The `sasl` application can be configured to add additional event
45 handlers that will write events to disk, either as human-friendly
46 ASCII/Latin-1 formatting or machine-friendly binary format. For
47 example, this is the list of `error_logger`'s event handlers when the
48 Basho's Riak application is started.
49
50 (riaksearch@127.0.0.1)1> gen_event:which_handlers(error_logger).
51 [log_mf_h,sasl_report_file_h,error_logger,error_logger_tty_h]
52
53 When the `riak_err` application is started, the following event
54 handlers are removed from the `error_logger`:
55
56 * `error_logger`
57 * `error_logger_tty_h`
58 * `sasl_report_tty_h`
59 * `sasl_report_file_h`
60
61 ... and are replaced by the `riak_err_handler` handler.
62
63 Configuration
64 -------------
65
66 There are two config knobs may be specified on the command line
67 via `-riak_err KnobName Integer` on the command line or (in a
68 Basho application like Riak) via the same `-riak_err KnobName Integer`
69 line in the `etc/vm.args` file). Alternatively, these properties
70 may be set using application environment variables by the same name.
71
72 * `term_max_size` For arguments formatted in FormatString and
73 ArgList style, if the total size of ArgList is more than `term_max_size`,
74 then we'll ignore FormatString and log the message with a well-known
75 (and therefore safe) formatting string. The default is 10KBytes.
76 * `fmt_max_bytes` When formatting a log-related term that might
77 be "big", limit the term's formatted output to a maximum of
78 `fmt_max_bytes` bytes. The default is 12KBytes.
79
80 For example, `erl -riak_err term_max_size 8192 fmt_max_bytes 9000`
81
82 If the SASL error logger's `sasl_error_logger` configuration
83 parameter is set to the `{file, FileName}` form, then this
84 module will attempt to emulate the SASL error logger's
85 logging-to-file behavior. However, the interpretation of the
86 `errlog_type` configuration parameter is limited: if its
87 value is `error`, then only error and warning messages will
88 be written to the file. In all other cases (namely both
89 `progress` and `all`), all events will be formatted
90 and written to the file.
91
92 A short note about log file rotation
93 ------------------------------------
94
95 * *NOTE:* The log file's filehandle will be re-opened once
96 per second, which will allow log file rotation schemes
97 to rotate the log file safely without undue worry about
98 losing log file entries or worrying about sending a
99 SIGHUP signal to the owner process before rotation.
100
101 Building via rebar
102 ------------------
103
104 To build using [`rebar`](http://github.com/basho/rebar), add the
105 following line to your project's `rebar.config` file, in the `deps`
106 section:
107
108 {riak_err, ".*", {git, "git@github.com:/basho/riak_err", "HEAD"}}
109
110 As an example, this is a mostly-complete `rebar.config` file from
111 Basho's Riak package:
112
113 {sub_dirs, ["rel"]}.
114 {require_otp_vsn, "R13B04|R14"}.
115 {cover_enabled, true}.
116 {erl_opts, [debug_info, fail_on_warning]}.
117
118 %% Technically speaking, this dependency list is incomplete, but
119 %% I wanted to show a complete rebar.config file here....
120 {deps, [
121 {riak_err, ".*", {git, "git@github.com:/basho/riak_err", "HEAD"}},
122 {riak_kv, "0.13.0", {git, "git://github.com/basho/riak_kv", "HEAD"}},
123 {luwak, "1.*", {git, "git://github.com/basho/luwak", "HEAD"}}
124 ]}.
125
126 Licensing
127 ---------
128
129 * Code written by Basho Technologies, Inc. is licensed under an Apache
130 Public License version 2.0, see the "LICENSE" file in this source code
131 distribution.
132 * Code written by Ericsson AB and contributors is licensed under the
133 Erlang Public License version 1.1, see http://www.erlang.org/.
134 * Code written by Corelatus AB and contributors is licensed under the
135 Erlang Public License version 1.1, see http://www.erlang.org/.
Something went wrong with that request. Please try again.