meter 0.0.1

data/LICENSE

@@ -0,0 +1,21 @@
+The MIT License
+
+Copyright (c) 2013 Bukowskis
+
+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,29 @@
+# Meter
+
+BETA!
+
+A generic abstraction layer for fire and forgetting measurements via UDP.
+
+# Installation
+
+```bash
+gem install meter
+````
+
+# Usage
+
+#### Syntax
+
+```ruby
+Meter.increment key, delta, options
+````
+
+#### Examples 
+
+```ruby
+Meter.increment 'my.key'
+Meter.increment 'my.key', 5
+Meter.increment 'my.key', 5, sample_rate: 0.25
+
+Meter.gauge 'my.gauge.key', 20
+```

data/lib/meter/backend.rb

@@ -0,0 +1,190 @@
+require 'socket'
+
+# Copy and paste from https://github.com/DataDog/dogstatsd-ruby/blob/master/lib/statsd.rb
+# Changes:
+# - The class is renamed to "Backend"
+# - the logger class method points to meter's logger
+
+module Meter
+  # = Statsd: A DogStatsd client (https://www.datadoghq.com)
+  #
+  # @example Set up a global Statsd client for a server on localhost:8125
+  #   require 'statsd'
+  #   $statsd = Statsd.new 'localhost', 8125
+  # @example Send some stats
+  #   $statsd.increment 'page.views'
+  #   $statsd.timing 'page.load', 320
+  #   $statsd.gauge 'users.online', 100
+  # @example Use {#time} to time the execution of a block
+  #   $statsd.time('account.activate') { @account.activate! }
+  # @example Create a namespaced statsd client and increment 'account.activate'
+  #   statsd = Statsd.new('localhost').tap{|sd| sd.namespace = 'account'}
+  #   statsd.increment 'activate'
+  class Backend
+    # A namespace to prepend to all statsd calls.
+    attr_reader :namespace
+
+    # StatsD host. Defaults to 127.0.0.1.
+    attr_accessor :host
+
+    # StatsD port. Defaults to 8125.
+    attr_accessor :port
+
+    def self.logger
+      Meter.config.logger
+    end
+
+    # Return the current version of the library.
+    def self.VERSION
+      "1.1.0"
+    end
+
+    # @param [String] host your statsd host
+    # @param [Integer] port your statsd port
+    def initialize(host = '127.0.0.1', port = 8125)
+      self.host, self.port = host, port
+      @prefix = nil
+      @socket = UDPSocket.new
+    end
+
+    def namespace=(namespace) #:nodoc:
+      @namespace = namespace
+      @prefix = "#{namespace}."
+    end
+
+    def host=(host) #:nodoc:
+      @host = host || '127.0.0.1'
+    end
+
+    def port=(port) #:nodoc:
+      @port = port || 8125
+    end
+
+    # Sends an increment (count = 1) for the given stat to the statsd server.
+    #
+    # @param [String] stat stat name
+    # @param [Hash] opts the options to create the metric with
+    # @option opts [Numeric] :sample_rate sample rate, 1 for always
+    # @option opts [Array<String>] :tags An array of tags
+    # @see #count
+    def increment(stat, opts={})
+      count stat, 1, opts
+    end
+
+    # Sends a decrement (count = -1) for the given stat to the statsd server.
+    #
+    # @param [String] stat stat name
+    # @param [Hash] opts the options to create the metric with
+    # @option opts [Numeric] :sample_rate sample rate, 1 for always
+    # @option opts [Array<String>] :tags An array of tags
+    # @see #count
+    def decrement(stat, opts={})
+      count stat, -1, opts
+    end
+
+    # Sends an arbitrary count for the given stat to the statsd server.
+    #
+    # @param [String] stat stat name
+    # @param [Integer] count count
+    # @param [Hash] opts the options to create the metric with
+    # @option opts [Numeric] :sample_rate sample rate, 1 for always
+    # @option opts [Array<String>] :tags An array of tags
+    def count(stat, count, opts={})
+      send_stats stat, count, :c, opts
+    end
+
+    # Sends an arbitary gauge value for the given stat to the statsd server.
+    #
+    # This is useful for recording things like available disk space,
+    # memory usage, and the like, which have different semantics than
+    # counters.
+    #
+    # @param [String] stat stat name.
+    # @param [Numeric] gauge value.
+    # @param [Hash] opts the options to create the metric with
+    # @option opts [Numeric] :sample_rate sample rate, 1 for always
+    # @option opts [Array<String>] :tags An array of tags
+    # @example Report the current user count:
+    #   $statsd.gauge('user.count', User.count)
+    def gauge(stat, value, opts={})
+      send_stats stat, value, :g, opts
+    end
+
+    # Sends a value to be tracked as a histogram to the statsd server.
+    #
+    # @param [String] stat stat name.
+    # @param [Numeric] histogram value.
+    # @param [Hash] opts the options to create the metric with
+    # @option opts [Numeric] :sample_rate sample rate, 1 for always
+    # @option opts [Array<String>] :tags An array of tags
+    # @example Report the current user count:
+    #   $statsd.histogram('user.count', User.count)
+    def histogram(stat, value, opts={})
+      send_stats stat, value, :h, opts
+    end
+
+    # Sends a timing (in ms) for the given stat to the statsd server. The
+    # sample_rate determines what percentage of the time this report is sent. The
+    # statsd server then uses the sample_rate to correctly track the average
+    # timing for the stat.
+    #
+    # @param [String] stat stat name
+    # @param [Integer] ms timing in milliseconds
+    # @param [Hash] opts the options to create the metric with
+    # @option opts [Numeric] :sample_rate sample rate, 1 for always
+    # @option opts [Array<String>] :tags An array of tags
+    def timing(stat, ms, opts={})
+      send_stats stat, ms, :ms, opts
+    end
+
+    # Reports execution time of the provided block using {#timing}.
+    #
+    # @param [String] stat stat name
+    # @param [Hash] opts the options to create the metric with
+    # @option opts [Numeric] :sample_rate sample rate, 1 for always
+    # @option opts [Array<String>] :tags An array of tags
+    # @yield The operation to be timed
+    # @see #timing
+    # @example Report the time (in ms) taken to activate an account
+    #   $statsd.time('account.activate') { @account.activate! }
+    def time(stat, opts={})
+      start = Time.now
+      result = yield
+      timing(stat, ((Time.now - start) * 1000).round, opts)
+      result
+    end
+    # Sends a value to be tracked as a set to the statsd server.
+    #
+    # @param [String] stat stat name.
+    # @param [Numeric] set value.
+    # @param [Hash] opts the options to create the metric with
+    # @option opts [Numeric] :sample_rate sample rate, 1 for always
+    # @option opts [Array<String>] :tags An array of tags
+    # @example Record a unique visitory by id:
+    #   $statsd.set('visitors.uniques', User.id)
+    def set(stat, value, opts={})
+      send_stats stat, value, :s, opts
+    end
+
+    private
+
+    def send_stats(stat, delta, type, opts={})
+      sample_rate = opts[:sample_rate] || 1
+      if sample_rate == 1 or rand < sample_rate
+        # Replace Ruby module scoping with '.' and reserved chars (: | @) with underscores.
+        stat = stat.to_s.gsub('::', '.').tr(':|@', '_')
+        rate = "|@#{sample_rate}" unless sample_rate == 1
+        tags = "|##{opts[:tags].join(",")}" if opts[:tags]
+        send_to_socket "#{@prefix}#{stat}:#{delta}|#{type}#{rate}#{tags}"
+      end
+    end
+
+    def send_to_socket(message)
+      self.class.logger.debug { "Statsd: #{message}" } if self.class.logger
+      @socket.send(message, 0, @host, @port)
+    rescue => boom
+      self.class.logger.error { "Statsd: #{boom.class} #{boom}" } if self.class.logger
+      nil
+    end
+  end
+end

