Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

Add README.md, LICENSE files

  • Loading branch information...
commit 2a18c9c16a9466352b9d11e29168b45ca344da34 1 parent 3c52872
Scott Lystig Fritchie authored November 10, 2010

Showing 2 changed files with 313 additions and 0 deletions. Show diff stats Hide diff stats

  1. 178  LICENSE
  2. 135  README.md
178  LICENSE
... ...
@@ -0,0 +1,178 @@
  1
+
  2
+                                 Apache License
  3
+                           Version 2.0, January 2004
  4
+                        http://www.apache.org/licenses/
  5
+
  6
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
  7
+
  8
+   1. Definitions.
  9
+
  10
+      "License" shall mean the terms and conditions for use, reproduction,
  11
+      and distribution as defined by Sections 1 through 9 of this document.
  12
+
  13
+      "Licensor" shall mean the copyright owner or entity authorized by
  14
+      the copyright owner that is granting the License.
  15
+
  16
+      "Legal Entity" shall mean the union of the acting entity and all
  17
+      other entities that control, are controlled by, or are under common
  18
+      control with that entity. For the purposes of this definition,
  19
+      "control" means (i) the power, direct or indirect, to cause the
  20
+      direction or management of such entity, whether by contract or
  21
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
  22
+      outstanding shares, or (iii) beneficial ownership of such entity.
  23
+
  24
+      "You" (or "Your") shall mean an individual or Legal Entity
  25
+      exercising permissions granted by this License.
  26
+
  27
+      "Source" form shall mean the preferred form for making modifications,
  28
+      including but not limited to software source code, documentation
  29
+      source, and configuration files.
  30
+
  31
+      "Object" form shall mean any form resulting from mechanical
  32
+      transformation or translation of a Source form, including but
  33
+      not limited to compiled object code, generated documentation,
  34
+      and conversions to other media types.
  35
+
  36
+      "Work" shall mean the work of authorship, whether in Source or
  37
+      Object form, made available under the License, as indicated by a
  38
+      copyright notice that is included in or attached to the work
  39
+      (an example is provided in the Appendix below).
  40
+
  41
+      "Derivative Works" shall mean any work, whether in Source or Object
  42
+      form, that is based on (or derived from) the Work and for which the
  43
+      editorial revisions, annotations, elaborations, or other modifications
  44
+      represent, as a whole, an original work of authorship. For the purposes
  45
+      of this License, Derivative Works shall not include works that remain
  46
+      separable from, or merely link (or bind by name) to the interfaces of,
  47
+      the Work and Derivative Works thereof.
  48
+
  49
+      "Contribution" shall mean any work of authorship, including
  50
+      the original version of the Work and any modifications or additions
  51
+      to that Work or Derivative Works thereof, that is intentionally
  52
+      submitted to Licensor for inclusion in the Work by the copyright owner
  53
+      or by an individual or Legal Entity authorized to submit on behalf of
  54
+      the copyright owner. For the purposes of this definition, "submitted"
  55
+      means any form of electronic, verbal, or written communication sent
  56
+      to the Licensor or its representatives, including but not limited to
  57
+      communication on electronic mailing lists, source code control systems,
  58
+      and issue tracking systems that are managed by, or on behalf of, the
  59
+      Licensor for the purpose of discussing and improving the Work, but
  60
+      excluding communication that is conspicuously marked or otherwise
  61
+      designated in writing by the copyright owner as "Not a Contribution."
  62
+
  63
+      "Contributor" shall mean Licensor and any individual or Legal Entity
  64
+      on behalf of whom a Contribution has been received by Licensor and
  65
+      subsequently incorporated within the Work.
  66
+
  67
+   2. Grant of Copyright License. Subject to the terms and conditions of
  68
+      this License, each Contributor hereby grants to You a perpetual,
  69
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
  70
+      copyright license to reproduce, prepare Derivative Works of,
  71
+      publicly display, publicly perform, sublicense, and distribute the
  72
+      Work and such Derivative Works in Source or Object form.
  73
+
  74
+   3. Grant of Patent License. Subject to the terms and conditions of
  75
+      this License, each Contributor hereby grants to You a perpetual,
  76
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
  77
+      (except as stated in this section) patent license to make, have made,
  78
+      use, offer to sell, sell, import, and otherwise transfer the Work,
  79
+      where such license applies only to those patent claims licensable
  80
+      by such Contributor that are necessarily infringed by their
  81
+      Contribution(s) alone or by combination of their Contribution(s)
  82
+      with the Work to which such Contribution(s) was submitted. If You
  83
