cognizant 0.0.1

data/.gitignore

@@ -0,0 +1,18 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+.DS_Store

data/.yardopts

@@ -0,0 +1 @@
+--asset images:images

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in cognizant.gemspec
+gemspec

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2012 Gurpartap Singh
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,160 @@
+# Cognizant
+
+Cognizant is a system utility that supervises your processes, ensuring their
+state based on a flexible criteria.
+
+In simpler terms, cognizant keeps your processes up and running. It ensures
+that something productive (like restart) is done when the process being
+monitored matches a certain condition (like RAM, CPU usage or a custom
+condition).
+
+PS: Although the core works efficiently, yet the command interface to the
+utility, documentation and some other features need a lot of work.
+Contributions will be overwhelmingly welcomed!
+
+PS2: This README is written as a roadmap for the features cognizant would
+ideally provide. Some of them might not yet be implemented (e.g. conditions).
+
+Cognizant can be used to monitor any long running process, including the
+following examples:
+
+- Web servers (Nginx, Apache httpd, WebSocket, etc.)
+- Databases (Redis, MongoDB, MySQL, PostgreSQL, etc.)
+- Job workers (Resque, Sidekiq, etc.)
+- Message queue applications (RabbitMQ, Beanstalkd, etc.)
+- Logs collection daemon
+- Or any other program that needs to keep running
+
+## Monitoring
+
+Cognizant can be used to monitor an application process' state so that it
+is running at all times. When cognizant is instructed to monitor a process,
+by default, the process will automatically be started. These processes are
+automatically monitored for their state. i.e. a process is automatically
+started again if it stops unexpectedly.
+
+## Conditions
+
+Conditions provide a way to monitor and act on more than just the state of a
+process. For example, conditions can monitor the resource utilization (RAM,
+CPU, etc.) of the application process and restart it if it matches a
+condition.
+
+## Getting started
+
+Cognizant is written in the Ruby programming language, and hence depends on
+it. Ensure that you have Ruby 1.9+ installed and run:
+
+    $ gem install cognizant
+
+## Architecture overview
+
+                                                          _____
+                                                 ___________   |
+     ____________          ____________         |           |  |
+    |            |        |            | -----> | Process A |  |
+    | Admin      |        | Monitoring |        |___________|  |
+    | Utility    | -----> | Daemon     |         ___________   | -- Managed Processes
+    | >_         |        |            |        |           |  |
+    |____________|        |____________| -----> | Process B |  |
+                                                |___________|  |
+                                                          _____|
+
+Since cognizant administration and process monitoring are two separate concerns, they are serviced by separate applications, `cognizant` and `cognizantd`, respectively.
+
+## Starting the monitoring daemon
+
+Cognizant runs the monitoring essentials through the `cognizantd` daemon application, which also maintains a server for accepting commands from the `cognizant` administration utility.
+
+The daemon, with it's default options, requires superuser access to certain system directories for storing logs and pid files. It can be started as follows:
+
+    $ sudo cognizantd    # ubuntu, debian, os x, etc.
+    $ su -c 'cognizantd' # amazon linux, centos, rhel, etc.
+
+To start without superuser access, specify these file and directory config variables to where the user starting it has write access:
+
+    $ cognizantd ~/.cognizant/cognizantd.yml
+    
+    # assuming that:
+    
+    $ cat ~/.cognizant/cognizantd.yml
+    ---
+    socket:   ~/.cognizant/cognizantd.sock
+    pidfile:  ~/.cognizant/cognizantd.pid
+    logfile:  ~/.cognizant/cognizantd.log
+    pids_dir: ~/.cognizant/pids/
+    logs_dir: ~/.cognizant/logs/
+
+or
+
+    # pass config directly into the daemon's STDIN
+    $ echo <<EOF | cognizantd -
+    ---
+    socket:   ~/.cognizant/cognizantd.sock
+    pidfile:  ~/.cognizant/cognizantd.pid
+    logfile:  ~/.cognizant/cognizantd.log
+    pids_dir: ~/.cognizant/pids/
+    logs_dir: ~/.cognizant/logs/
+    EOF
+
+## Using the administration utility
+
+Cognizant can be administered using the `cognizant` command line utility. This is an application for performing administration tasks like monitoring, starting, stopping processes or loading configuration and processes' information.
+
+Here's how you tell cognizant to start monitoring a new process:
+
+    $ cognizant monitor --name          resque-worker-1                \
+                        --group         resque                         \
+                        --chdir         /apps/example/current/         \
+                        --start_command "bundle exec rake resque:work"
+
+Now check it's status:
+
+    $ cognizant status resque-worker-1
+    ---
+    resque-worker-1: {
+      state: running,
+      uptime: 3600 # 1 hour
+    }
+
+Or check status of all processes:
+
+    $ cognizant status resque-worker-1
+    ---
+    redis-server: {
+      state: running,
+      uptime: 5400 # 1 hour 30 minutes
+    },
+    resque-worker-1: {
+      group: resque,
+      state: running,
+      uptime: 3600 # 1 hour
+    },
+    resque-worker-2: {
+      group: resque,
+      state: stoppped,
+      uptime: 0
+    }
+
+### Works anywhere
+
+Cognizant can be used on any operating system where Ruby 1.9+ works.
+
+### What are the other programs similar to cognizant?
+
+- Monit
+- God (Ruby)
+- Bluepill (Ruby)
+- Supervisord (Python)
+- Upstart
+- SysV Init
+- Systemd
+- Launchd
+
+### Which one of these should I be using?
+
+The one that gets your job done efficiently.
+
+### What does the term "cognizant" mean?
+
+If it matters, cognizant means "having knowledge or being aware of", according to Apple's Dictionary.

