pulse-meter 0.0.1

data/examples/readme_client_example.rb

@@ -0,0 +1,52 @@
+$: << File.join(File.absolute_path(__FILE__), '..', 'lib')
+
+require 'pulse-meter'
+PulseMeter.redis = Redis.new
+
+# static sensor examples
+
+counter = PulseMeter::Sensor::Counter.new :my_counter
+counter.event(1)
+counter.event(2)
+puts counter.value
+
+indicator = PulseMeter::Sensor::Indicator.new :my_value
+indicator.event(3.14)
+indicator.event(2.71)
+puts indicator.value
+
+hashed_counter = PulseMeter::Sensor::HashedCounter.new :my_h_counter
+hashed_counter.event(:x => 1)
+hashed_counter.event(:y => 5)
+hashed_counter.event(:y => 1)
+p hashed_counter.value
+
+
+# timeline sensor examples
+
+requests_per_minute = PulseMeter::Sensor::Timelined::Counter.new(:my_t_counter,
+  :interval => 60,         # count for each minute
+  :ttl => 24 * 60 * 60     # keep data one day
+)
+requests_per_minute.event(1)
+requests_per_minute.event(1)
+sleep(60)
+requests_per_minute.event(1)
+requests_per_minute.timeline(2 * 60).each do |v|
+  puts "#{v.start_time}: #{v.value}"
+end
+
+max_per_minute = PulseMeter::Sensor::Timelined::Max.new(:my_t_max,
+  :interval => 60,         # max for each minute
+  :ttl => 24 * 60 * 60     # keep data one day
+)
+max_per_minute.event(3)
+max_per_minute.event(1)
+max_per_minute.event(2)
+sleep(60)
+max_per_minute.event(5)
+max_per_minute.event(7)
+max_per_minute.event(6)
+max_per_minute.timeline(2 * 60).each do |v|
+  puts "#{v.start_time}: #{v.value}"
+end

data/lib/cmd.rb

