ostrichpoll 0.0.1

data/.gitignore

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

data/.rvmrc

@@ -0,0 +1,81 @@
+#!/usr/bin/env bash
+
+# This is an RVM Project .rvmrc file, used to automatically load the ruby
+# development environment upon cd'ing into the directory
+
+# First we specify our desired <ruby>[@<gemset>], the @gemset name is optional.
+environment_id="ruby-1.9.2-p290"
+
+#
+# Uncomment the following lines if you want to verify rvm version per project
+#
+# rvmrc_rvm_version="1.10.1" # 1.10.1 seams as a safe start
+# eval "$(echo ${rvm_version}.${rvmrc_rvm_version} | awk -F. '{print "[[ "$1*65536+$2*256+$3" -ge "$4*65536+$5*256+$6" ]]"}' )" || {
+#   echo "This .rvmrc file requires at least RVM ${rvmrc_rvm_version}, aborting loading."
+#   return 1
+# }
+#
+
+#
+# Uncomment following line if you want options to be set only for given project.
+#
+# PROJECT_JRUBY_OPTS=( --1.9 )
+#
+# The variable PROJECT_JRUBY_OPTS requires the following to be run in shell:
+#
+#    chmod +x ${rvm_path}/hooks/after_use_jruby_opts
+#
+
+#
+# First we attempt to load the desired environment directly from the environment
+# file. This is very fast and efficient compared to running through the entire
+# CLI and selector. If you want feedback on which environment was used then
+# insert the word 'use' after --create as this triggers verbose mode.
+#
+if [[ -d "${rvm_path:-$HOME/.rvm}/environments" \
+  && -s "${rvm_path:-$HOME/.rvm}/environments/$environment_id" ]]
+then
+  \. "${rvm_path:-$HOME/.rvm}/environments/$environment_id"
+
+  if [[ -s "${rvm_path:-$HOME/.rvm}/hooks/after_use" ]]
+  then
+    . "${rvm_path:-$HOME/.rvm}/hooks/after_use"
+  fi
+else
+  # If the environment file has not yet been created, use the RVM CLI to select.
+  if ! rvm --create  "$environment_id"
+  then
+    echo "Failed to create RVM environment '${environment_id}'."
+    return 1
+  fi
+fi
+
+#
+# If you use an RVM gemset file to install a list of gems (*.gems), you can have
+# it be automatically loaded. Uncomment the following and adjust the filename if
+# necessary.
+#
+# filename=".gems"
+# if [[ -s "$filename" ]]
+# then
+#   rvm gemset import "$filename" | grep -v already | grep -v listed | grep -v complete | sed '/^$/d'
+# fi
+
+# If you use bundler, this might be useful to you:
+# if [[ -s Gemfile ]] && ! command -v bundle >/dev/null
+# then
+#   printf "%b" "The rubygem 'bundler' is not installed. Installing it now.\n"
+#   gem install bundler
+# fi
+# if [[ -s Gemfile ]] && command -v bundle
+# then
+#   bundle install
+# fi
+
+if [[ $- == *i* ]] # check for interactive shells
+then
+    echo "Using: $(tput setaf 2)$GEM_HOME$(tput sgr0)" # show the user the ruby and gemset they are using in green
+else 
+	echo "Using: $GEM_HOME" # don't use colors in interactive shells
+fi
+

data/Gemfile

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

data/LICENSE.md

@@ -0,0 +1,14 @@
+
+Copyright 2012, Tumblr Inc.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

data/README.md