data/Rakefile

@@ -0,0 +1,2 @@
+#!/usr/bin/env rake
+require "bundler/gem_tasks"

data/bin/cognizant

@@ -0,0 +1,58 @@
+#!/usr/bin/env ruby
+
+# Set the process name.
+$0 = File.basename(__FILE__)
+
+# Flush standard output/error immediately.
+$stdout.sync = true
+$stderr.sync = true
+
+begin
+  require 'optparse'
+
+  options = {
+    socket: "/var/run/cognizant/cognizantd.sock"
+  }
+
+  OptionParser.new do |opts|
+    opts.banner = <<-EOF
+  Usage:
+    cognizant [OPTIONS] command
+
+  Options:
+    EOF
+
+    opts.on("-s FILE", "--socket FILE", String, "The socket lock file for the server") do |value|
+      options[:socket] = value
+    end
+
+    opts.on("-b ADDRESS", "--bind-address ADDRESS", String, "The interface to bind the TCP server to.") do |value|
+      options[:bind_address] = value
+    end
+
+    opts.on("-p PORT", "--port PORT", Integer, "The TCP port to start the server with.") do |value|
+      options[:port] = value
+    end
+
+    opts.on("--username USERNAME", String, "Username for securing server access.") do |value|
+      options[:username] = value
+    end
+
+    opts.on("--password PASSWORD", String, "Password to accompany the username.") do |value|
+      options[:password] = value
+    end
+
+    opts.on("-t", "--trace", "Turn on tracing, enable full backtrace.") do
+      options[:trace] = true
+    end
+
+    opts.on("-v", "--version", "Print the version number and exit.") do
+      require 'cognizant/version'
+      $stdout.puts Cognizant::VERSION
+      exit(0)
+    end
+  end.parse!
+
+  require 'cognizant'
+  Cognizant.add_process(options)
+end

data/bin/cognizantd