@@ -0,0 +1,150 @@
+require 'thor'
+require 'terminal-table'
+require 'time'
+require 'json'
+
+module Cmd
+  class All < Thor
+    include PulseMeter::Mixins::Utils
+    no_tasks do
+      def with_redis
+        PulseMeter.redis = Redis.new :host => options[:host], :port => options[:port], :db => options[:db]
+        yield
+      end
+
+      def with_safe_restore_of(name, &block)
+        with_redis do
+          sensor = PulseMeter::Sensor::Base.restore(name)
+          block.call(sensor)
+        end
+      rescue PulseMeter::RestoreError
+        fail! "Sensor #{name} is unknown or cannot be restored"
+      end
+
+      def all_sensors
+        PulseMeter::Sensor::Timeline.list_objects
+      end
+
+      def all_sensors_table(title = nil)
+        table = Terminal::Table.new :title => title
+        table << ["Name", "Class", "ttl", "raw data ttl", "interval", "reduce delay"]
+        table << :separator
+        all_sensors.each do |s|
+          if s.kind_of? PulseMeter::Sensor::Timeline
+            table << [s.name, s.class, s.ttl, s.raw_data_ttl, s.interval, s.reduce_delay]
+          else
+            table << [s.name, s.class] + ['-'] * 4
+          end
+        end
+        table
+      end
+
+      def fail!(description = nil)
+        puts description if description
+        exit 1
+      end
+
+      def self.common_options
+        method_option :host, :default => '127.0.0.1', :desc => "Redis host"
+        method_option :port, :default => 6379, :desc => "Redis port"
+        method_option :db, :default => 0, :desc => "Redis db"
+      end
+    end
+
+    desc "sensors", "List all sensors available"
+    common_options
+    def sensors
+      with_redis {puts all_sensors_table('Registered sensors')}
+    end
+
+    desc "reduce", "Execute reduction for all sensors' raw data"
+    common_options
+    def reduce
+      with_redis do
+        puts all_sensors_table('Registered sensors to be reduced')
+        PulseMeter::Sensor::Timeline.reduce_all_raw
+        puts "DONE"
+      end
+    end
+
+    desc "event NAME VALUE", "Send event VALUE to sensor NAME"
+    common_options
+    method_option :format, :default => :plain, :desc => "Event format: plain or json"
+    def event(name, value)
+      if "json" == options[:format]
+        value = JSON.parse(value)
+      end
+      with_safe_restore_of(name) {|sensor| sensor.event(value)}
+    end
+
+    desc "timeline NAME SECONDS", "Get sensor's NAME timeline for last SECONDS"
+    common_options
+    def timeline(name, seconds)
+      with_safe_restore_of(name) do |sensor|
+        table = Terminal::Table.new
+        sensor.timeline(seconds).each {|data| table << [data.start_time, data.value || '-']}
+        puts table
+      end
+    end
+
+    desc "timeline_within NAME FROM TILL", "Get sensor's NAME timeline in interval. Time format: YYYY-MM-DD HH:MM:SS"
+    common_options
+    def timeline_within(name, from, till)
+      with_safe_restore_of(name) do |sensor|
+        table = Terminal::Table.new
+        sensor.timeline_within(
+          Time.parse(from),
+          Time.parse(till)
+        ).each {|data| table << [data.start_time, data.value || '-']}
+        puts table
+      end
+    end
+
+    desc "delete NAME", "Delete sensor by name"
+    common_options
+    def delete(name)
+      with_safe_restore_of(name) {|sensor| sensor.cleanup}
+      puts "Sensor #{name} deleted"
+    end
+
+    desc "create NAME TYPE", "Create sensor of given type"
+    common_options
+    method_option :interval, :required => true, :type => :numeric, :desc => "Rotation interval"
+    method_option :ttl, :required => true, :type => :numeric, :desc => "How long summarized data will be stored"
+    method_option :raw_data_ttl, :type => :numeric, :desc => "How long unsummarized raw data will be stored"
+    method_option :reduce_delay, :type => :numeric, :desc => "Delay between end of interval and summarization"
+    method_option :annotation, :type => :string, :desc => "Sensor annotation"
+    def create(name, type)
+      with_redis do
+        klass = constantize("PulseMeter::Sensor::Timelined::#{type}")
+        puts "PulseMeter::Sensor::Timelined::#{type}"
+        fail! "Unknown sensor type #{type}" unless klass
+        sensor = klass.new(name, options.dup)
+        puts "Sensor created"
+        puts all_sensors_table
+      end
+    end
+
+    desc "create_simple NAME TYPE", "Create simple non-timelined sensor of given type"
+    common_options
+    method_option :annotation, :type => :string, :desc => "Sensor annotation"
+    def create_simple(name, type)
+      with_redis do
+        klass = constantize("PulseMeter::Sensor::#{type}")
+        fail! "Unknown sensor type #{type}" unless klass
+        sensor = klass.new(name, options.dup)
+        puts "Sensor created"
+        puts all_sensors_table
+      end
+    end
+
+    desc "value NAME", "Get value of non-timelined sensor"
+    def value(name)
+      with_safe_restore_of(name) do |sensor|
+        fail! "Sensor #{name} has no value method" unless sensor.respond_to?(:value)
+        puts "Value: #{sensor.value}"
+      end
+    end
+
+  end
+end

data/lib/pulse-meter.rb

@@ -0,0 +1,17 @@
+require "redis"
+require "pulse-meter/version"
+require "pulse-meter/mixins/dumper"
+require "pulse-meter/mixins/utils"
+require "pulse-meter/sensor"
+
+module PulseMeter
+  @@redis = nil
+
+  def self.redis
+    @@redis 
+  end
+
+  def self.redis=(redis)
+    @@redis = redis
+  end
+end

data/lib/pulse-meter/mixins/dumper.rb