data/lib/meter/configuration.rb

@@ -0,0 +1,112 @@
+require 'logger'
+require 'meter/backend'
+
+module Meter
+  class Configuration
+
+    attr_accessor :logger, :tags
+    attr_reader :primary_backend, :secondary_backend
+
+    def initialize(options={})
+      @logger = options[:logger] || default_logger
+      @primary_backend = Backend.new
+      @primary_backend.host = options[:primary_host] || default_host
+      @primary_backend.port = options[:primary_port] || default_port
+      @primary_backend.namespace = options[:namespace] || default_namespace
+      @secondary_backend = Backend.new
+      @secondary_backend.host = options[:secondary_host] || default_host
+      @secondary_backend.port = options[:secondary_port] || default_secondary_port
+      @secondary_backend.namespace = options[:namespace] || default_namespace
+      @tags = options[:tags] || {}
+    end
+
+    def namespace=(new_namespace)
+      primary_backend.namespace = new_namespace
+      secondary_backend.namespace = new_namespace
+    end
+
+    def namespace
+      primary_backend.namespace
+    end
+
+    def primary_host
+      primary_backend.host
+    end
+
+    def primary_port
+      primary_backend.port
+    end
+
+    def secondary_host
+      secondary_backend.host
+    end
+
+    def secondary_port
+      secondary_backend.port
+    end
+
+    def primary_host=(new_host)
+      primary_backend.host = new_host
+    end
+
+    def primary_port=(new_port)
+      primary_backend.port = new_port
+    end
+
+    def secondary_host=(new_host)
+      secondary_backend.host = new_host
+    end
+
+    def secondary_port=(new_port)
+      secondary_backend.port = new_port
+    end
+
+    private
+
+    def default_logger
+      if defined?(Rails)
+        Rails.logger
+      else
+        Logger.new(STDOUT)
+      end
+    end
+
+    def default_host
+      '127.0.0.1'
+    end
+
+    def default_port
+      8125
+    end
+
+    def default_secondary_port
+      3333
+    end
+
+    def default_namespace
+      'meter'
+    end
+
+  end
+end
+
+module Meter
+
+  # Public: Returns the the configuration instance.
+  #
+  def self.config
+    @config ||= Configuration.new
+  end
+
+  # Public: Yields the configuration instance.
+  #
+  def self.configure(&block)
+    yield config
+  end
+
+  # Public: Reset the configuration (useful for testing).
+  #
+  def self.reset!
+    @config = nil
+  end
+end