@@ -0,0 +1,85 @@
+# Ostrichpoll
+
+Ostrichpoll is a tiny utility for monitoring Twitter Ostrich services.
+Effectively it can monitor any service which exposes internal metrics in JSON
+over HTTP.
+
+Features:
+
+* not a daemon: Ostrichpoll is intended to be run by `monit` or similar tool on a regular basis.
+* validate multiple endpoints in a single execution
+* specify normal ranges for metrics and gauges through YAML configuration
+* support for "rate" measurements, specifying acceptable change per second for
+  a metric. (useful for counters and other monotonic metrics)
+
+
+## Installation
+
+    $ gem install ostrichpoll
+
+## Execution
+
+Ostrichpoll may be executed with a simple `ostrichpoll` which will ensure a 200 response
+is given from `127.0.0.1:9900/stats.json`.
+
+You may change the endpoint:
+
+    ostrichpoll -u devbox:9999/stats.json
+
+The interesting part of Ostrichpoll is when you give a configuration file
+that specifies normal ranges for individual metrics:
+
+    ostrichpoll -c pollconfig.yml
+
+Use `-d` to enable extra logging for debugging.
+
+## Configuration
+
+Configuration is specified in the format:
+
+    ---
+    - url: 127.0.0.1:9900/stats.txt?period=10
+      rate_file: /tmp/parmesan-http-ostrich-rate.yml
+      validations:
+        counters/KafkaEventSink_messageDropped:
+          rate: true
+          normal_range: [0, 5]
+          missing: ignore
+          exit_code: 2
+        metrics/KafkaEventSink_append_msec/p99:
+          normal_range: [0, 10]
+          missing: error
+          exit_code: 3
+    - url: 127.0.0.1:9901/stats.txt
+    ...
+
+### Options
+
+* `url` - an endpoint which exposes JSON stats. If this endpoint is not available, Ostrichpoll will exit with `-1` (really `255`).
+* `rate_file` - where to store rate measurements between executions of Ostrichpoll.
+* `validations` - a list of validations to execute with the following options:
+    * the key is the name of the metric. Nested metrics are supported through the `/` notation.
+    * `rate` when set to true, compute the change per second since this value was last seen. You must specify a `rate_file` for this to work. Obviously, on the first execution of Ostrichpoll this validation will be ignored.
+    * `normal_range` an array specifying the minimum and maximum (inclusive) values which are acceptable for this metric
+    * `missing` behavior if the metric is not seen in the output at all. (error by default)
+    * `exit_code` what value Ostrichpoll should exit with if this error is seen.
+    
+### Notes
+Ostrichpoll is setup to execute all validations on each execution, even if one of the early validations fails, the output from all validations is logged to stderr. However, the exit code is the exit code from the first erroring validation.
+
+
+## License
+
+Copyright 2012, Tumblr Inc.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

data/Rakefile

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

data/bin/ostrichpoll

@@ -0,0 +1,4 @@
+#!/usr/bin/env ruby
+$LOAD_PATH.unshift File.join(File.dirname(__FILE__), '..', 'lib')
+
+require 'ostrichpoll'

data/lib/ostrichpoll/config_parser.rb

@@ -0,0 +1,74 @@
+require 'ostrichpoll/ostrich_validator'
+
+module OstrichPoll
+  # traverses a nested hashmap (the parsed config YAML)
+  # returning a set of hosts and validators
+  class ConfigParser
+    def self.parse(map)
+      hosts = []
+
+      map.each do |host_config|
+        host = Host.new
+        host_config.each do |key,value|
+          case key
+            when 'url'
+              host.url = value
+
+            when 'rate_file'
+              host.rate_file = value
+
+            when 'validations'
+              validations = parse_validations(value)
+
+              validations.each do |v|
+                v.host_instance = host
+              end
+
+              host.validations = validations
+
+            else
+              Log.warn "Unknown key: #{key}. Ignoring."
+          end
+        end
+        hosts << host
+      end
+
+      hosts
+    end
+
+    def self.parse_validations(validations)
+      return [] unless validations
+
+      validations.map do |name, v|
+        self.parse_validation name, v
+      end
+    end
+
+    def self.parse_validation(name, map)
+      validator = Validator.new
+      validator.metric = name
+      map.each do |key,value|
+        case key
+          when 'rate'
+            validator.rate = value
+
+          when 'normal_range'
+            # FIXME validate normal range (min <= max, etc.)
+            validator.normal_range = value
+
+          when 'missing'
+            validator.missing = value.to_sym
+
+          when 'exit_code'
+            validator.exit_code = value
+
+          else
+            Log.warn "Unknown key for validation: #{key}. Ignoring."
+        end
+      end
+
+      validator.verify!
+      validator
+    end
+  end
+end

data/lib/ostrichpoll/exit_codes.rb

@@ -0,0 +1,8 @@
+module OstrichPoll
+  # generics
+  EXIT_OK = 0
+  EXIT_ERROR = -1
+
+  # could not connect to http endpoint
+  EXIT_NOHTTP = 1
+end

data/lib/ostrichpoll/ostrich_validator.rb

