Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 306 lines (230 sloc) 10.612 kb
75b96b05 »
2009-10-31 basic readme
1 # Bluepill
2 Bluepill is a simple process monitoring tool written in Ruby.
3
4 ## Installation
3cd99807 »
2011-03-31 We hosted at rubygems
5 It's hosted on [rubygems.org][rubygems].
75b96b05 »
2009-10-31 basic readme
6
7 sudo gem install bluepill
8
f6161908 »
2009-11-20 info about log file in readme
9 In order to take advantage of logging with syslog, you also need to setup your syslog to log the local6 facility. Edit the appropriate config file for your syslogger (/etc/syslog.conf for syslog) and add a line for local6:
75b96b05 »
2009-10-31 basic readme
10
11 local6.* /var/log/bluepill.log
c40a9958 »
2011-06-01 Use GitHub markup
12
7de2a641 »
2011-03-10 Fix ' in README.md
13 You'll also want to add _/var/log/bluepill.log_ to _/etc/logrotate.d/syslog_ so that it gets rotated.
75b96b05 »
2009-10-31 basic readme
14
15 Lastly, create the _/var/bluepill_ directory for bluepill to store its pid and sock files.
16
17 ## Usage
581c48d2 »
2009-11-22 renamed DSL to config in readme as a clarification
18 ### Config
75b96b05 »
2009-10-31 basic readme
19 Bluepill organizes processes into 3 levels: application -> group -> process. Each process has a few attributes that tell bluepill how to start, stop, and restart it, where to look or put the pid file, what process conditions to monitor and the options for each of those.
20
21 The minimum config file looks something like this:
22
c40a9958 »
2011-06-01 Use GitHub markup
23 ```ruby
75b96b05 »
2009-10-31 basic readme
24 Bluepill.application("app_name") do |app|
25 app.process("process_name") do |process|
26 process.start_command = "/usr/bin/some_start_command"
27 process.pid_file = "/tmp/some_pid_file.pid"
28 end
29 end
c40a9958 »
2011-06-01 Use GitHub markup
30 ```
31
52606c89 »
2009-11-06 corrected error in readme
32 Note that since we specified a PID file and start command, bluepill assumes the process will daemonize itself. If we wanted bluepill to daemonize it for us, we can do (note we still need to specify a PID file):
75b96b05 »
2009-10-31 basic readme
33
c40a9958 »
2011-06-01 Use GitHub markup
34 ```ruby
75b96b05 »
2009-10-31 basic readme
35 Bluepill.application("app_name") do |app|
36 app.process("process_name") do |process|
37 process.start_command = "/usr/bin/some_start_command"
52606c89 »
2009-11-06 corrected error in readme
38 process.pid_file = "/tmp/some_pid_file.pid"
75b96b05 »
2009-10-31 basic readme
39 process.daemonize = true
40 end
41 end
c40a9958 »
2011-06-01 Use GitHub markup
42 ```
43
7de2a641 »
2011-03-10 Fix ' in README.md
44 If you don't specify a stop command, a TERM signal will be sent by default. Similarly, the default restart action is to issue stop and then start.
75b96b05 »
2009-10-31 basic readme
45
46 Now if we want to do something more meaningful, like actually monitor the process, we do:
47
c40a9958 »
2011-06-01 Use GitHub markup
48 ```ruby
75b96b05 »
2009-10-31 basic readme
49 Bluepill.application("app_name") do |app|
50 app.process("process_name") do |process|
51 process.start_command = "/usr/bin/some_start_command"
52 process.pid_file = "/tmp/some_pid_file.pid"
53
54 process.checks :cpu_usage, :every => 10.seconds, :below => 5, :times => 3
55 end
56 end
c40a9958 »
2011-06-01 Use GitHub markup
57 ```
58
75b96b05 »
2009-10-31 basic readme
59 We added a line that checks every 10 seconds to make sure the cpu usage of this process is below 5 percent; 3 failed checks results in a restart. We can specify a two-element array for the _times_ option to say that it 3 out of 5 failed attempts results in a restart.
60
61 To watch memory usage, we just add one more line:
62
c40a9958 »
2011-06-01 Use GitHub markup
63 ```ruby
75b96b05 »
2009-10-31 basic readme
64 Bluepill.application("app_name") do |app|
65 app.process("process_name") do |process|
66 process.start_command = "/usr/bin/some_start_command"
67 process.pid_file = "/tmp/some_pid_file.pid"
68
69 process.checks :cpu_usage, :every => 10.seconds, :below => 5, :times => 3
70 process.checks :mem_usage, :every => 10.seconds, :below => 100.megabytes, :times => [3,5]
71 end
72 end
c40a9958 »
2011-06-01 Use GitHub markup
73 ```
74
75b96b05 »
2009-10-31 basic readme
75 We can tell bluepill to give a process some grace time to start/stop/restart before resuming monitoring:
76
c40a9958 »
2011-06-01 Use GitHub markup
77 ```ruby
75b96b05 »
2009-10-31 basic readme
78 Bluepill.application("app_name") do |app|
79 app.process("process_name") do |process|
80 process.start_command = "/usr/bin/some_start_command"
81 process.pid_file = "/tmp/some_pid_file.pid"
82 process.start_grace_time = 3.seconds
83 process.stop_grace_time = 5.seconds
84 process.restart_grace_time = 8.seconds
85
86 process.checks :cpu_usage, :every => 10.seconds, :below => 5, :times => 3
87 process.checks :mem_usage, :every => 10.seconds, :below => 100.megabytes, :times => [3,5]
88 end
89 end
c40a9958 »
2011-06-01 Use GitHub markup
90 ```
75b96b05 »
2009-10-31 basic readme
91
92 We can group processes by name:
93
c40a9958 »
2011-06-01 Use GitHub markup
94 ```ruby
75b96b05 »
2009-10-31 basic readme
95 Bluepill.application("app_name") do |app|
96 5.times do |i|
97 app.process("process_name_#{i}") do |process|
98 process.group = "mongrels"
99 process.start_command = "/usr/bin/some_start_command"
100 process.pid_file = "/tmp/some_pid_file.pid"
101 end
102 end
103 end
c40a9958 »
2011-06-01 Use GitHub markup
104 ```
75b96b05 »
2009-10-31 basic readme
105
106 If you want to run the process as someone other than root:
107
c40a9958 »
2011-06-01 Use GitHub markup
108 ```ruby
75b96b05 »
2009-10-31 basic readme
109 Bluepill.application("app_name") do |app|
110 app.process("process_name") do |process|
111 process.start_command = "/usr/bin/some_start_command"
112 process.pid_file = "/tmp/some_pid_file.pid"
113 process.uid = "deploy"
114 process.gid = "deploy"
115
116 process.checks :cpu_usage, :every => 10.seconds, :below => 5, :times => 3
117 process.checks :mem_usage, :every => 10.seconds, :below => 100.megabytes, :times => [3,5]
118 end
119 end
c40a9958 »
2011-06-01 Use GitHub markup
120 ```
121
cd07c3b5 »
2011-08-19 Adding supplementary groups to readme.
122 If you want to include one or more supplementary groups:
123
124 ```ruby
125 Bluepill.application("app_name") do |app|
126 app.process("process_name") do |process|
127 process.start_command = "/usr/bin/some_start_command"
128 process.pid_file = "/tmp/some_pid_file.pid"
129 process.uid = "deploy"
130 process.gid = "deploy"
131 process.supplementary_groups = ['rvm']
132
133 process.checks :cpu_usage, :every => 10.seconds, :below => 5, :times => 3
134 process.checks :mem_usage, :every => 10.seconds, :below => 100.megabytes, :times => [3,5]
135 end
136 end
137 ```
138
36a83f0f »
2009-11-22 added info about working dir and new app-wide config options to README
139 You can also set an app-wide uid/gid:
140
c40a9958 »
2011-06-01 Use GitHub markup
141 ```ruby
36a83f0f »
2009-11-22 added info about working dir and new app-wide config options to README
142 Bluepill.application("app_name") do |app|
143 app.uid = "deploy"
144 app.gid = "deploy"
145 app.process("process_name") do |process|
146 process.start_command = "/usr/bin/some_start_command"
147 process.pid_file = "/tmp/some_pid_file.pid"
148 end
149 end
c40a9958 »
2011-06-01 Use GitHub markup
150 ```
151
75b96b05 »
2009-10-31 basic readme
152 To check for flapping:
153
c40a9958 »
2011-06-01 Use GitHub markup
154 ```ruby
75b96b05 »
2009-10-31 basic readme
155 process.checks :flapping, :times => 2, :within => 30.seconds, :retry_in => 7.seconds
c40a9958 »
2011-06-01 Use GitHub markup
156 ```
157
36a83f0f »
2009-11-22 added info about working dir and new app-wide config options to README
158 To set the working directory to _cd_ into when starting the command:
159
c40a9958 »
2011-06-01 Use GitHub markup
160 ```ruby
36a83f0f »
2009-11-22 added info about working dir and new app-wide config options to README
161 Bluepill.application("app_name") do |app|
162 app.process("process_name") do |process|
163 process.start_command = "/usr/bin/some_start_command"
164 process.pid_file = "/tmp/some_pid_file.pid"
165 process.working_dir = "/path/to/some_directory"
166 end
167 end
c40a9958 »
2011-06-01 Use GitHub markup
168 ```
36a83f0f »
2009-11-22 added info about working dir and new app-wide config options to README
169
c40a9958 »
2011-06-01 Use GitHub markup
170 You can also have an app-wide working directory:
36a83f0f »
2009-11-22 added info about working dir and new app-wide config options to README
171
c40a9958 »
2011-06-01 Use GitHub markup
172 ```ruby
36a83f0f »
2009-11-22 added info about working dir and new app-wide config options to README
173 Bluepill.application("app_name") do |app|
174 app.working_dir = "/path/to/some_directory"
175 app.process("process_name") do |process|
176 process.start_command = "/usr/bin/some_start_command"
177 process.pid_file = "/tmp/some_pid_file.pid"
178 end
179 end
c40a9958 »
2011-06-01 Use GitHub markup
180 ```
36a83f0f »
2009-11-22 added info about working dir and new app-wide config options to README
181
c40a9958 »
2011-06-01 Use GitHub markup
182 Note: We also set the PWD in the environment to the working dir you specify. This is useful for when the working dir is a symlink. Unicorn in particular will cd into the environment variable in PWD when it re-execs to deal with a change in the symlink.
75b96b05 »
2009-10-31 basic readme
183
46bdcd41 »
2011-08-19 Adding stop_command and stop_signals to readme.
184 By default, bluepill will send a SIGTERM to your process when stopping.
185 To change the stop command:
186
187 ```ruby
188 Bluepill.application("app_name") do |app|
189 app.process("process_name") do |process|
190 process.start_command = "/usr/bin/some_start_command"
191 process.pid_file = "/tmp/some_pid_file.pid"
192 process.stop_command = "/user/bin/some_stop_command"
193 end
194 end
195 ```
196
197 If you'd like to send a signal or signals to your process to stop it:
198
199 ```ruby
200 Bluepill.application("app_name") do |app|
201 app.process("process_name") do |process|
202 process.start_command = "/usr/bin/some_start_command"
203 process.pid_file = "/tmp/some_pid_file.pid"
204 process.stop_signals = [:quit, 30.seconds, :term, 5.seconds, :kill]
205 end
206 end
207 ```
208
209 We added a line that will send a SIGQUIT, wait 30 seconds and check to
210 see if the process is still up, send a SIGTERM, wait 5 seconds and check
211 to see if the process is still up, and finally send a SIGKILL.
212
75b96b05 »
2009-10-31 basic readme
213 And lastly, to monitor child processes:
214
c40a9958 »
2011-06-01 Use GitHub markup
215 ```ruby
75b96b05 »
2009-10-31 basic readme
216 process.monitor_children do |child_process|
217 child_process.checks :cpu_usage, :every => 10, :below => 5, :times => 3
218 child_process.checks :mem_usage, :every => 10, :below => 100.megabytes, :times => [3, 5]
219
220 child_process.stop_command = "kill -QUIT {{PID}}"
221 end
c40a9958 »
2011-06-01 Use GitHub markup
222 ```
223
75b96b05 »
2009-10-31 basic readme
224 Note {{PID}} will be substituted for the pid of process in both the stop and restart commands.
225
1bdd6a58 »
2009-11-16 removed racy bash style output redirection support in start_commands and
226 ### A Note About Output Redirection
227
228 While you can specify shell tricks like the following in the start_command of a process:
c40a9958 »
2011-06-01 Use GitHub markup
229
230 ```ruby
1bdd6a58 »
2009-11-16 removed racy bash style output redirection support in start_commands and
231 Bluepill.application("app_name") do |app|
232 app.process("process_name") do |process|
233 process.start_command = "cd /tmp/some_dir && SOME_VAR=1 /usr/bin/some_start_command > /tmp/server.log 2>&1"
234 process.pid_file = "/tmp/some_pid_file.pid"
235 end
236 end
c40a9958 »
2011-06-01 Use GitHub markup
237 ```
238
581c48d2 »
2009-11-22 renamed DSL to config in readme as a clarification
239 We recommend that you _not_ do that and instead use the config options to capture output from your daemons. Like so:
1bdd6a58 »
2009-11-16 removed racy bash style output redirection support in start_commands and
240
c40a9958 »
2011-06-01 Use GitHub markup
241 ```ruby
1bdd6a58 »
2009-11-16 removed racy bash style output redirection support in start_commands and
242 Bluepill.application("app_name") do |app|
243 app.process("process_name") do |process|
244 process.start_command = "/usr/bin/env SOME_VAR=1 /usr/bin/some_start_command"
245
246 process.working_dir = "/tmp/some_dir"
247 process.stdout = process.stderr = "/tmp/server.log"
248
249 process.pid_file = "/tmp/some_pid_file.pid"
250 end
251 end
c40a9958 »
2011-06-01 Use GitHub markup
252 ```
253
581c48d2 »
2009-11-22 renamed DSL to config in readme as a clarification
254 The main benefit of using the config options is that Bluepill will be able to monitor the correct process instead of just watching the shell that spawned your actual server.
1bdd6a58 »
2009-11-16 removed racy bash style output redirection support in start_commands and
255
75b96b05 »
2009-10-31 basic readme
256 ### CLI
257 To start a bluepill process and load a config:
258
259 sudo bluepill load /path/to/production.pill
c40a9958 »
2011-06-01 Use GitHub markup
260
75b96b05 »
2009-10-31 basic readme
261 To act on a process or group:
262
263 sudo bluepill <start|stop|restart|unmonitor> <process_or_group_name>
c40a9958 »
2011-06-01 Use GitHub markup
264
75b96b05 »
2009-10-31 basic readme
265 To view process statuses:
266
267 sudo bluepill status
268
269 To view the log for a process or group:
270
271 sudo bluepill log <process_or_group_name>
272
273 To quit bluepill:
274
275 sudo bluepill quit
f6161908 »
2009-11-20 info about log file in readme
276
277 ### Logging
3448450a »
2011-03-10 Fix ' in README.md
278 By default, bluepill uses syslog local6 facility as described in the installation section. But if for any reason you don&apos;t want to use syslog, you can use a log file. You can do this by setting the :log\_file option in the config:
f6161908 »
2009-11-20 info about log file in readme
279
c40a9958 »
2011-06-01 Use GitHub markup
280 ```ruby
f6161908 »
2009-11-20 info about log file in readme
281 Bluepill.application("app_name", :log_file => "/path/to/bluepill.log") do |app|
282 # ...
283 end
c40a9958 »
2011-06-01 Use GitHub markup
284 ```
f6161908 »
2009-11-20 info about log file in readme
285
286 Keep in mind that you still need to set up log rotation (described in the installation section) to keep the log file from growing huge.
75b96b05 »
2009-10-31 basic readme
287
811f75f5 »
2010-03-14 added to readme for foreground option.
288 ### Extra options
289 You can run bluepill in the foreground:
290
c40a9958 »
2011-06-01 Use GitHub markup
291 ```ruby
811f75f5 »
2010-03-14 added to readme for foreground option.
292 Bluepill.application("app_name", :foreground => true) do |app|
293 # ...
294 end
c40a9958 »
2011-06-01 Use GitHub markup
295 ```
811f75f5 »
2010-03-14 added to readme for foreground option.
296
c12dbb5b »
2011-04-23 Note about only one application per config for foreground mode.
297 Note that You must define only one application per config when using foreground mode.
298
b9b167c3 »
2009-11-27 added link to mailing list in readme
299 ## Links
75b96b05 »
2009-10-31 basic readme
300 Code: [http://github.com/arya/bluepill](http://github.com/arya/bluepill)
301 Bugs/Features: [http://github.com/arya/bluepill/issues](http://github.com/arya/bluepill/issues)
b9b167c3 »
2009-11-27 added link to mailing list in readme
302 Mailing List: [http://groups.google.com/group/bluepill-rb](http://groups.google.com/group/bluepill-rb)
75b96b05 »
2009-10-31 basic readme
303
304
3cd99807 »
2011-03-31 We hosted at rubygems
305 [rubygems]: http://rubygems.org/gems/bluepill
75b96b05 »
2009-10-31 basic readme
306
Something went wrong with that request. Please try again.