data/lib/meter/version.rb

@@ -0,0 +1,9 @@
+module Meter
+  module VERSION #:nodoc:
+    MAJOR = 0
+    MINOR = 0
+    TINY  = 1
+
+    STRING = [MAJOR, MINOR, TINY].compact.join('.')
+  end
+end

data/lib/meter.rb

@@ -0,0 +1,42 @@
+require 'meter/configuration'
+
+# A generic wrapper for Statsd-like gauges and counters.
+#
+module Meter
+  extend self
+
+  def increment(key, options = {})
+    id = options.delete(:id)
+    primary.increment key, options
+    if id
+      secondary.increment "#{key}.#{id}", options
+    end
+  end
+
+  def count(key, delta, options = {})
+    id = options.delete(:id)
+    primary.count key, delta, options
+    if id
+      secondary.count "#{key}.#{id}", delta, options
+    end
+  end
+
+  def gauge(key, value, options = {})
+    primary.gauge key, value, options
+  end
+
+  def histogram(key, value, options = {})
+    primary.histogram key, value, options
+  end
+
+  private
+
+  def primary
+    config.primary_backend
+  end
+
+  def secondary
+    config.secondary_backend
+  end
+
+end

data/spec/lib/meter/backend_spec.rb

@@ -0,0 +1,18 @@
+require 'spec_helper'
+require 'meter'
+
+describe Meter::Backend do
+
+  let(:backend) { Meter.config.primary_backend }
+
+  before do
+    Meter.reset!
+  end
+
+  describe '.increment' do
+    it 'works and I did not make any mistakes when copy and pasting the backend from StatsD' do
+      backend.increment 'my.counter'
+    end
+  end
+
+end

data/spec/lib/meter/configuration_spec.rb