@@ -0,0 +1,124 @@
+#!/usr/bin/env ruby
+
+# Set the process name.
+$0 = File.basename(__FILE__)
+
+# Flush standard output/error immediately.
+$stdout.sync = true
+$stderr.sync = true
+
+begin
+  require 'optparse'
+
+  options = {}
+
+  OptionParser.new do |opts|
+    opts.banner = <<-EOF
+  Usage:
+    cognizantd [OPTIONS] [CONFIG | -]
+
+  Options:
+    EOF
+
+    opts.on("--[no-]daemonize", "Whether or not to daemonize cognizant into background.") do |value|
+      options[:daemonize] = value
+    end
+
+    opts.on("--pidfile FILE", String, "The pid lock file for the daemon.") do |value|
+      options[:pidfile] = value
+    end
+
+    opts.on("--logfile FILE", String, "The file to log the daemon's operations information into.") do |value|
+      options[:logfile] = value
+    end
+
+    opts.on("--loglevel LEVEL", String, "The level of information to log.") do |value|
+      options[:loglevel] = value
+    end
+
+    opts.on("--env ENV", String, "Environment variables for managed processes to inherit.") do |value|
+      options[:env] = value
+    end
+
+    opts.on("--chdir DIRECTORY", String, "The current working directory for the managed processes to start with.") do |value|
+      options[:chdir] = value
+    end
+
+    opts.on("--umask UMASK", String, "Permission mode limitations for file and directory creation.") do |value|
+      options[:umask] = value
+    end
+
+    opts.on("--user USER", String, "Run the daemon and managed processes as the given user.") do |value|
+      options[:user] = value
+    end
+
+    opts.on("--group GROUP", String, "Run the daemon and managed processes as the given user group.") do |value|
+      options[:group] = value
+    end
+
+    opts.on("--pids-dir DIRECTORY", String, "Directory to store the pid files of managed processes, when required.") do |value|
+      options[:pids_dir] = value
+    end
+
+    opts.on("--logs-dir DIRECTORY", String, "Directory to store the log files of managed processes, when required.") do |value|
+      options[:logs_dir] = value
+    end
+
+    opts.on("-s FILE", "--socket FILE", String, "The socket lock file for the server") do |value|
+      options[:socket] = value
+    end
+
+    opts.on("-b ADDRESS", "--bind-address ADDRESS", String, "The interface to bind the TCP server to.") do |value|
+      options[:bind_address] = value
+    end
+
+    opts.on("-p PORT", "--port PORT", Integer, "The TCP port to start the server with.") do |value|
+      options[:port] = value
+    end
+
+    opts.on("--username USERNAME", String, "Username for securing server access.") do |value|
+      options[:username] = value
+    end
+
+    opts.on("--password PASSWORD", String, "Password to accompany the username.") do |value|
+      options[:password] = value
+    end
+
+    opts.on("-t", "--trace", "Turn on tracing, enable full backtrace.") do
+      options[:trace] = true
+    end
+
+    opts.on("-v", "--version", "Print the version number and exit.") do
+      require 'cognizant/version'
+      $stdout.puts Cognizant::VERSION
+      exit(0)
+    end
+  end.parse!
+
+  if config_file = ARGV.shift
+    if config_file.eql?("-")
+      config = YAML.load(ARGF.read)
+    else
+      config = YAML.load_file(config_file)
+    end
+    config = config.inject({}) { |c,(k,v)| c[k.gsub("-", "_").to_sym] = v; c }
+    options = config.merge(options)
+  end
+
+  require 'cognizant/server'
+  Cognizant::Server.start(options)
+rescue => exception
+  if exception.instance_of?(SystemExit)
+    raise
+  else
+    $stderr.puts "ERROR: While executing #{$0} ... (#{exception.class})"
+    $stderr.puts "    #{exception.message}\n\n"
+    if options[:trace]
+      $stderr.puts exception.backtrace.join("\n")
+      $stderr.puts "\n(See usage by running #{$0} with --help)"
+    else
+      $stderr.puts "(See full trace by running #{$0} with --trace)"
+    end
+    exit(1)
+  end
+end

data/cognizant.gemspec

@@ -0,0 +1,24 @@
+# -*- encoding: utf-8 -*-
+require File.expand_path('../lib/cognizant/version', __FILE__)
+
+Gem::Specification.new do |gem|
+  gem.authors       = ["Gurpartap Singh"]
+  gem.email         = ["contact@gurpartap.com"]
+  gem.description   = "Process monitoring and management framework"
+  gem.summary       = "Cognizant is an advanced and efficient process monitoring and management framework."
+  gem.homepage      = "http://gurpartap.github.com/cognizant/"
+
+  gem.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  gem.files         = `git ls-files`.split("\n")
+  gem.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  gem.name          = "cognizant"
+  gem.require_paths = ["lib"]
+  gem.version       = Cognizant::VERSION
+
+  gem.add_development_dependency "rake"
+  gem.add_development_dependency "redcarpet"
+  gem.add_development_dependency "yard"
+
+  gem.add_dependency "eventmachine"
+  gem.add_dependency "state_machine"
+end

data/examples/cognizantd.yml

@@ -0,0 +1,23 @@
+---
+daemonize: false
+pidfile: ~/.cognizant/cognizantd.pid
+logfile: ~/.cognizant/cognizantd.log
+socket: ~/.cognizant/cognizantd.sock
+pids_dir: ~/.cognizant/pids/
+logs_dir: ~/.cognizant/logs/
+
+monitor: {
+  redis-server: {
+    start_command: /usr/local/bin/redis-server -,
+    start_with_input: daemonize no,
+    ping_command: redis-cli PING,
+    autostart: true,
+    stop_timeout: 5,
+    start_timeout: 2,
+    restart_timeout: 2
+  },
+  sleep-10: {
+    start_command: sleep 10,
+    autostart: true
+  }
+}

data/examples/redis-server.rb

@@ -0,0 +1,17 @@
+# 4 slave instances to master at port 6000.
+5.times do |i|
+  Cognizant.monitor "redis-server-600#{i}" do |process|
+    process.group            = "redis"
+    process.uid              = "redis"
+    process.gid              = "redis"
+    process.start_command    = "redis-server -"
+    process.ping_command     = "redis-cli -p 600#{i} PING"
+
+    slaveof = i == 0 ? "" : "slaveof 127.0.0.1 6000"
+    process.start_with_input = <<-heredoc
+      daemonize no
+      port 600#{i}
+      #{slaveof}
+    heredoc
+  end
+end