@@ -0,0 +1,175 @@
+#
+# implements the actual validators
+#
+
+require 'json'
+require 'yaml'
+require 'net/http'
+
+module OstrichPoll
+  class Host
+    attr_accessor :url
+    attr_accessor :rate_file
+    attr_accessor :validations
+
+
+    def initialize
+      validations = []
+    end
+
+    attr_accessor :stored_values
+    attr_accessor :stored_timestamp
+
+    def validate
+      uri = URI.parse url
+      response = Net::HTTP.get uri
+
+      # parse response
+      json = JSON.parse(response) rescue (
+        Log.error "Invalid JSON response: #{response}"
+        return EXIT_ERROR
+      )
+
+      @stored_values = {}
+      if rate_file
+        # read in rate-file
+        @stored_values = YAML.load_file(rate_file) rescue (
+          Log.warn "Could not parse rate file: #{rate_file}"
+          {}
+        )
+
+        @stored_timestamp = stored_values['ostrichpoll.timestamp']
+        unless @stored_timestamp
+          Log.warn "No 'ostrichpoll.timestamp' found in rate file: #{rate_file}"
+        end
+
+        # write out new rate file
+        json['ostrichpoll.timestamp'] = Time.now.to_i
+        File.open(rate_file, 'w') do |f|
+          f.puts json.to_yaml
+        end
+      end
+
+      # execute each validations:
+      retval = false
+      if validations
+        validations.each do |v|
+          value = v.check(find_value(json, v.metric))
+          retval = value unless retval
+        end
+      end
+
+      retval
+    end
+
+    def previous_reading(key)
+      return stored_timestamp, find_value(stored_values, key)
+    end
+
+    def find_value(map, key)
+      tree = map
+      key.split('/').each do |selector|
+        return nil unless tree.kind_of? Hash
+        tree = tree[selector]
+      end
+
+      tree
+    end
+  end
+
+  # this is a pretty weak and limiting definition of a validator,
+  # but it's quick to develop and clear how to extend
+  class Validator
+    attr_accessor :host_instance
+
+    attr_accessor :metric
+    attr_accessor :rate
+    attr_accessor :normal_range
+    attr_accessor :missing
+    attr_accessor :exit_code
+
+    def init
+      @rate = false
+      @exit_code = 1
+      @missing = :ignore
+    end
+
+    def verify!
+      Log.warn "Invalid metric #{metric.inspect}" unless metric.is_a? String
+      Log.warn "Invalid exit code: #{exit_code.inspect}" unless exit_code.is_a? Integer
+
+      if normal_range
+        Log.warn "Invalid normal range: #{normal_range.inspect}" unless normal_range.is_a? Array
+      end
+    end
+
+    def check (value)
+      Log.debug "#{host_instance.url} | Given: #{metric}=#{value}"
+
+      # error on missing value unless we ignore missing
+      unless value
+        unless missing == :ignore
+          Log.warn "#{metric}: value missing, treating as error; exit code #{exit_code}"
+          return exit_code
+        else
+          Log.debug "#{host_instance.url} |   missing value, but set to ignore"
+          # not an error, but you can't check anything else
+          return false
+        end
+      end
+
+      # compute rate
+      if rate
+        timestamp, previous = host_instance.previous_reading(metric)
+
+        if previous
+          Log.debug "#{host_instance.url} |   last seen: #{previous} @ #{timestamp}"
+
+          # change since last measure
+          value -= previous
+
+          # divide by seconds elapsed
+          value /= Time.now.to_i - timestamp
+
+          Log.debug "#{host_instance.url} |   computed rate: #{value}"
+
+        else
+          # let it pass
+          Log.info "#{metric}: no previous reading for rate"
+          return false
+        end
+      end
+
+      # ensure value is within normal range
+      if normal_range
+        Log.debug "#{host_instance.url} |   normal range: #{normal_range.inspect}"
+        case normal_range.size
+          when 1 # max
+            hi = normal_range.first
+
+          when 2 # min
+            lo = normal_range.first
+            hi = normal_range.last
+
+          else
+            # whatever, ignore
+            # the yaml deserializer shouldn't let this happen
+        end
+
+        if lo && value < lo
+          Log.warn "#{metric}: read value #{value} is below normal range minimum #{lo}; exit code #{exit_code}"
+          return exit_code
+        end
+
+        if hi && value > hi
+          Log.warn "#{metric}: read value #{value} is above normal range maximum #{hi}; exit code #{exit_code}"
+          return exit_code
+        end
+
+        Log.debug "#{host_instance.url} |   within normal range"
+      end
+
+      false
+    end
+  end
+end

data/lib/ostrichpoll/string.rb