@@ -0,0 +1,72 @@
+module PulseMeter
+  module Mixins
+    # Mixin with dumping utilities
+    module Dumper
+      # Prefix for Redis keys with dumped sensors' metadata
+      DUMP_REDIS_KEY = "pulse_meter:dump"
+
+      module InstanceMethods
+        # Serializes object and saves it to Redis
+        # @raise [DumpError] if dumping fails for any reason
+        def dump!
+          ensure_storability!
+          serialized_obj = Marshal.dump(self)
+          redis.hset(DUMP_REDIS_KEY, self.name, serialized_obj)
+        rescue
+          raise DumpError, "object cannot be dumped"
+        end
+
+        # Ensures that object is dumpable
+        # @raise [DumpError] if object cannot be dumped
+        def ensure_storability!
+          raise DumpError, "#name attribute must be readable" unless self.respond_to?(:name)
+          raise DumpError, "#redis attribute must be available" unless self.respond_to?(:redis) && self.redis
+        end
+        
+        # Cleans up object dump in Redis 
+        def cleanup_dump
+          redis.hdel(DUMP_REDIS_KEY, self.name)
+        end
+      end
+
+      module ClassMethods
+        # Restores object from Redis
+        # @param name [String] object name
+        # @return [Object]
+        # @raise [RestoreError] if object cannot be restored for any reason
+        def restore(name)
+          serialized_obj = PulseMeter.redis.hget(DUMP_REDIS_KEY, name)
+          Marshal.load(serialized_obj)
+        rescue
+          raise RestoreError, "cannot restore #{name}"
+        end
+
+        # Lists all dumped objects' names
+        # @return [Array<String>]
+        # @raise [RestoreError] if list cannot be retrieved for any reason
+        def list_names
+          PulseMeter.redis.hkeys(DUMP_REDIS_KEY)
+        rescue
+          raise RestoreError, "cannot get data from redis"
+        end
+
+        # Safely restores all dumped objects
+        # @return [Array<Object>]
+        def list_objects
+          list_names.each_with_object([]) do |name, objects|
+            begin
+              objects << restore(name)
+            rescue
+            end
+          end
+        end
+      end
+
+      def self.included(base)
+        base.send :include, InstanceMethods
+        base.send :extend, ClassMethods
+      end
+
+    end
+  end
+end

data/lib/pulse-meter/mixins/utils.rb

@@ -0,0 +1,91 @@
+require 'securerandom'
+
+module PulseMeter
+  module Mixins
+    # Mixin with various useful functions 
+    module Utils
+      # Tries to find a class with the name specified in the argument string
+      # @param const_name [String] class name
+      # @return [Class] if given class definde
+      # @return [NilClass] if given class is not defined
+      def constantize(const_name)
+        return unless const_name.respond_to?(:to_s)
+        const_name.to_s.split('::').reduce(Module, :const_get)
+      rescue NameError
+        nil
+      end
+
+      # Ensures that hash value specified by key can be converted to positive integer.
+      # In case it can makes in-place conversion and returns the value.
+      # @param options [Hash] hash to be looked at
+      # @param key [Object] hash key
+      # @param default [Object] default value to be returned
+      # @raise [ArgumentError] unless value is positive integer
+      # @return [Fixnum]
+      def assert_positive_integer!(options, key, default = nil)
+        value = options[key] || default
+        raise ArgumentError, "#{key} should be defined" unless value
+        raise ArgumentError, "#{key} should be integer" unless value.respond_to?(:to_i)
+        raise ArgumentError, "#{key} should be positive" unless value.to_i > 0
+        options[key] = value.to_i
+      end
+
+      # Ensures that hash value specified by key is can be converted to float
+      # and it is within given range.
+      # In case it can makes in-place conversion and returns the value.
+      # @param options [Hash] hash to be looked at
+      # @param key [Object] hash key
+      # @param from [Float] lower bound
+      # @param to [Float] upper bound
+      # @raise [ArgumentError] unless value is float within given range
+      # @return [Float]
+      def assert_ranged_float!(options, key, from, to)
+        f = options[key]
+        raise ArgumentError, "#{key} should be defined" unless f
+        raise ArgumentError, "#{key} should be float" unless f.respond_to?(:to_f)
+        f = f.to_f
+        raise ArgumentError, "#{key} should be between #{from} and #{to}" unless f >= from && f <= to
+        options[key] = f
+      end
+
+      # Generates uniq random string
+      # @return [String]
+      def uniqid
+        SecureRandom.hex(32)
+      end
+
+      # Capitalizes the first letter of each word in string
+      # @param str [String]
+      # @return [String]
+      # @raise [ArgumentError] unless passed value responds to to_s
+      def titleize(str)
+        raise ArgumentError unless str.respond_to?(:to_s)
+        str.to_s.split(/[\s_]+/).map(&:capitalize).join(' ')
+      end
+
+      # Converts string from snake_case to CamelCase
+      # @param str [String] string to be camelized
+      # @param first_letter_upper [TrueClass, FalseClass] says if the first letter must be uppercased
+      # @return [String]
+      # @raise [ArgumentError] unless passed value responds to to_s
+      def camelize(str, first_letter_upper = false)
+        raise ArgumentError unless str.respond_to?(:to_s)
+        terms = str.to_s.split(/_/)
+        first = terms.shift
+        (first_letter_upper ? first.capitalize : first.downcase) + terms.map(&:capitalize).join
+      end
+
+      # Deeply capitalizes Array values or Hash keys
+      def camelize_keys(item)
+        case item
+        when Array
+          item.map{|i| camelize_keys(i)}
+        when Hash
+          item.each_with_object({}) { |(k, v), h| h[camelize(k)] = camelize_keys(v)}
+        else
+          item
+        end
+      end
+    end
+  end
+end