data/examples/resque.rb

@@ -0,0 +1,10 @@
+5.times do |i|
+  Cognizant.monitor "resque-worker-#{i}" do |process|
+    process.group         = "resque"
+    process.uid           = "deploy"
+    process.gid           = "deploy"
+    process.chdir         = "/apps/example/current/"
+    process.env           = { "QUEUE" => "*", "RACK_ENV" => "production" }
+    process.start_command = "bundle exec rake resque:work"
+  end
+end

data/lib/cognizant/client/cli.rb

@@ -0,0 +1,9 @@
+module Cognizant
+  module Client
+    class CLI
+      def initialize(command)
+        puts "got #{command}"
+      end
+    end
+  end
+end

data/lib/cognizant/client/interface.rb

@@ -0,0 +1,33 @@
+require "eventmachine"
+
+module Cognizant
+  module Client
+    class Interface
+      def initialize(server = nil)
+        @sock = EventMachine.connect(server, Client::Interface::Handler)
+      end
+
+      def method_missing(*meth, &blk)
+        @sock.queue << blk
+        @sock.send_object(meth)
+      end
+
+      class Handler < EventMachine::Connection
+        # include EventMachine::Protocols::SASLauthclient
+        include EventMachine::Protocols::ObjectProtocol
+
+        attr_reader :queue
+
+        def post_init
+          @queue = []
+        end
+
+        def receive_object(obj)
+          if callback = @queue.shift
+            callback.call(obj)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/cognizant/logging.rb

@@ -0,0 +1,33 @@
+require "logger"
+
+module Cognizant
+  module Logging
+    extend self
+
+    def add_log_adapter(file)
+      @files ||= Array.new
+      @files << file unless @files.include?(file)
+      @logger = nil
+    end
+
+    def log
+      @files ||= Array.new($stdout)
+      @logger ||= Logger.new(Files.new(*@files))
+    end
+    alias :logger :log
+
+    class Files
+      def initialize(*files)
+        @files = files
+      end
+
+      def write(*args)
+        @files.each { |t| t.write(*args) }
+      end
+
+      def close
+        @files.each(&:close)
+      end
+    end
+  end
+end

data/lib/cognizant/process/actions/restart.rb

@@ -0,0 +1,60 @@
+module Cognizant
+  class Process
+    module Actions
+      module Restart
+        # Environment variables for process during restart.
+        # @return [Hash] Defaults to {}
+        attr_accessor :restart_env
+
+        # The command to run before the process is restarted. The exit status
+        # of this command determines whether or not to proceed.
+        # @return [String] Defaults to nil
+        attr_accessor :restart_before_command
+
+        # The command to restart the process with. This command can optionally
+        # be similar in behavior to the stop command, since the process will
+        # anyways be automatically started again, if autostart is set to true.
+        # @return [String] Defaults to nil
+        attr_accessor :restart_command
+
+        # The signals to pass to the process one by one attempting to restart
+        # it. Each signal is passed within the timeout period over equally
+        # distributed intervals (min. 2 seconds). Override with signals without
+        # "KILL" to never force kill the process.
+        # e.g. ["TERM", "INT"]
+        # @return [Array] Defaults to ["TERM", "INT", "KILL"]
+        attr_accessor :restart_signals
+
+        # The grace time period in seconds for the process to stop within
+        # (for restart). Covers the time period for the restart command or
+        # signals. After the timeout is over, the process is checked for
+        # running status and if not stopped, it re-enters the auto start
+        # lifecycle based on conditions.
+        # @return [String] Defaults to 10
+        attr_accessor :restart_timeout
+
+        # The command to run after the process is restarted.
+        # @return [String] Defaults to nil
+        attr_accessor :restart_after_command
+
+        def restart_process
+          result_handler = Proc.new do |result|
+            # If it is a boolean and value is true OR if it's an execution result and it succeeded.
+            if (!!result == result and result) or (result.respond_to?(:succeeded?) and result.succeeded?)
+              unlink_pid unless pid_running?
+            end
+          end
+          execute_action(
+            result_handler,
+            env:     (self.env || {}).merge(self.restart_env || {}),
+            before:  self.restart_before_command,
+            command: self.restart_command,
+            signals: self.restart_signals,
+            after:   self.restart_after_command,
+            timeout: self.restart_timeout
+          )
+        end
+      end
+    end
+  end
+end