@@ -0,0 +1,6 @@
+class String
+  def strip_heredoc
+    indent = scan(/^[ \t]*(?=\S)/).min.size || 0
+    gsub(/^[ \t]{#{indent}}/, '')
+  end
+end

data/lib/ostrichpoll/version.rb

@@ -0,0 +1,3 @@
+module OstrichPoll
+  VERSION = "0.0.1"
+end

data/lib/ostrichpoll.rb

@@ -0,0 +1,77 @@
+require 'yaml'
+require 'trollop'
+require 'pp'
+require 'net/http'
+require 'logger'
+
+require 'ostrichpoll/string'
+require 'ostrichpoll/version'
+require 'ostrichpoll/exit_codes'
+require 'ostrichpoll/config_parser'
+
+module OstrichPoll
+  Log = Logger.new(STDERR)
+
+  @opts = Trollop::options do
+    version = "ostrichpoll #{VERSION}"
+    banner_text = <<-EOS
+      A ruby utility for monitoring JSON endpoints (Twitter Ostrich, specifically)
+      for normal ranges of values.
+    EOS
+    banner(banner_text.strip_heredoc)
+
+    opt :configfile, "YAML configuration",
+        type: :string
+
+    opt :url, "url",
+        type: :string,
+        default: 'http://127.0.0.1:9900/stats.json'
+
+    opt :debug, "debug",
+        :default => false
+  end
+
+  if @opts[:configfile] and not File.readable_real?(@opts[:configfile])
+    Trollop::die "configuration file #{@opts[:configfile]} cannot be read"
+  end
+
+  if @opts[:debug]
+    Log.level = Logger::DEBUG
+  else
+    Log.level = Logger::WARN
+  end
+
+  # TODO rewrite the basic check in terms of a hard-coded validator, much cleaner
+  # check that the host+port respond to http
+  if @opts[:configfile]
+    yaml = YAML.load_file @opts[:configfile]
+    hosts = ConfigParser.parse(yaml)
+
+    retval = false
+    hosts.each do |h|
+      retval = h.validate unless retval
+    end
+
+    # use the exitcode, unless none is given
+    exit retval if retval
+
+  else
+    # if we don't have a config file, simply check that the host and port respond to http
+    begin
+      uri = URI.parse @opts[:url]
+      @response = Net::HTTP.get uri
+    rescue Exception => e
+      Log.warn e
+      exit EXIT_NOHTTP
+    end
+  end
+
+rescue SystemExit => e
+  exit e.status
+
+rescue Exception => e
+  Log.error e
+  exit EXIT_ERROR # exit with error
+end
+
+exit OstrichPoll::EXIT_OK

data/ostrichPoll.gemspec

@@ -0,0 +1,20 @@
+# -*- encoding: utf-8 -*-
+require File.expand_path('../lib/ostrichPoll/version', __FILE__)
+
+Gem::Specification.new do |gem|
+  gem.authors       = ["Wiktor Macura"]
+  gem.email         = ["wiktor@tumblr.com"]
+  gem.description   = %q{Ostrichpoll is a tiny utility for monitoring Twitter Ostrich services. Effectively it can monitor any service which exposes internal metrics in JSON over HTTP.}
+  gem.summary       = %q{Ostrichpoll is a tiny utility for monitoring Twitter Ostrich services.}
+  gem.homepage      = "http://github.com/tumblr/ostrichpoll"
+
+  gem.files         = `git ls-files`.split($\)
+  gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
+  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
+  gem.name          = "ostrichpoll"
+  gem.require_paths = ["lib"]
+  gem.version       = OstrichPoll::VERSION
+
+  gem.add_development_dependency 'json'
+  gem.add_development_dependency 'trollop'
+end

metadata

@@ -0,0 +1,85 @@
+--- !ruby/object:Gem::Specification
+name: ostrichpoll
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+  prerelease: 
+platform: ruby
+authors:
+- Wiktor Macura
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-05-08 00:00:00.000000000Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: json
+  requirement: &70093421674620 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: *70093421674620
+- !ruby/object:Gem::Dependency
+  name: trollop
+  requirement: &70093413683700 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: *70093413683700
+description: Ostrichpoll is a tiny utility for monitoring Twitter Ostrich services.
+  Effectively it can monitor any service which exposes internal metrics in JSON over
+  HTTP.
+email:
+- wiktor@tumblr.com
+executables:
+- ostrichpoll
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- .rvmrc
+- Gemfile
+- LICENSE.md
+- README.md
+- Rakefile
+- bin/ostrichpoll
+- exampleconfigs/firehose.yml
+- lib/ostrichpoll.rb
+- lib/ostrichpoll/config_parser.rb
+- lib/ostrichpoll/exit_codes.rb
+- lib/ostrichpoll/ostrich_validator.rb
+- lib/ostrichpoll/string.rb
+- lib/ostrichpoll/version.rb
+- ostrichPoll.gemspec
+homepage: http://github.com/tumblr/ostrichpoll
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.10
+signing_key: 
+specification_version: 3
+summary: Ostrichpoll is a tiny utility for monitoring Twitter Ostrich services.
+test_files: []