bluepill 0.0.10 → 0.0.11

data/DESIGN.markdown

@@ -0,0 +1,10 @@
+## Bluepill Design
+Here are just some bullet points of the design. We'll add details later.
+
+ * Each process monitors a single _application_, so you can have multiple bluepill processes on a system
+ * Use rotational arrays for storing historical data for monitoring process conditions
+ * Memo-ize output of _ps_ per tick as an optimization for applications with many processes
+ * Use socket files to communicate between CLI and daemon
+ * DSL is a separate layer, the core of the monitoring just uses regular initializers, etc. DSL is simply for ease of use and should not interfere with business logic
+ * Sequentially process user issued commands so no weird race cases occur
+ * Triggers are notified by the state machine on any process state transitions

data/README.markdown

@@ -0,0 +1,149 @@
+# Bluepill
+Bluepill is a simple process monitoring tool written in Ruby. 
+
+## Installation
+It's hosted on [gemcutter.org][gemcutter].
+
+    sudo gem install bluepill
+    
+In order to take advantage of logging, 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:
+
+    local6.*          /var/log/bluepill.log
+    
+You'll also want to add _/var/log/bluepill.log_ to _/etc/logrotate.d/syslog_ so that it gets rotated.
+
+Lastly, create the _/var/bluepill_ directory for bluepill to store its pid and sock files.
+
+## Usage
+### DSL
+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.
+
+The minimum config file looks something like this:
+
+    Bluepill.application("app_name") do |app|
+      app.process("process_name") do |process|
+        process.start_command = "/usr/bin/some_start_command"
+        process.pid_file = "/tmp/some_pid_file.pid"
+      end
+    end
+    
+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:
+
+    Bluepill.application("app_name") do |app|
+      app.process("process_name") do |process|
+        process.start_command = "/usr/bin/some_start_command"
+        process.daemonize = true
+      end
+    end
+    
+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.
+
+Now if we want to do something more meaningful, like actually monitor the process, we do:
+
+    Bluepill.application("app_name") do |app|
+      app.process("process_name") do |process|
+        process.start_command = "/usr/bin/some_start_command"
+        process.pid_file = "/tmp/some_pid_file.pid"
+        
+        process.checks :cpu_usage, :every => 10.seconds, :below => 5, :times => 3
+      end
+    end
+    
+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.
+
+To watch memory usage, we just add one more line:
+
+    Bluepill.application("app_name") do |app|
+      app.process("process_name") do |process|
+        process.start_command = "/usr/bin/some_start_command"
+        process.pid_file = "/tmp/some_pid_file.pid"
+
+        process.checks :cpu_usage, :every => 10.seconds, :below => 5, :times => 3        
+        process.checks :mem_usage, :every => 10.seconds, :below => 100.megabytes, :times => [3,5]
+      end
+    end
+    
+We can tell bluepill to give a process some grace time to start/stop/restart before resuming monitoring:
+
+    Bluepill.application("app_name") do |app|
+      app.process("process_name") do |process|
+        process.start_command = "/usr/bin/some_start_command"
+        process.pid_file = "/tmp/some_pid_file.pid"
+        process.start_grace_time = 3.seconds
+        process.stop_grace_time = 5.seconds
+        process.restart_grace_time = 8.seconds
+
+        process.checks :cpu_usage, :every => 10.seconds, :below => 5, :times => 3        
+        process.checks :mem_usage, :every => 10.seconds, :below => 100.megabytes, :times => [3,5]
+      end
+    end
+
+We can group processes by name:
+
+    Bluepill.application("app_name") do |app|
+      5.times do |i|
+        app.process("process_name_#{i}") do |process|
+          process.group = "mongrels"
+          process.start_command = "/usr/bin/some_start_command"
+          process.pid_file = "/tmp/some_pid_file.pid"
+        end
+      end
+    end
+
+If you want to run the process as someone other than root:
+
+    Bluepill.application("app_name") do |app|
+      app.process("process_name") do |process|
+        process.start_command = "/usr/bin/some_start_command"
+        process.pid_file = "/tmp/some_pid_file.pid"
+        process.uid = "deploy"
+        process.gid = "deploy"
+
+        process.checks :cpu_usage, :every => 10.seconds, :below => 5, :times => 3        
+        process.checks :mem_usage, :every => 10.seconds, :below => 100.megabytes, :times => [3,5]
+      end
+    end
+    
+To check for flapping:
+
+    process.checks :flapping, :times => 2, :within => 30.seconds, :retry_in => 7.seconds
+
+And lastly, to monitor child processes:
+
+    process.monitor_children do |child_process|
+      child_process.checks :cpu_usage, :every => 10, :below => 5, :times => 3
+      child_process.checks :mem_usage, :every => 10, :below => 100.megabytes, :times => [3, 5]
+      
+      child_process.stop_command = "kill -QUIT {{PID}}"
+    end
+    
+Note {{PID}} will be substituted for the pid of process in both the stop and restart commands.
+
+### CLI
+To start a bluepill process and load a config:
+
+    sudo bluepill load /path/to/production.pill
+    
+To act on a process or group:
+
+    sudo bluepill <start|stop|restart|unmonitor> <process_or_group_name>
+    
+To view process statuses:
+
+    sudo bluepill status
+
+To view the log for a process or group:
+
+    sudo bluepill log <process_or_group_name>
+
+To quit bluepill:
+
+    sudo bluepill quit
+    
+## Contribute
+Code: [http://github.com/arya/bluepill](http://github.com/arya/bluepill)  
+Bugs/Features: [http://github.com/arya/bluepill/issues](http://github.com/arya/bluepill/issues)  
+
+
+[gemcutter]: http://gemcutter.org
+    

data/Rakefile

@@ -13,7 +13,8 @@ begin
     gem.add_development_dependency "rspec"
     # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
     gem.add_dependency("daemons", ">= 1.0.9")
-    gem.add_dependency("pluginaweek-state_machine", ">= 0.8.0")
+    gem.add_dependency("blankslate", ">= 2.1.2.2")
+    gem.add_dependency("state_machine", ">= 0.8.0")
     gem.add_dependency("activesupport", ">= 2.3.4")
 
     gem.files -= ["bin/sample_forking_server"]

data/VERSION

@@ -1 +1 @@
-0.0.10
+0.0.11

data/bluepill.gemspec

@@ -5,28 +5,26 @@
 
 Gem::Specification.new do |s|
   s.name = %q{bluepill}
-  s.version = "0.0.10"
+  s.version = "0.0.11"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Arya Asemanfar", "Gary Tsang", "Rohith Ravi"]
-  s.date = %q{2009-10-26}
+  s.date = %q{2009-11-03}
   s.default_executable = %q{bluepill}
   s.description = %q{Bluepill keeps your daemons up while taking up as little resources as possible. After all you probably want the resources of your server to be used by whatever daemons you are running rather than the thing that's supposed to make sure they are brought back up, should they die or misbehave.}
   s.email = %q{entombedvirus@gmail.com}
   s.executables = ["bluepill"]
   s.extra_rdoc_files = [
     "LICENSE",
-     "README",
-     "README.rdoc"
+     "README.markdown"
   ]
   s.files = [
     ".document",
      ".gitignore",
+     "DESIGN.markdown",
      "LICENSE",
-     "README",
-     "README.rdoc",
+     "README.markdown",
      "Rakefile",
-     "TODO",
      "VERSION",
      "bin/bluepill",
      "bluepill.gemspec",
@@ -59,7 +57,7 @@ Gem::Specification.new do |s|
   s.homepage = %q{http://github.com/arya/bluepill}
   s.rdoc_options = ["--charset=UTF-8"]
   s.require_paths = ["lib"]
-  s.rubygems_version = %q{1.3.5}
+  s.rubygems_version = %q{1.3.4}
   s.summary = %q{A process monitor written in Ruby with stability and minimalism in mind.}
   s.test_files = [
     "spec/blue-pill_spec.rb",
@@ -74,18 +72,21 @@ Gem::Specification.new do |s|
     if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
       s.add_development_dependency(%q<rspec>, [">= 0"])
       s.add_runtime_dependency(%q<daemons>, [">= 1.0.9"])
-      s.add_runtime_dependency(%q<pluginaweek-state_machine>, [">= 0.8.0"])
+      s.add_runtime_dependency(%q<blankslate>, [">= 2.1.2.2"])
+      s.add_runtime_dependency(%q<state_machine>, [">= 0.8.0"])
       s.add_runtime_dependency(%q<activesupport>, [">= 2.3.4"])
     else
       s.add_dependency(%q<rspec>, [">= 0"])
       s.add_dependency(%q<daemons>, [">= 1.0.9"])
-      s.add_dependency(%q<pluginaweek-state_machine>, [">= 0.8.0"])
+      s.add_dependency(%q<blankslate>, [">= 2.1.2.2"])
+      s.add_dependency(%q<state_machine>, [">= 0.8.0"])
       s.add_dependency(%q<activesupport>, [">= 2.3.4"])
     end
   else
     s.add_dependency(%q<rspec>, [">= 0"])
     s.add_dependency(%q<daemons>, [">= 1.0.9"])
-    s.add_dependency(%q<pluginaweek-state_machine>, [">= 0.8.0"])
+    s.add_dependency(%q<blankslate>, [">= 2.1.2.2"])
+    s.add_dependency(%q<state_machine>, [">= 0.8.0"])
     s.add_dependency(%q<activesupport>, [">= 2.3.4"])
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: bluepill
 version: !ruby/object:Gem::Version 
-  version: 0.0.10
+  version: 0.0.11
 platform: ruby
 authors: 
 - Arya Asemanfar
@@ -11,7 +11,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-10-26 00:00:00 -07:00
+date: 2009-11-03 00:00:00 -08:00
 default_executable: bluepill
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -35,7 +35,17 @@ dependencies:
         version: 1.0.9
     version: 
 - !ruby/object:Gem::Dependency 
-  name: pluginaweek-state_machine
+  name: blankslate
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 2.1.2.2
+    version: 
+- !ruby/object:Gem::Dependency 
+  name: state_machine
   type: :runtime
   version_requirement: 
   version_requirements: !ruby/object:Gem::Requirement 
@@ -62,16 +72,14 @@ extensions: []
 
 extra_rdoc_files: 
 - LICENSE
-- README
-- README.rdoc
+- README.markdown
 files: 
 - .document
 - .gitignore
+- DESIGN.markdown
 - LICENSE
-- README
-- README.rdoc
+- README.markdown
 - Rakefile
-- TODO
 - VERSION
 - bin/bluepill
 - bluepill.gemspec
@@ -124,7 +132,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 
 rubyforge_project: 
-rubygems_version: 1.3.5
+rubygems_version: 1.3.4
 signing_key: 
 specification_version: 3
 summary: A process monitor written in Ruby with stability and minimalism in mind.

data/README.rdoc

@@ -1,18 +0,0 @@
-= little-blue-pill
-
-Description goes here.
-
-== Note on Patches/Pull Requests
- 
-* Fork the project.
-* Make your feature addition or bug fix.
-* Add tests for it. This is important so I don't break it in a
-  future version unintentionally.
-* Commit, do not mess with rakefile, version, or history.
-  (if you want to have your own version, that is fine but
-   bump version in a commit by itself I can ignore when I pull)
-* Send me a pull request. Bonus points for topic branches.
-
-== Copyright
-
-Copyright (c) 2009 garru. See LICENSE for details.

data/TODO

@@ -1,22 +0,0 @@
-* Figure out proper logger lvl for each msg. So a person can choose only to log local6.warn and get only state transition messages and not any of the watch chatter.
-* Better error output than just vanilla exception traces
-* Better output for cli commands than just "ok"
-* munin support?
-
-
-Issues encountered in the wild
-------------------------------
-
-* Whenever bluepill executes user specified commands (like start_command, stop_command, restart_command), it should execute it in such a way that it does not affect the stability of bluepill daemon itself.
-
-* Whenever a command is sent to a process group, execute them in parallel for each process in the group instead of serially.
-
-* Issuing commands to the running bluepill daemon using the cli can trigger flapping condition. So, running bluepill restart <blah> can cause a flapping trigger to be fired depending on internal state.
-
-* Have validations for easy to make mistakes in the config file. For ex:
-  + Accidently specifying the same pid file for multiple processes. 
-  + Accidently specifying the same process name for multiple processes.
-  + Validate the minimum number of config options to setup successful monitoring. 
-  
-For example, for a valid "process", the only 2 things that are required are the start command and the pid file. We should tell a user at the time of loading whether the config file is syntactically and semantically valid.
-