Exception Notification
- Filed under Miscellaneous
- Developed by Jamis Buck
<!DOCTYPE html
PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en">
<head>
<title>/plugins/exception_notification/README - Rails Trac - Trac</title><link rel="start" href="/wiki" /><link rel="search" href="/search" /><link rel="help" href="/wiki/TracGuide" /><link rel="stylesheet" href="/trac/css/trac.css" type="text/css" /><link rel="stylesheet" href="/trac/css/code.css" type="text/css" /><link rel="stylesheet" href="/trac/css/browser.css" type="text/css" /><link rel="icon" href="/chrome/common/trac.ico" type="image/x-icon" /><link rel="shortcut icon" href="/chrome/common/trac.ico" type="image/x-icon" /><link rel="up" href="/browser/plugins/exception_notification" title="Parent directory" /><link rel="alternate" href="/browser/plugins/exception_notification/README?format=txt" title="Plain Text" type="text/plain" /><link rel="alternate" href="/export/7594/plugins/exception_notification/README" title="Original Format" type="text/plain; charset=iso-8859-15" /><style type="text/css">@import url(/site/screen.css);
</style>
<script type="text/javascript" src="/trac/js/trac.js"></script>
</head>
<body>
<div id="TopNav">
<img src="http://www.rubyonrails.org/images/favicon.png" style="vertical-align: middle; border: none; margin-right: 5px"/>
<a href="http://www.rubyonrails.org/">Ruby on Rails</a> |
<a href="http://www.rubyonrails.org/screencasts">Screencasts</a> |
<a href="http://www.rubyonrails.org/down">Download</a> |
<a href="http://www.rubyonrails.org/docs">Documentation</a> |
<a href="http://weblog.rubyonrails.org">Weblog</a> |
<a href="http://www.rubyonrails.org/community">Community</a> |
<a href="http://dev.rubyonrails.org">Source</a>
</div>
<div id="banner">
<div id="header"><h1><a href="http://dev.rubyonrails.org/">Rails Trac</a></h1></div>
<form id="search" action="/search" method="get">
<div>
<label for="proj-search">Search:</label>
<input type="text" id="proj-search" name="q" size="10" accesskey="f" value="" />
<input type="submit" value="Search" />
<input type="hidden" name="wiki" value="on" />
<input type="hidden" name="changeset" value="on" />
<input type="hidden" name="ticket" value="on" />
</div>
</form>
<div id="metanav" class="nav"><ul><li class="first"><a href="/login">Login</a></li><li><a href="/settings">Settings</a></li><li><a accesskey="6" href="/wiki/TracGuide">Help/Guide</a></li><li><a href="/about">About Trac</a></li><li class="last"><a href="/register">Register</a></li></ul></div>
</div>
<div id="mainnav" class="nav"><ul><li class="first"><a accesskey="1" href="/wiki">Wiki</a></li><li><a accesskey="2" href="/timeline">Timeline</a></li><li><a accesskey="3" href="/roadmap">Roadmap</a></li><li class="active"><a href="/browser">Browse Source</a></li><li><a href="/report">View Tickets</a></li><li class="last"><a accesskey="4" href="/search">Search</a></li></ul></div>
<div id="main">
<div id="ctxtnav" class="nav">
<ul>
<li class="first"><a href="/changeset/2822/plugins/exception_notification/README">
Last Change</a></li>
<li class="last"><a href="/log/plugins/exception_notification/README">
Revision Log</a></li>
</ul>
</div>
<div id="searchable">
<div id="content" class="browser">
<h1><a class="first" title="Go to root directory" href="/browser">root</a><span class="sep">/</span><a title="View plugins" href="/browser/plugins">plugins</a><span class="sep">/</span><a title="View exception_notification" href="/browser/plugins/exception_notification">exception_notification</a><span class="sep">/</span><a title="View README" href="/browser/plugins/exception_notification/README">README</a></h1>
<div id="jumprev">
<form action="" method="get">
<div>
<label for="rev">View revision:</label>
<input type="text" id="rev" name="rev" value="" size="4" />
</div>
</form>
</div>
<table id="info" summary="Revision info"><tr>
<th scope="col">
Revision <a href="/changeset/2822">2822</a>, 4.2 kB
(checked in by minam, 2 years ago)
</th></tr><tr>
<td class="message"><p>
Correct error in documentation <br />
</p>
</td>
</tr>
</table>
<div id="preview"><table class="code"><thead><tr><th class="lineno">Line</th><th class="content"> </th></tr></thead><tbody><tr><th id="L1"><a href="#L1">1</a></th>
<td>= Exception Notifier Plugin for Rails</td>
</tr><tr><th id="L2"><a href="#L2">2</a></th>
<td></td>
</tr><tr><th id="L3"><a href="#L3">3</a></th>
<td>The Exception Notifier plugin provides a mailer object and a default set of</td>
</tr><tr><th id="L4"><a href="#L4">4</a></th>
<td>templates for sending email notifications when errors occur in a Rails</td>
</tr><tr><th id="L5"><a href="#L5">5</a></th>
<td>application. The plugin is configurable, allowing programmers to specify:</td>
</tr><tr><th id="L6"><a href="#L6">6</a></th>
<td></td>
</tr><tr><th id="L7"><a href="#L7">7</a></th>
<td>* the sender address of the email</td>
</tr><tr><th id="L8"><a href="#L8">8</a></th>
<td>* the recipient addresses</td>
</tr><tr><th id="L9"><a href="#L9">9</a></th>
<td>* the text used to prefix the subject line</td>
</tr><tr><th id="L10"><a href="#L10">10</a></th>
<td></td>
</tr><tr><th id="L11"><a href="#L11">11</a></th>
<td>The email includes information about the current request, session, and</td>
</tr><tr><th id="L12"><a href="#L12">12</a></th>
<td>environment, and also gives a backtrace of the exception.</td>
</tr><tr><th id="L13"><a href="#L13">13</a></th>
<td></td>
</tr><tr><th id="L14"><a href="#L14">14</a></th>
<td>== Usage</td>
</tr><tr><th id="L15"><a href="#L15">15</a></th>
<td></td>
</tr><tr><th id="L16"><a href="#L16">16</a></th>
<td>First, include the ExceptionNotifiable mixin in whichever controller you want</td>
</tr><tr><th id="L17"><a href="#L17">17</a></th>
<td>to generate error emails (typically ApplicationController):</td>
</tr><tr><th id="L18"><a href="#L18">18</a></th>
<td></td>
</tr><tr><th id="L19"><a href="#L19">19</a></th>
<td> class ApplicationController < ActionController::Base</td>
</tr><tr><th id="L20"><a href="#L20">20</a></th>
<td> include ExceptionNotifiable</td>
</tr><tr><th id="L21"><a href="#L21">21</a></th>
<td> ...</td>
</tr><tr><th id="L22"><a href="#L22">22</a></th>
<td> end</td>
</tr><tr><th id="L23"><a href="#L23">23</a></th>
<td></td>
</tr><tr><th id="L24"><a href="#L24">24</a></th>
<td>Then, specify the email recipients in your environment:</td>
</tr><tr><th id="L25"><a href="#L25">25</a></th>
<td></td>
</tr><tr><th id="L26"><a href="#L26">26</a></th>
<td> ExceptionNotifier.exception_recipients = %w(joe@schmoe.com bill@schmoe.com)</td>
</tr><tr><th id="L27"><a href="#L27">27</a></th>
<td></td>
</tr><tr><th id="L28"><a href="#L28">28</a></th>
<td>And that's it! The defaults take care of the rest.</td>
</tr><tr><th id="L29"><a href="#L29">29</a></th>
<td></td>
</tr><tr><th id="L30"><a href="#L30">30</a></th>
<td>== Configuration</td>
</tr><tr><th id="L31"><a href="#L31">31</a></th>
<td></td>
</tr><tr><th id="L32"><a href="#L32">32</a></th>
<td>You can tweak other values to your liking, as well. In your environment file,</td>
</tr><tr><th id="L33"><a href="#L33">33</a></th>
<td>just set any or all of the following values:</td>
</tr><tr><th id="L34"><a href="#L34">34</a></th>
<td></td>
</tr><tr><th id="L35"><a href="#L35">35</a></th>
<td> # defaults to exception.notifier@default.com</td>
</tr><tr><th id="L36"><a href="#L36">36</a></th>
<td> ExceptionNotifier.sender_address =</td>
</tr><tr><th id="L37"><a href="#L37">37</a></th>
<td> %("Application Error" <app.error@myapp.com>)</td>
</tr><tr><th id="L38"><a href="#L38">38</a></th>
<td></td>
</tr><tr><th id="L39"><a href="#L39">39</a></th>
<td> # defaults to "[ERROR] "</td>
</tr><tr><th id="L40"><a href="#L40">40</a></th>
<td> ExceptionNotifier.email_prefix = "[APP] "</td>
</tr><tr><th id="L41"><a href="#L41">41</a></th>
<td></td>
</tr><tr><th id="L42"><a href="#L42">42</a></th>
<td>Email notifications will only occur when the IP address is determined not to</td>
</tr><tr><th id="L43"><a href="#L43">43</a></th>
<td>be local. You can specify certain addresses to always be local so that you'll</td>
</tr><tr><th id="L44"><a href="#L44">44</a></th>
<td>get a detailed error instead of the generic error page. You do this in your</td>
</tr><tr><th id="L45"><a href="#L45">45</a></th>
<td>controller (or even per-controller):</td>
</tr><tr><th id="L46"><a href="#L46">46</a></th>
<td></td>
</tr><tr><th id="L47"><a href="#L47">47</a></th>
<td> consider_local "64.72.18.143", "14.17.21.25"</td>
</tr><tr><th id="L48"><a href="#L48">48</a></th>
<td></td>
</tr><tr><th id="L49"><a href="#L49">49</a></th>
<td>You can specify subnet masks as well, so that all matching addresses are</td>
</tr><tr><th id="L50"><a href="#L50">50</a></th>
<td>considered local:</td>
</tr><tr><th id="L51"><a href="#L51">51</a></th>
<td></td>
</tr><tr><th id="L52"><a href="#L52">52</a></th>
<td> consider_local "64.72.18.143/24"</td>
</tr><tr><th id="L53"><a href="#L53">53</a></th>
<td></td>
</tr><tr><th id="L54"><a href="#L54">54</a></th>
<td>The address "127.0.0.1" is always considered local. If you want to completely</td>
</tr><tr><th id="L55"><a href="#L55">55</a></th>
<td>reset the list of all addresses (for instance, if you wanted "127.0.0.1" to</td>
</tr><tr><th id="L56"><a href="#L56">56</a></th>
<td>NOT be considered local), you can simply do, somewhere in your controller:</td>
</tr><tr><th id="L57"><a href="#L57">57</a></th>
<td></td>
</tr><tr><th id="L58"><a href="#L58">58</a></th>
<td> local_addresses.clear</td>
</tr><tr><th id="L59"><a href="#L59">59</a></th>
<td></td>
</tr><tr><th id="L60"><a href="#L60">60</a></th>
<td>== Customization</td>
</tr><tr><th id="L61"><a href="#L61">61</a></th>
<td></td>
</tr><tr><th id="L62"><a href="#L62">62</a></th>
<td>By default, the notification email includes four parts: request, session,</td>
</tr><tr><th id="L63"><a href="#L63">63</a></th>
<td>environment, and backtrace (in that order). You can customize how each of those</td>
</tr><tr><th id="L64"><a href="#L64">64</a></th>
<td>sections are rendered by placing a partial named for that part in your</td>
</tr><tr><th id="L65"><a href="#L65">65</a></th>
<td>app/views/exception_notifier directory (e.g., _session.rhtml). Each partial has</td>
</tr><tr><th id="L66"><a href="#L66">66</a></th>
<td>access to the following variables:</td>
</tr><tr><th id="L67"><a href="#L67">67</a></th>
<td></td>
</tr><tr><th id="L68"><a href="#L68">68</a></th>
<td>* @controller: the controller that caused the error</td>
</tr><tr><th id="L69"><a href="#L69">69</a></th>
<td>* @request: the current request object</td>
</tr><tr><th id="L70"><a href="#L70">70</a></th>
<td>* @exception: the exception that was raised</td>
</tr><tr><th id="L71"><a href="#L71">71</a></th>
<td>* @host: the name of the host that made the request</td>
</tr><tr><th id="L72"><a href="#L72">72</a></th>
<td>* @backtrace: a sanitized version of the exception's backtrace</td>
</tr><tr><th id="L73"><a href="#L73">73</a></th>
<td>* @rails_root: a sanitized version of RAILS_ROOT</td>
</tr><tr><th id="L74"><a href="#L74">74</a></th>
<td>* @data: a hash of optional data values that were passed to the notifier</td>
</tr><tr><th id="L75"><a href="#L75">75</a></th>
<td>* @sections: the array of sections to include in the email</td>
</tr><tr><th id="L76"><a href="#L76">76</a></th>
<td></td>
</tr><tr><th id="L77"><a href="#L77">77</a></th>
<td>You can reorder the sections, or exclude sections completely, by altering the</td>
</tr><tr><th id="L78"><a href="#L78">78</a></th>
<td>ExceptionNotifier.sections variable. You can even add new sections that</td>
</tr><tr><th id="L79"><a href="#L79">79</a></th>
<td>describe application-specific data--just add the section's name to the list</td>
</tr><tr><th id="L80"><a href="#L80">80</a></th>
<td>(whereever you'd like), and define the corresponding partial. Then, if your</td>
</tr><tr><th id="L81"><a href="#L81">81</a></th>
<td>new section requires information that isn't available by default, make sure</td>
</tr><tr><th id="L82"><a href="#L82">82</a></th>
<td>it is made available to the email using the exception_data macro:</td>
</tr><tr><th id="L83"><a href="#L83">83</a></th>
<td></td>
</tr><tr><th id="L84"><a href="#L84">84</a></th>
<td> class ApplicationController < ActionController::Base</td>
</tr><tr><th id="L85"><a href="#L85">85</a></th>
<td> ...</td>
</tr><tr><th id="L86"><a href="#L86">86</a></th>
<td> protected</td>
</tr><tr><th id="L87"><a href="#L87">87</a></th>
<td> exception_data :additional_data</td>
</tr><tr><th id="L88"><a href="#L88">88</a></th>
<td></td>
</tr><tr><th id="L89"><a href="#L89">89</a></th>
<td> def additional_data</td>
</tr><tr><th id="L90"><a href="#L90">90</a></th>
<td> { :document => @document,</td>
</tr><tr><th id="L91"><a href="#L91">91</a></th>
<td> :person => @person }</td>
</tr><tr><th id="L92"><a href="#L92">92</a></th>
<td> end</td>
</tr><tr><th id="L93"><a href="#L93">93</a></th>
<td> ...</td>
</tr><tr><th id="L94"><a href="#L94">94</a></th>
<td> end</td>
</tr><tr><th id="L95"><a href="#L95">95</a></th>
<td></td>
</tr><tr><th id="L96"><a href="#L96">96</a></th>
<td>In the above case, @document and @person would be made available to the email</td>
</tr><tr><th id="L97"><a href="#L97">97</a></th>
<td>renderer, allowing your new section(s) to access and display them. See the</td>
</tr><tr><th id="L98"><a href="#L98">98</a></th>
<td>existing sections defined by the plugin for examples of how to write your own.</td>
</tr><tr><th id="L99"><a href="#L99">99</a></th>
<td></td>
</tr><tr><th id="L100"><a href="#L100">100</a></th>
<td>== Advanced Customization</td>
</tr><tr><th id="L101"><a href="#L101">101</a></th>
<td></td>
</tr><tr><th id="L102"><a href="#L102">102</a></th>
<td>By default, the email notifier will only notify on critical errors. For</td>
</tr><tr><th id="L103"><a href="#L103">103</a></th>
<td>ActiveRecord::RecordNotFound and ActionController::UnknownAction, it will</td>
</tr><tr><th id="L104"><a href="#L104">104</a></th>
<td>simply render the contents of your public/404.html file. Other exceptions</td>
</tr><tr><th id="L105"><a href="#L105">105</a></th>
<td>will render public/500.html and will send the email notification. If you want</td>
</tr><tr><th id="L106"><a href="#L106">106</a></th>
<td>to use different rules for the notification, you will need to implement your</td>
</tr><tr><th id="L107"><a href="#L107">107</a></th>
<td>own rescue_action_in_public method. You can look at the default implementation</td>
</tr><tr><th id="L108"><a href="#L108">108</a></th>
<td>in ExceptionNotifiable for an example of how to go about that.</td>
</tr><tr><th id="L109"><a href="#L109">109</a></th>
<td></td>
</tr><tr><th id="L110"><a href="#L110">110</a></th>
<td></td>
</tr><tr><th id="L111"><a href="#L111">111</a></th>
<td>Copyright (c) 2005 Jamis Buck, released under the MIT license</td>
</tr></tbody></table>
</div>
<div id="help">
<strong>Note:</strong> See <a href="/wiki/TracBrowser">TracBrowser</a> for help on using the browser.
</div>
<div id="anydiff">
<form action="/anydiff" method="get">
<div class="buttons">
<input type="hidden" name="new_path" value="/plugins/exception_notification/README" />
<input type="hidden" name="old_path" value="/plugins/exception_notification/README" />
<input type="hidden" name="new_rev" value="" />
<input type="hidden" name="old_rev" value="" />
<input type="submit" value="View changes..." title="Prepare an Arbitrary Diff" />
</div>
</form>
</div>
</div>
</div>
<script type="text/javascript">searchHighlight()</script>
<div id="altlinks"><h3>Download in other formats:</h3><ul><li class="first"><a href="/browser/plugins/exception_notification/README?format=txt">Plain Text</a></li><li class="last"><a href="/export/7594/plugins/exception_notification/README">Original Format</a></li></ul></div>
</div>
<div id="footer">
<hr />
<a id="tracpowered" href="http://trac.edgewall.org/"><img src="/trac/trac_logo_mini.png" height="30" width="107"
alt="Trac Powered"/></a>
<p class="left">
Powered by <a href="/about"><strong>Trac 0.10.5dev</strong></a><br />
By <a href="http://www.edgewall.org/">Edgewall Software</a>.
</p>
<p class="right">
Visit the Ruby on Rails project at<br /><a href="http://rubyonrails.org/">http://rubyonrails.org/</a>
</p>
</div>
</body>
</html>
Last updated: September 23, 2007 15:54