+      institute patent litigation against any entity (including a
  84
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
  85
+      or a Contribution incorporated within the Work constitutes direct
  86
+      or contributory patent infringement, then any patent licenses
  87
+      granted to You under this License for that Work shall terminate
  88
+      as of the date such litigation is filed.
  89
+
  90
+   4. Redistribution. You may reproduce and distribute copies of the
  91
+      Work or Derivative Works thereof in any medium, with or without
  92
+      modifications, and in Source or Object form, provided that You
  93
+      meet the following conditions:
  94
+
  95
+      (a) You must give any other recipients of the Work or
  96
+          Derivative Works a copy of this License; and
  97
+
  98
+      (b) You must cause any modified files to carry prominent notices
  99
+          stating that You changed the files; and
  100
+
  101
+      (c) You must retain, in the Source form of any Derivative Works
  102
+          that You distribute, all copyright, patent, trademark, and
  103
+          attribution notices from the Source form of the Work,
  104
+          excluding those notices that do not pertain to any part of
  105
+          the Derivative Works; and
  106
+
  107
+      (d) If the Work includes a "NOTICE" text file as part of its
  108
+          distribution, then any Derivative Works that You distribute must
  109
+          include a readable copy of the attribution notices contained
  110
+          within such NOTICE file, excluding those notices that do not
  111
+          pertain to any part of the Derivative Works, in at least one
  112
+          of the following places: within a NOTICE text file distributed
  113
+          as part of the Derivative Works; within the Source form or
  114
+          documentation, if provided along with the Derivative Works; or,
  115
+          within a display generated by the Derivative Works, if and
  116
+          wherever such third-party notices normally appear. The contents
  117
+          of the NOTICE file are for informational purposes only and
  118
+          do not modify the License. You may add Your own attribution
  119
+          notices within Derivative Works that You distribute, alongside
  120
+          or as an addendum to the NOTICE text from the Work, provided
  121
+          that such additional attribution notices cannot be construed
  122
+          as modifying the License.
  123
+
  124
+      You may add Your own copyright statement to Your modifications and
  125
+      may provide additional or different license terms and conditions
  126
+      for use, reproduction, or distribution of Your modifications, or
  127
+      for any such Derivative Works as a whole, provided Your use,
  128
+      reproduction, and distribution of the Work otherwise complies with
  129
+      the conditions stated in this License.
  130
+
  131
+   5. Submission of Contributions. Unless You explicitly state otherwise,
  132
+      any Contribution intentionally submitted for inclusion in the Work
  133
+      by You to the Licensor shall be under the terms and conditions of
  134
+      this License, without any additional terms or conditions.
  135
+      Notwithstanding the above, nothing herein shall supersede or modify
  136
+      the terms of any separate license agreement you may have executed
  137
+      with Licensor regarding such Contributions.
  138
+
  139
+   6. Trademarks. This License does not grant permission to use the trade
  140
+      names, trademarks, service marks, or product names of the Licensor,
  141
+      except as required for reasonable and customary use in describing the
  142
+      origin of the Work and reproducing the content of the NOTICE file.
  143
+
  144
+   7. Disclaimer of Warranty. Unless required by applicable law or
  145
+      agreed to in writing, Licensor provides the Work (and each
  146
+      Contributor provides its Contributions) on an "AS IS" BASIS,
  147
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
  148
+      implied, including, without limitation, any warranties or conditions
  149
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
  150
+      PARTICULAR PURPOSE. You are solely responsible for determining the
  151
+      appropriateness of using or redistributing the Work and assume any
  152
+      risks associated with Your exercise of permissions under this License.
  153
+
  154
+   8. Limitation of Liability. In no event and under no legal theory,
  155
+      whether in tort (including negligence), contract, or otherwise,
  156
+      unless required by applicable law (such as deliberate and grossly
  157
+      negligent acts) or agreed to in writing, shall any Contributor be
  158
+      liable to You for damages, including any direct, indirect, special,
  159
+      incidental, or consequential damages of any character arising as a
  160
+      result of this License or out of the use or inability to use the
  161
+      Work (including but not limited to damages for loss of goodwill,
  162
+      work stoppage, computer failure or malfunction, or any and all
  163
+      other commercial damages or losses), even if such Contributor
  164
+      has been advised of the possibility of such damages.
  165
+
  166
+   9. Accepting Warranty or Additional Liability. While redistributing
  167
+      the Work or Derivative Works thereof, You may choose to offer,
  168
+      and charge a fee for, acceptance of support, warranty, indemnity,
  169
+      or other liability obligations and/or rights consistent with this
  170
+      License. However, in accepting such obligations, You may act only
  171
+      on Your own behalf and on Your sole responsibility, not on behalf
  172
+      of any other Contributor, and only if You agree to indemnify,
  173
+      defend, and hold each Contributor harmless for any liability
  174
+      incurred by, or claims asserted against, such Contributor by reason
  175
+      of your accepting any such warranty or additional liability.
  176
+
  177
+   END OF TERMS AND CONDITIONS
  178
+
135  README.md
Source Rendered
... ...
@@ -0,0 +1,135 @@
  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/.

0 notes on commit 2a18c9c

Please sign in to comment.
Something went wrong with that request. Please try again.