check_passenger 0.2 → 1.0

data/README.md

@@ -1,29 +1,118 @@
-# CheckPassenger
+# check_passenger
 
-TODO: Write a gem description
+This gem provides a Nagios check command to monitor running Passenger processes and the memory that they use.
+
+It can report data on a global or per-application basis, and raise warnings and alerts when consumption exceeds given thresholds.
 
-## Installation
 
-Add this line to your application's Gemfile:
+## Installation
 
-    gem 'check_passenger'
+The easiest way to install **check\_passenger** is through RubyGems:
 
-And then execute:
+    # gem install check_passenger
 
-    $ bundle
+Alternatively, the gem can be built from the source code with `gem build`, and manually installed in the machines where it needs to run.
 
-Or install it yourself as:
+Either way, the `check_passenger` command should become available in the path—although it may be necessary to perform an additional action, such as running `rbenv rehash` or similar.
 
-    $ gem install check_passenger
 
 ## Usage
 
-TODO: Write usage instructions here
+**check\_passenger** is intended to be executed in the same machine or machines where Passenger is running. It will call `passenger-status` and gather all data from its output.
+
+Typically, the Nagios service will be running in a separate machine from those being monitored. Remote execution of `check_passenger` is then usually achieved with Nagios Remote Plugin Executor (NRPE), or MK's Remote Plugin Executor (MRPE).
+
+`check_passenger` reads all necessary settings from the command-line when it's run, and does not take configuration from a file. It supports three working modes depending on the aspect being monitored, which are called with an argument as:
+
+    # check_passenger <mode>
+
+Where the `<mode>` argument can be on of the following:
+
+* `processes`: These are the Passenger processes that are currently running, associated to applications.
+* `live_processes`: Of all the running processes, how many are actually being used. See the section [Passenger Live Processes](#passenger-live-processes) below.
+* `memory`: Memory occupied by the Passenger processes that are running.
+
+In addition, **check\_passenger** can be called with the following options:
+
+* `-n, --app-name`: Limit check to application with *APP_NAME*—see the section [Global or Per-Application Reporting](#global-or-per-application-reporting) below.
+* `-C, --cache`: Cache parsed output of `passenger-status`—see the section [Data Caching](#data-caching) below.
+* `-D, --debug`: Let exception raise to the command-line, and keep the output of `passenger-status` in a file for debugging purposes.
+* `-d, --dump`: Keep the output of `passenger-status` in a file for debugging purposes.
+* `-a, --include-all`: Apart from reporting on a global counter, add data for the same counter for each running Passenger application—see the section [Global or Per-Application Reporting](#global-or-per-application-reporting) below.
+* `-p, --passenger-status-path`: Full path to the `passenger-status` command—most of the time not needed.
+
+To raise warnings and alerts, use the `-w, --warn`, and `-c, --crit` options. Ranges can be provided as described in the [Nagios Plugin Development Guidelines](https://nagios-plugins.org/doc/guidelines.html#THRESHOLDFORMAT). Note that memory is measured in megabytes.
+
+Finally, run `check_passenger help [mode]` to get usage information on the command-line.
+
+
+## Global or Per-Application Reporting
+
+For each of the aspects that **check\_passenger** can monitor (processes, live processes, and memory), it can focus on all the applications running with Passenger, or on a specific application. This is controlled with the `-n` (`--app-name`), and `-a` (`--include-all`) options, as seen in the following examples.
+
+The following command returns a counter for all the running Passenger processes in the machine:
+
+    # check_passenger processes
+    Passenger 4.0.59 OK - 46 processes|process_count=46;;;0;50
+
+The next command limits the count to the processes that belong to *APP_NAME*:
+
+    # check_passenger processes --app-name APP_NAME
+    Passenger APP_NAME OK - 20 processes|process_count=20;;;0;
+
+Where *APP_NAME* is the full path, or a unique part of it, to the root directory of the application. If, for example, each application is installed in its own user directory, this path could be something like `/home/USER/Site`, and only the username would be needed to filter the output for the application—but the full path could be provided.
+
+If multiple applications match the *APP_NAME* given, **check\_passenger** reports an `UNKNOWN` status. If no application is found by the search string, it is assumed that the application failed and is not running, so **check\_passenger** raises a critical alert.
+
+Finally, it's possible to obtain a global counter, together with additional counters for each running application, as follows:
+
+    # check_passenger processes --include-all
+    Passenger 4.0.59 OK - 46 processes|process_count=46;;;0;50 /home/APP_NAME_1/Site=20;;;; /home/APP_NAME_2/Site=12;;;; /home/APP_NAME_3/Site=4;;;; /home/APP_NAME_4/Site=10;;;;
+    /home/APP_NAME_1/Site 20 processes
+    /home/APP_NAME_2/Site 12 processes
+    /home/APP_NAME_3/Site 4 processes
+    /home/APP_NAME_4/Site 10 processes
+
+This allows to monitor a resource, together with how much of it is being used by each application. Note though, that when monitoring a particular counter for all the applications in this way, it won't be possible to set alerts—just add an additional check for the alert you want to set for an application or globally.
+
+All these examples work the same with processes, live processes, and memory.
+
+
+## Passenger Live Processes
+
+Passenger reuses running processes in a sort of LIFO manner. This means that when it needs a process to handle a request, and there are running processes not currently busy handling requests, it will preferably take first the one that was run the most recently. This feature is quite handy to know how many processes a particular application, or all running applications, actually ever execute in parallel.
+
+In order to estimate the live process count, **check\_passenger** takes a look at those that have been run in the last 300 seconds (or 5 minutes). This works well as long as **check\_passenger** is executed with a periodicity of 5 minutes or less.
+
+
+## Data Caching
+
+In order to set alerts per global or application counter, **check\_passenger** must be called successive times with different settings. For example, to raise alerts on global memory consumption:
+
+    # check_passenger memory --warn 6000 --crit 8000
+    Passenger 4.0.59 OK - 4864MB memory used|memory=4864;6000;8000;0;
+
+And then again, to raise alerts on the memory consumption of a specific application:
+
+    # check_passenger memory --app-name APP_NAME --warn 3000 --crit 4000
+    Passenger APP_NAME OK - 2123MB memory used|memory=2123;3000;4000;0;
+
+For each call, **check\_passenger** must execute `passenger-status` and parse its output. While the performance penalty should not be high, this can lead to inconsistent data where, for example, the global process count is not equal to the sum of processes for all applications, as it's possible for processes to be started or terminated between calls.
+
+To avoid this inconsistency, and speed things up a bit in the way, **check\_passenger** can cache the parsed output of `passenger-status`. Just provide the `-C`, or `--cache` command-line option.
+
+Cached data is stored in the temporary directory of the system, with a time-to-live of just 5 seconds. That is, cached data will be ignored if it's more than 5 seconds old. Therefore, it's recommended that all calls to **check\_passenger** are made one after another, without inserting other checks in the middle that might take longer to complete.
+
 
 ## Contributing
 
-1. Fork it ( https://github.com/[my-github-username]/check_passenger/fork )
+1. Fork it ( https://github.com/aredondo/check_passenger/fork )
 2. Create your feature branch (`git checkout -b my-new-feature`)
-3. Commit your changes (`git commit -am 'Add some feature'`)
+3. Commit your changes (`git commit -am ‘Add some feature'`)
 4. Push to the branch (`git push origin my-new-feature`)
 5. Create a new Pull Request
+
+
+## License
+
+**check\_passenger** is released under the [MIT License](LICENSE.txt).

data/bin/check_passenger

@@ -19,7 +19,7 @@ class CheckPassengerCLI < Thor
                 banner: 'Also include counter for all running apps'
   class_option :passenger_status_path, aliases: 'p', banner: 'Path to passenger-status command'
 
-  desc 'memory', 'Check Passenger memory'
+  desc 'memory', 'Check memory used by Passenger processes'
   option :warn, banner: 'Memory usage threshold to raise warning status', aliases: 'w'
   option :crit, banner: 'Memory usage threshold to raise critical status', aliases: 'c'
   def memory
@@ -28,7 +28,7 @@ class CheckPassengerCLI < Thor
     end
   end
 
-  desc 'processes', 'Check Passenger processes'
+  desc 'processes', 'Check running Passenger processes'
   option :warn, aliases: 'w', banner: 'Process count threshold to raise warning status'
   option :crit, aliases: 'c', banner: 'Process count threshold to raise critical status'
   def processes
@@ -37,7 +37,7 @@ class CheckPassengerCLI < Thor
     end
   end
 
-  desc 'live_processes', 'Check Passenger live processes'
+  desc 'live_processes', 'Check live Passenger processes'
   option :warn, aliases: 'w', banner: 'Live process count threshold to raise warning status'
   option :crit, aliases: 'c', banner: 'Live process count threshold to raise critical status'
   def live_processes
@@ -98,4 +98,15 @@ class CheckPassengerCLI < Thor
   end
 end
 
+if ARGV.empty? or ARGV.first.downcase == 'help'
+  puts <<BANNER
+check_passenger #{CheckPassenger::VERSION}, Copyright 2014-#{Time.now.year} MIT License
+
+check_passenger is a Nagios check command to monitor running Passenger processes
+and the memory that they use. It can report data on a global or per-application
+basis, and raise warnings and alerts when consumption exceeds given thresholds.
+
+BANNER
+end
+
 CheckPassengerCLI.start(ARGV)

data/check_passenger.gemspec

@@ -12,7 +12,7 @@ Gem::Specification.new do |spec|
   spec.email         = ['alvaro@redondo.name']
   spec.summary       = %q{Nagios check to monitor Passenger processes and memory}
   # spec.description   = %q{TODO: Write a longer description. Optional.}
-  spec.homepage      = ''
+  spec.homepage      = 'https://github.com/aredondo/check_passenger'
   spec.license       = 'MIT'
 
   spec.files         = `git ls-files -z`.split("\x0")

data/lib/check_passenger/check.rb

@@ -8,9 +8,9 @@ module CheckPassenger
       attr_reader :parsed_data
 
       COUNTER_LABELS = {
-        live_process_count: '%d live processes',
+        live_process_count: ['%d live process', '%d live processes'],
         memory: '%dMB memory used',
-        process_count: '%d processes'
+        process_count: ['%d process', '%d processes']
       }
 
       def check_counter(counter_name, options = {})
@@ -25,7 +25,7 @@ module CheckPassenger
                 [
                   options[:app_name] || parsed_data.passenger_version,
                   output_status.to_s.upcase,
-                  COUNTER_LABELS[counter_name.to_sym] % counter
+                  counter_with_label(counter, counter_name)
                 ],
           counter: counter_name.to_s, value: counter,
           warn: options[:warn], crit: options[:crit],
@@ -40,13 +40,17 @@ module CheckPassenger
           parsed_data.application_names.each do |app_name|
             counter = parsed_data.send(counter_name.to_sym, app_name)
             output_data << {
-              text: '%s %s' % [app_name, COUNTER_LABELS[counter_name.to_sym] % counter],
+              text: '%s %s' % [app_name, counter_with_label(counter, counter_name)],
               counter: app_name, value: counter
             }
           end
         end
 
         return [output_status, output_data]
+
+      rescue NoApplicationError => e
+        status = :crit
+        return [status, 'Passenger %s %s - %s' % [e.name, status.to_s.upcase, e.to_s]]
       end
 
       def method_missing(method, *args)
@@ -64,6 +68,22 @@ module CheckPassenger
 
       private
 
+      def counter_with_label(counter, counter_type)
+        counter_type = counter_type.to_sym
+
+        unless COUNTER_LABELS.keys.include?(counter_type)
+          raise ArgumentError, 'Unknown counter type: %s' % counter_type.to_s
+        end
+
+        label = if COUNTER_LABELS[counter_type].is_a?(Array)
+          counter == 1 ? COUNTER_LABELS[counter_type].first : COUNTER_LABELS[counter_type].last
+        else
+          COUNTER_LABELS[counter_type]
+        end
+
+        label % counter
+      end
+
       def load_parsed_data(options)
         @parsed_data = options[:parsed_data]
 

data/lib/check_passenger/multiple_applications_error.rb

@@ -0,0 +1,4 @@
+module CheckPassenger
+  class MultipleApplicationsError < NameError
+  end
+end

data/lib/check_passenger/nagios_check.rb

@@ -9,33 +9,49 @@ module CheckPassenger
       exit 3
     end
 
-    def nagios_output(status, data)
-      unless [:ok, :warn, :crit].include?(status)
-        raise ArgumentError, 'Invalid status provided: %s' % status.to_s
-      end
-
+    def nagios_format_output(data)
       data = [data] unless data.is_a?(Array)
       main_status = nil
       status_data = []
       perf_data = []
 
       data.each do |line|
-        raise ArgumentError, 'No status text provided' unless line.has_key?(:text)
+        case line
+        when String
+          status_text = line
+        when Hash
+          status_text = line[:text]
+          perf_data << '%s=%d;%s;%s;%s;%s' % [
+            line[:counter], line[:value],
+            line[:warn], line[:crit],
+            line[:min], line[:max]
+          ]
+        else
+          raise ArgumentError
+        end
 
         if main_status.nil?
-          main_status = line[:text]
+          main_status = status_text
         else
-          status_data << line[:text]
+          status_data << status_text
         end
+      end
 
-        perf_data << '%s=%d;%s;%s;%s;%s' % [
-          line[:counter], line[:value],
-          line[:warn], line[:crit],
-          line[:min], line[:max]
-        ]
+      [main_status, status_data, perf_data]
+    end
+
+    def nagios_output(status, data)
+      unless [:ok, :warn, :crit].include?(status)
+        raise ArgumentError, 'Invalid status provided: %s' % status.to_s
       end
 
-      puts '%s|%s' % [main_status, perf_data.join(' ')]
+      main_status, status_data, perf_data = nagios_format_output(data)
+
+      if perf_data.is_a?(Array) and perf_data.any?
+        puts '%s|%s' % [main_status, perf_data.join(' ')]
+      else
+        puts main_status
+      end
       status_data.each { |status_datum| puts status_datum }
 
       exit EXIT_CODES[status]

data/lib/check_passenger/no_application_error.rb

@@ -0,0 +1,4 @@
+module CheckPassenger
+  class NoApplicationError < NameError
+  end
+end

data/lib/check_passenger/parser.rb

@@ -46,9 +46,9 @@ module CheckPassenger
       if app_name
         data = @application_data.select { |d| d[:name].include?(app_name) }
         if data.size == 0
-          raise ArgumentError, 'Could not find an application by "%s"' % app_name
+          raise NoApplicationError.new('Could not find an application by "%s"' % app_name, app_name)
         elsif data.size > 1
-          raise ArgumentError, 'More than one application match "%s"' % app_name
+          raise MultipleApplicationsError.new('More than one application match "%s"' % app_name, app_name)
         else
           return data.first
         end

data/lib/check_passenger/version.rb

@@ -1,3 +1,3 @@
 module CheckPassenger
-  VERSION = "0.2"
+  VERSION = '1.0'
 end

data/lib/check_passenger.rb

@@ -3,6 +3,8 @@
   check
   parser
   passenger_status
+  multiple_applications_error
+  no_application_error
   status_output_error
   version
 }.each { |lib| require 'check_passenger/' + lib }

data/test/sample_output_3.txt

@@ -0,0 +1,32 @@
+Version : 4.0.59
+Date    : 2015-05-30 01:53:14 +0200
+Instance: 1965
+----------- General information -----------
+Max pool size : 50
+Processes     : 6
+Requests in top-level queue : 0
+
+----------- Application groups -----------
+/home/application_1/Site#default:
+  App root: /home/application_1/Site
+  Requests in queue: 0
+  * PID: 14518   Sessions: 0       Processed: 11723   Uptime: 20h 8m 7s
+    CPU: 0%      Memory  : 144M    Last used: 1m 33s ag
+
+/home/application_2/Site#default:
+  App root: /home/application_2/Site
+  Requests in queue: 0
+  * PID: 14134   Sessions: 0       Processed: 2313    Uptime: 20h 8m 10s
+    CPU: 0%      Memory  : 63M     Last used: 6h 22m 4
+
+/home/application_3/Site#default:
+  App root: /home/application_3/Site
+  Requests in queue: 0
+  * PID: 21058   Sessions: 0       Processed: 725     Uptime: 2d 22h 35m 38s
+    CPU: 0%      Memory  : 30M     Last used: 5m 4
+  * PID: 21071   Sessions: 0       Processed: 0       Uptime: 2d 22h 35m 38s
+    CPU: 0%      Memory  : 15M     Last used: 2d 2
+  * PID: 21078   Sessions: 0       Processed: 0       Uptime: 2d 22h 35m 38s
+    CPU: 0%      Memory  : 15M     Last used: 2d 2
+  * PID: 21085   Sessions: 0       Processed: 0       Uptime: 2d 22h 35m 38s
+    CPU: 0%      Memory  : 15M     Last used: 2d 2

data/test/test_check.rb

@@ -119,4 +119,44 @@ describe CheckPassenger::Check do
       end
     end
   end
+
+  describe 'sample output 3' do
+    before do
+      sample_path = File.expand_path('sample_output_3.txt', File.dirname(__FILE__))
+      data = File.read(sample_path)
+      @parsed_data = CheckPassenger::Parser.new(data)
+    end
+
+    it 'correctly uses singular/plural when reporting counts' do
+      options = { parsed_data: @parsed_data }
+      output_status, output_data = CheckPassenger::Check.process_count(options)
+      assert output_data.first[:text] =~ /\b6 processes\b/, output_data.first[:text]
+      output_status, output_data = CheckPassenger::Check.live_process_count(options)
+      assert output_data.first[:text] =~ /\b1 live process\b/, output_data.first[:text]
+
+      options = { parsed_data: @parsed_data, app_name: 'application_1' }
+      output_status, output_data = CheckPassenger::Check.process_count(options)
+      assert output_data.first[:text] =~ /\b1 process\b/, output_data.first[:text]
+      output_status, output_data = CheckPassenger::Check.live_process_count(options)
+      assert output_data.first[:text] =~ /\b1 live process\b/, output_data.first[:text]
+
+      options = { parsed_data: @parsed_data, app_name: 'application_2' }
+      output_status, output_data = CheckPassenger::Check.process_count(options)
+      assert output_data.first[:text] =~ /\b1 process\b/, output_data.first[:text]
+      output_status, output_data = CheckPassenger::Check.live_process_count(options)
+      assert output_data.first[:text] =~ /\b0 live processes\b/, output_data.first[:text]
+
+      options = { parsed_data: @parsed_data, app_name: 'application_3' }
+      output_status, output_data = CheckPassenger::Check.process_count(options)
+      assert output_data.first[:text] =~ /\b4 processes\b/, output_data.first[:text]
+      output_status, output_data = CheckPassenger::Check.live_process_count(options)
+      assert output_data.first[:text] =~ /\b0 live processes\b/, output_data.first[:text]
+    end
+
+    it 'raises an alert if the application is not running' do
+      options = { parsed_data: @parsed_data, app_name: 'application_4' }
+      output_status, output_data = CheckPassenger::Check.process_count(options)
+      assert_equal :crit, output_status, output_data.inspect
+    end
+  end
 end

data/test/test_parser.rb

@@ -109,7 +109,7 @@ describe CheckPassenger::Parser do
       end
 
       it 'raises exception if term matches multiple apps' do
-        assert_raises ArgumentError do
+        assert_raises CheckPassenger::MultipleApplicationsError do
           @parser.memory('application')
         end
       end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: check_passenger
 version: !ruby/object:Gem::Version
-  version: '0.2'
+  version: '1.0'
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-09-14 00:00:00.000000000 Z
+date: 2015-05-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -104,12 +104,13 @@ files:
 - LICENSE.txt
 - README.md
 - Rakefile
-- TODO.md
 - bin/check_passenger
 - check_passenger.gemspec
 - lib/check_passenger.rb
 - lib/check_passenger/check.rb
+- lib/check_passenger/multiple_applications_error.rb
 - lib/check_passenger/nagios_check.rb
+- lib/check_passenger/no_application_error.rb
 - lib/check_passenger/parser.rb
 - lib/check_passenger/passenger_status.rb
 - lib/check_passenger/status_output_error.rb
@@ -117,12 +118,13 @@ files:
 - test/passenger-status
 - test/sample_output_1.txt
 - test/sample_output_2.txt
+- test/sample_output_3.txt
 - test/test_check.rb
 - test/test_helper.rb
 - test/test_nagios_check.rb
 - test/test_parser.rb
 - test/test_passenger_status.rb
-homepage: ''
+homepage: https://github.com/aredondo/check_passenger
 licenses:
 - MIT
 post_install_message: 
@@ -135,12 +137,18 @@ required_ruby_version: !ruby/object:Gem::Requirement
   - - ! '>='
     - !ruby/object:Gem::Version
       version: '0'
+      segments:
+      - 0
+      hash: 2306355991957231543
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
   - - ! '>='
     - !ruby/object:Gem::Version
       version: '0'
+      segments:
+      - 0
+      hash: 2306355991957231543
 requirements: []
 rubyforge_project: 
 rubygems_version: 1.8.29
@@ -151,6 +159,7 @@ test_files:
 - test/passenger-status
 - test/sample_output_1.txt
 - test/sample_output_2.txt
+- test/sample_output_3.txt
 - test/test_check.rb
 - test/test_helper.rb
 - test/test_nagios_check.rb

data/TODO.md

@@ -1,31 +0,0 @@
-# Release
-
-- README page.
-- Add summary to command help.
-
-
-# Fix
-
-- Handle error:
-
-```
-It appears that multiple Passenger instances are running. Please select a
-specific one by running:
-
-  passenger-status <PID>
-
-The following Passenger instances are running:
-  PID: 1394
-  PID: 1413
-```
-
-- "1 live processes" should be "1 live process"
-
-
-# Other
-
-- Option `all` to monitor all counters for all applications and globally,
-  without possibility to raise alerts.
-- PerfDatum class.
-- Option to set TTL used to estimate live processes.
-- Option to set TTL of cached data.