1 <!DOCTYPE html PUBLIC
"-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
2 <html xmlns=
"http://www.w3.org/1999/xhtml">
4 <meta http-equiv=
"Content-Type" content=
"text/html; charset=iso-8859-1" />
5 <title>god - process and task monitoring done right
</title>
6 <link href=
"styles.css" rel=
"stylesheet" type=
"text/css" />
7 <style type=
"text/css" media=
"screen">
14 font: normal
.8em/
1.5em
"Trebuchet MS", Verdana, Arial, Helvetica, sans-serif;
16 background: #E6EAE9 url(images/bg_grey.gif);
21 text-decoration: none;
26 text-decoration: underline;
33 background: url(images/god_logo1.gif);
40 border:
1px solid #
444;
48 border:
1px solid #ddd;
51 background: url(images/banner.jpg);
59 background: url(images/red_dot.gif) repeat;
66 font-family:
"Trebuchet MS", Verdana, Arial, Helvetica, sans-serif;
68 text-transform: uppercase;
73 margin-top:
0 !important;
85 text-decoration: none;
91 text-decoration: none;
94 #page_home #menu li.menu_home a {
115 font: bold
1.5em
"Trebuchet MS", Verdana, Arial, Helvetica, sans-serif;
117 text-transform: uppercase;
118 margin:
1.5em
0 .5em
0;
128 margin-left:
1.5em !important;
133 list-style-position: outside;
134 list-style-type: circle;
135 list-style-image: url(images/bullet.jpg);
149 border:
1px solid #ccc;
151 background-color: #efefef;
180 <script type=
"text/javascript" src=
"javascripts/code_highlighter.js"></script>
181 <script type=
"text/javascript" src=
"javascripts/ruby.js"></script>
185 <body id=
"page_home">
187 <div id=
"mothership">
196 <div class="dots"></div>
198 <li class="menu_home"><a href="/">Home</a></li>
199 <li class="menu_contact"><a href="mailto:tom@projectmothership.com">Contact</a></li>
201 <div class="dots"></div>
204 <div class=
"columnleft">
205 <h1>A Better Way to Monitor
</h1>
206 <p>God is an easy to configure, easy to extend monitoring framework written in Ruby.
</p>
207 <p>Keeping your server processes and tasks running should be a simple part of your deployment process. God aims to be the simplest, most powerful monitoring application available.
</p>
210 <div class=
"columnright">
212 <ul class=
"features">
213 <li>Config file is written in Ruby
</li>
214 <li>Easily write your own custom conditions in Ruby
</li>
215 <li>Supports both poll and event based conditions
</li>
216 <li>Different poll conditions can have different intervals
</li>
220 <h1>Installation
</h1>
221 <p>God does not yet have a public release. You can read through these docs (which are likely to change), or if you're really antsy, peruse or clone the code from
<a href=
"http://repo.or.cz/w/god.git">http://repo.or.cz/w/god.git
</a></p>
223 <h1>Finally, a Config File that Makes Sense
</h1>
224 <p>The easiest way to understand how god will make your life better is by looking at a sample config file. The following configuration file is what I use at
<a href=
"http://site.gravatar.com/">gravatar.com
</a> to keep the mongrels running:
</p>
226 <pre><code class=
"ruby"># file: gravatar.god
228 # This is the actual config file used to keep the mongrels of
229 # gravatar.com running.
231 RAILS_ROOT =
"/var/www/gravatar2/current"
234 %w{
8200 8201 8202}.each do |port|
236 w.name =
"gravatar2-mongrel-#{port}"
237 w.interval =
30 # seconds
238 w.start =
"mongrel_rails cluster::start --only #{port} -c #{RAILS_ROOT}"
239 w.stop =
"mongrel_rails cluster::stop --only #{port} -c #{RAILS_ROOT}"
240 w.grace =
10 # seconds
242 pid_file = File.join(RAILS_ROOT,
"log/mongrel.#{port}.pid")
244 w.behavior(:clean_pid_file) do |b|
245 b.pid_file = pid_file
248 w.start_if do |start|
249 start.condition(:process_not_running) do |c|
250 c.interval =
5 # seconds
251 c.pid_file = pid_file
255 w.restart_if do |restart|
256 restart.condition(:memory_usage) do |c|
257 c.pid_file = pid_file
258 c.above = (
150 *
1024) #
150mb
259 c.times = [
3,
5] #
3 out of
5 intervals
262 restart.condition(:cpu_usage) do |c|
263 c.pid_file = pid_file
264 c.above =
50 # percent
272 <p>That's a lot to take in at once, so I'll break it down by section and explain what's going on in each.
</p>
274 <pre><code class=
"ruby">RAILS_ROOT =
"/var/www/gravatar2/current"</code></pre>
276 <p>Here I've set a constant that is used throughout the file. Keeping the
<code>RAILS_ROOT
</code> value in a constant makes it easy to adapt this script to other applications. Because the config file is Ruby code, I can set whatever variables or constants I want that make the configuration more concise and easier to work with.
</p>
278 <pre><code class=
"ruby">God.meddle do |god|
282 <p>The meat of the config file is defined inside a
<code>God.meddle
</code> block.
</p>
284 <pre><code class=
"ruby"> %w{
8200 8201 8202}.each do |port|
288 <p>Because the config file is written in actual Ruby code, we can construct loops and do other intelligent things that are impossible in your every day, run of the mill config file. I need to watch three mongrels, so I simply loop over their port numbers, eliminating duplication and making my life a whole lot easier.
</p>
290 <pre><code class=
"ruby"> god.watch do |w|
291 w.name =
"gravatar2-mongrel-#{port}"
292 w.interval =
30 # seconds
293 w.start =
"mongrel_rails cluster::start --only #{port} -c #{RAILS_ROOT}"
294 w.stop =
"mongrel_rails cluster::stop --only #{port} -c #{RAILS_ROOT}"
295 w.grace =
10 # seconds
300 <p>A
<code>watch
</code> represents a single process or task that has concrete start, stop, and/or restart operations. You can define as many watches as you like inside the
<code>God.meddle
</code> block. In the example above, I've got a Rails instance running in a Mongrel that I need to keep alive. Every watch must have a unique
<code>name
</code> so that it can be identified later on. The
<code>interval
</code> option sets the default poll interval (this can be overridden in each condition). The
<code>start
</code> and
<code>stop
</code> attributes specify the commands to start and stop the process. If no
<code>restart
</code> attribute is set, restart will be represented by a call to stop followed by a call to start. The optional
<code>grace
</code> attribute sets the amount of time following a start/stop/restart command to wait before resuming normal monitoring operations.
</p>
302 <pre><code class=
"ruby"> pid_file = File.join(RAILS_ROOT,
"log/mongrel.#{port}.pid")
</code></pre>
304 <p>A variable to hold the location of the PID file.
</p>
306 <pre><code class=
"ruby"> w.behavior(:clean_pid_file) do |b|
307 b.pid_file = pid_file
310 <p>Behaviors allow you to execute additional commands around start/stop/restart commands. In our case, if the process dies it will leave a PID file behind. The next time a start command is issued, it will fail, complaining about the leftover PID file. We'd like the PID file cleaned up before a start command is issued. The built-in behavior
<code>clean_pid_file
</code> will do just that. All we have to do is specify the location of the PID file.
</p>
312 <pre><code class=
"ruby"> w.start_if do |start|
313 start.condition(:process_not_running) do |c|
314 c.interval =
5 # seconds
315 c.pid_file = pid_file
319 <p>Watches contain conditions grouped by the action to execute should they fail. I start with a
<code>start_if
</code> block that contains a single condition. Conditions are specified by calling
<code>condition
</code> with an identifier, in this case
320 <code>:process_not_running
</code>. Each condition can specify a poll interval that will override the default watch interval. In this case, I want to check that the process is still running every
5 seconds instead of the
30 second interval that other conditions will inherit. The ability to set condition specific poll intervals makes it possible to run costly tests less often then cheap tests.
</p>
322 <pre><code class=
"ruby"> w.restart_if do |restart|
323 restart.condition(:memory_usage) do |c|
324 c.pid_file = pid_file
325 c.above = (
150 *
1024) #
150mb
326 c.times = [
3,
5] #
3 out of
5 intervals
332 <p>Similar to
<code>start_if
</code> there is a
<code>restart_if
</code> command that groups conditions that should trigger a restart. The
<code>memory_usage
</code> condition will fail if the specified process is using too much memory. Once again, the
<code>pid_file
</code> must be set. The maximum allowable amount of memory is specified with the
<code>above
</code> attribute in units of kilobytes. The number of times the test needs to fail in order to trigger a restart is set with
<code>times
</code>. This can be either an integer or an array. An integer means it must fail that many times in a row while an array [x, y] means it must fail x times out of the last y tests.
</p>
334 <pre><code class=
"ruby"> w.restart_if do |restart|
337 restart.condition(:cpu_usage) do |c|
338 c.pid_file = pid_file
339 c.above =
50 # percent
344 <p>To keep an eye on CPU usage, I've employed the
<code>cpu_usage
</code> condition. When CPU usage for a Mongrel process is over
50% for
5 consecutive intervals, it will be restarted.
</p>
346 <h1>Extend God with your own Conditions
</h1>
348 <p>God was designed from the start to allow you to easily write your own custom conditions, making it simple to add tests that are application specific.
</p>
350 <pre><code class=
"ruby">module God
353 class ProcessNotRunning < PollCondition
354 attr_accessor :pid_file
358 valid &= complain(
"You must specify the 'pid_file' attribute
359 for :process_not_running") if self.pid_file.nil?
364 return false unless File.exist?(self.pid_file)
366 pid = File.open(self.pid_file).read.strip
367 System::Process.new(pid).exists?
376 <p>Brought to you by
<a href=
"http://rubyisawesome.com/">Ruby is Awesome
</a></p>