data/lib/pulse-meter/sensor.rb

@@ -0,0 +1,44 @@
+require 'pulse-meter/sensor/base'
+require 'pulse-meter/sensor/counter'
+require 'pulse-meter/sensor/hashed_counter'
+require 'pulse-meter/sensor/indicator'
+require 'pulse-meter/sensor/timeline'
+require 'pulse-meter/sensor/timelined/average'
+require 'pulse-meter/sensor/timelined/counter'
+require 'pulse-meter/sensor/timelined/hashed_counter'
+require 'pulse-meter/sensor/timelined/min'
+require 'pulse-meter/sensor/timelined/max'
+require 'pulse-meter/sensor/timelined/percentile'
+require 'pulse-meter/sensor/timelined/median'
+
+# Top level sensor module
+module PulseMeter
+
+  # Atomic sensor data
+  SensorData = Struct.new(:start_time, :value)
+
+  # General sensor exception
+  class SensorError < StandardError; end
+
+  # Exception to be raised when sensor name is malformed
+  class BadSensorName < SensorError
+    def initialize(name, options = {})
+      super("Bad sensor name: `#{name}', only a-z letters and _ are allowed")
+    end
+  end
+
+  # Exception to be raised when Redis is not initialized
+  class RedisNotInitialized < SensorError
+    def initialize
+      super("PulseMeter.redis is not set")
+    end
+  end
+
+  # Exception to be raised when sensor cannot be dumped
+  class DumpError < SensorError; end
+
+  # Exception to be raised when sensor cannot be restored
+  class RestoreError < SensorError; end
+
+end
+  

data/lib/pulse-meter/sensor/base.rb

@@ -0,0 +1,75 @@
+module PulseMeter
+  module Sensor
+    # @abstract Subclass and override {#event} to implement sensor 
+    class Base
+      include PulseMeter::Mixins::Dumper
+
+      # @!attribute [rw] redis
+      #   @return [Redis] 
+      attr_accessor :redis
+      # @!attribute [r] name
+      #   @return [String] sensor name
+      attr_reader :name
+
+      # Initializes sensor and dumps it to redis
+      # @param name [String] sensor name
+      # @option options [String] :annotation Sensor annotation
+      # @raise [BadSensorName] if sensor name is malformed
+      # @raise [RedisNotInitialized] unless Redis is initialized
+      def initialize(name, options={})
+        @name = name.to_s
+        if options[:annotation]
+          annotate(options[:annotation])
+        end
+        raise BadSensorName, @name unless @name =~ /\A\w+\z/
+        raise RedisNotInitialized unless PulseMeter.redis
+        dump!
+      end
+
+      # Returns Redis instance
+      def redis
+        PulseMeter.redis
+      end
+
+      # Saves annotation to Redis
+      # @param description [String] Sensor annotation
+      def annotate(description)
+        redis.set(desc_key, description)
+      end
+
+      # Retrieves annotation from Redis
+      # @return [String] Sensor annotation
+      def annotation
+        redis.get(desc_key)
+      end
+
+      # Cleans up all sensor metadata in Redis
+      def cleanup
+        redis.del(desc_key)
+        cleanup_dump
+      end
+  
+      # @abstract Processes event
+      # @param value [Object] value produced by some kind of event
+      def event(value)
+        # do nothing here
+      end
+
+      protected
+      
+      # Forms Redis key to store annotation
+      def desc_key
+        "pulse_meter:desc:#{name}"
+      end
+      
+      # For a block
+      # @yield Executes it within Redis multi
+      def multi
+        redis.multi 
+        yield
+        redis.exec
+      end
+
+    end
+  end
+end