@@ -0,0 +1,60 @@
+require 'spec_helper'
+require 'meter/configuration'
+
+describe Meter::Configuration do
+
+  let(:logger) { mock(:logger) }
+  let(:config)  { Meter.config }
+
+  before do
+    Meter.reset!
+  end
+
+  describe '.config' do
+
+    describe '#logger' do
+      it 'is an STDOUT logger' do
+        Logger.should_receive(:new).with(STDOUT).and_return logger
+        config.logger.should be logger
+      end
+
+      context 'with Rails' do
+        before do
+          ensure_module :Rails
+          Rails.stub!(:logger).and_return(logger)
+        end
+
+        after do
+          Object.send(:remove_const, :Rails)
+        end
+
+        it 'is the Rails logger' do
+          config.logger.should be Rails.logger
+        end
+      end
+    end
+
+    describe '#primary_backend and #secondary_backend' do
+      it 'is a Backend' do
+        config.primary_backend.should be_instance_of Meter::Backend
+        config.secondary_backend.should be_instance_of Meter::Backend
+      end
+
+      it 'has the default host' do
+        config.primary_backend.host.should == '127.0.0.1'
+        config.secondary_backend.host.should == '127.0.0.1'
+      end
+
+      it 'has the default namespace' do
+        config.primary_backend.namespace.should == 'meter'
+        config.secondary_backend.namespace.should == 'meter'
+      end
+
+      it 'has the default port' do
+        config.primary_backend.port.should == 8125
+        config.secondary_backend.port.should == 3333
+      end
+    end
+
+  end
+end

data/spec/lib/meter_spec.rb

@@ -0,0 +1,34 @@
+require 'spec_helper'
+
+describe Meter do
+
+  let(:meter)     { Meter }
+  let(:primary)    { Meter.config.primary_backend }
+  let(:secondary) { Meter.config.secondary_backend }
+
+  describe '.increment' do
+    context "when given an id as option"  do
+      it "proxies to the secondary with the id" do
+        secondary.should_receive(:increment).with("my.key.123", {})
+        meter.increment 'my.key', :id => 123
+      end
+
+      it "proxies to the primary without the id" do
+        primary.should_receive(:increment).with("my.key", {})
+        meter.increment 'my.key', :id => 123
+      end
+    end
+
+    context "when id is NOT given as an option"  do
+      it "doesn't proxy to the secondary at all" do
+        secondary.should_not_receive(:increment)
+        meter.increment 'my.key'
+      end
+
+      it "proxies to the primary" do
+        primary.should_receive(:increment).with("my.key", {})
+        meter.increment 'my.key'
+      end
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,33 @@
+require 'meter'
+
+def ensure_class_or_module(full_name, class_or_module)
+  full_name.to_s.split(/::/).inject(Object) do |context, name|
+    begin
+      context.const_get(name)
+    rescue NameError
+      if class_or_module == :class
+        context.const_set(name, Class.new)
+      else
+        context.const_set(name, Module.new)
+      end
+    end
+  end
+end
+
+def ensure_module(name)
+  ensure_class_or_module(name, :module)
+end
+
+def ensure_class(name)
+  ensure_class_or_module(name, :class)
+end
+
+RSpec.configure do |config|
+  config.before do
+    Meter.config.logger = nil
+  end
+
+  config.after do
+    Meter.reset!
+  end
+end

metadata

@@ -0,0 +1,107 @@
+--- !ruby/object:Gem::Specification
+name: meter
+version: !ruby/object:Gem::Version
+  prerelease: 
+  version: 0.0.1
+platform: ruby
+authors:
+- bukowskis
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-08-13 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+    none: false
+  name: rspec
+  type: :development
+  prerelease: false
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+    none: false
+- !ruby/object:Gem::Dependency
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+    none: false
+  name: guard-rspec
+  type: :development
+  prerelease: false
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+    none: false
+- !ruby/object:Gem::Dependency
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+    none: false
+  name: rb-fsevent
+  type: :development
+  prerelease: false
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+    none: false
+description: A generic abstraction layer for fire and forgetting measurements via
+  UDP.
+email: 
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/meter/backend.rb
+- lib/meter/configuration.rb
+- lib/meter/version.rb
+- lib/meter.rb
+- spec/lib/meter/backend_spec.rb
+- spec/lib/meter/configuration_spec.rb
+- spec/lib/meter_spec.rb
+- spec/spec_helper.rb
+- README.md
+- LICENSE
+homepage: https://github.com/bukowskis/meter
+licenses:
+- MIT
+post_install_message: 
+rdoc_options:
+- --encoding
+- UTF-8
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+  none: false
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+  none: false
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.23
+signing_key: 
+specification_version: 3
+summary: A generic abstraction layer for fire and forgetting measurements via UDP.
+test_files: []
+has_rdoc: