hallmonitor 0.4.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 2d62d082477737cb28427f17c204445f84782d1f
-  data.tar.gz: 949e08d6e519ecbe58cebd50f5b663671e0496ce
+  metadata.gz: a94b8069a987ca9eb3493b18f47b5a92b45b3881
+  data.tar.gz: 44949242eb518251bb8327350c01f4001d978fb1
 SHA512:
-  metadata.gz: 6f244f06a3c98c8da024fb9b5e608a3a7cef717ac58092d88eb40b28827d1888286c386d31a48ecc4ef3f1c21e7aedcf6de4184f5f08cdabb11680426fd10e3d
-  data.tar.gz: d0c64796b5c0328f19dab64c63747375ee345b929b106592fc6bd4f27962906cab6cf1ee62c244b08b780e958dd134f795ee0068de234014f66a5e633df9092c
+  metadata.gz: 30c54a353d079bfffc7285d229a9b4224ebcf9378fe91412c8e83a5ce4dab7d617d5bc12499890644842be9d5e9864e7f75debaf2ccc74a9b6475e52021163aa
+  data.tar.gz: d17fbde9caa08887b1a704fe9ffa076f362e494b402afc599dee8e798c6f90783b7eef013268218144d08d291fe228d10a0b79795309de3f8ddc11fc52fe20bb

data/README.md

@@ -1,18 +1,33 @@
 # Hallmonitor
 
-Hallmonitor is a simple event monitoring framework for Ruby.  It allows programs to define and emit events.
+Hallmonitor is a simple event monitoring framework for Ruby.  It allows programs to define and emit events. These events can then be sent on to various back ends to be counted, monitored, etc.
 
-Hallmonitor supports publishing events to a Statsd instance if the 'statsd-ruby' gem is installed.  See https://github.com/reinh/statsd for details
+Hallmonitor includes support for publishing events to a Statsd instance if the `statsd-ruby` gem is installed.  See https://github.com/reinh/statsd for details
 
 ## Setup
-Before you can use Hallmonitor you have to do a tiny bit of configuration in the form of adding outputters
+Before you can use Hallmonitor you have to do a tiny bit of configuration in the form of adding outputters.
 
 ```ruby
-Hallmonitor::Outputter.add_outputter Hallmonitor::Outputters::IOOutputter.new("STDOUT", STDOUT)
-Hallmonitor::Outputter.add_outputter Hallmonitor::Outputters::StatsdOutputter.new("example", "localhost")
+# Add an outputter to STDOUT
+Hallmonitor.add_outputter Hallmonitor::Outputters::IOOutputter.new("STDOUT", STDOUT)
+
+# Add an outputter to StatsD
+Hallmonitor.add_outputter Hallmonitor::Outputters::StatsdOutputter.new("example", "localhost")
+```
+
+The `StatsdOutputter` is only available if you've installed the `statsd-ruby` gem.  If it's not available, StatsdOutputter's intitialize method will raise a RuntimeError
+
+## Configuration
+Right now there's only one configuration option and here's how you can set it:
+
+```ruby
+# Configure Hallmonitor
+Hallmonitor.config |config|
+  config.trap_outputter_exceptions = true # Default value is false
+end
 ```
 
-The StatsdOutputter is only available if you've installed the `statsd-ruby` gem.  If it's not available, StatsdOutputter's intitialize method will raise a RuntimeError
+**trap_outputter_exceptions:** instructs the output framework to ignore and squash any exceptions that might be raised from inside an outputter.  This can be useful if you want to configure multiple outputter and not have a misbehaving one interrupt other outputter, or your system.
 
 ## Usage
 
@@ -21,13 +36,15 @@ There are a few different ways to use Hallmonitor:
 ### Included in your class
 ```ruby
 class Foo
+  # Monitored adds a few methods you can use, like emit(...) and watch(...)
   include Hallmonitor::Monitored
 
   # This method will emit 100 events
   def bar
+
     # Emit 100 events.  The string will be the name of the Event object that gets emitted
     100.times do
-      emit("event")
+      emit("event") # Will emit a new Event with the name 'event'
     end
 
     # You can also just emit Event objects themselves
@@ -39,9 +56,9 @@ class Foo
     end
   end
 
-  # This method will emit 1 TimedEvent for the block
+  # This method will emit 1 TimedEvent for the block with the name 'timed'
   def time_me
-    watch("timed") do |x|
+    watch("timed") do
       sleep(10)
     end
   end
@@ -54,14 +71,14 @@ foo.time_me # Will emit a single TimedEvent
 
 ### Explicit Event objects
 ```ruby
+# Event objects include Hallmonitor::Monitored and so they have
+# an emit method of their own
 event = Hallmonitor::Event.new("event")
 event.emit
 ```
 
-
-
 ## Contributing to Hallmonitor
- 
+
 * Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet.
 * Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it.
 * Fork the project.
@@ -72,6 +89,5 @@ event.emit
 
 ## Copyright
 
-Copyright (c) 2012 Chris TenHarmsel. See LICENSE.txt for
+Copyright (c) 2012-2015 Chris TenHarmsel. See LICENSE.txt for
 further details.
-

data/bin/example.rb

@@ -1,3 +1,5 @@
+#!/usr/bin/env ruby
+
 lib = File.expand_path('../../lib', __FILE__)
 $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
 
@@ -6,8 +8,8 @@ require 'hallmonitor/outputters/iooutputter'
 require 'hallmonitor/outputters/statsd_outputter'
 require 'pry'
 
-Hallmonitor::Outputter.add_outputter Hallmonitor::Outputters::IOOutputter.new("STDOUT", STDOUT)
-Hallmonitor::Outputter.add_outputter Hallmonitor::Outputters::StatsdOutputter.new("example", "graphite.demo.transis.net")
+Hallmonitor.add_outputter Hallmonitor::Outputters::IOOutputter.new("STDOUT", STDOUT)
+Hallmonitor.add_outputter Hallmonitor::Outputters::StatsdOutputter.new("example", "localhost")
 
 class Foo
   include Hallmonitor::Monitored
@@ -30,9 +32,18 @@ class Foo
 
   def time_me
     watch("timed") do |x|
-      sleep(10)
+      sleep(5)
     end
   end
 end
 
-binding.pry
+f = Foo.new
+
+puts 'Calling method with timer_for and count_for...'
+f.do_something
+
+puts 'Emitting some events'
+f.emit_events(5)
+
+puts 'Timing a 5 second block'
+f.time_me

data/hallmonitor.gemspec

@@ -1,7 +1,3 @@
-# Generated by jeweler
-# DO NOT EDIT THIS FILE DIRECTLY
-# Instead, edit Jeweler::Tasks in Rakefile, and run 'rake gemspec'
-# -*- encoding: utf-8 -*-
 lib = File.expand_path('../lib', __FILE__)
 $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
 require 'hallmonitor/version'
@@ -22,7 +18,8 @@ Gem::Specification.new do |s|
   s.require_paths = ["lib"]
 
   s.add_runtime_dependency("json", [">= 0"])
-  s.add_runtime_dependency("statsd-ruby", [">= 0"])
+
+  s.add_development_dependency("statsd-ruby", [">= 0"])
   s.add_development_dependency("rspec", [">= 3.0"])
   s.add_development_dependency("rdoc", [">= 0"])
   s.add_development_dependency("bundler", ["~> 1.3"])

data/lib/hallmonitor/configuration.rb

@@ -0,0 +1,11 @@
+module Hallmonitor
+  # Hallmonitor configuration
+  class Configuration
+    # Whether or not to trap outputter exceptions, defaults to false
+    attr_accessor :trap_outputter_exceptions
+
+    def initialize
+      @trap_outputter_exceptions = false
+    end
+  end
+end

data/lib/hallmonitor/dispatcher.rb

@@ -0,0 +1,40 @@
+module Hallmonitor
+  class Dispatcher
+    @outputters = []
+
+    # Returns list of outputters registered
+    # @return [Array<Outputter>]
+    def self.outputters
+      @outputters
+    end
+
+    # Adds an outputter.  Outputters are required to respond to :process
+    # @param outputter [Object]
+    # @see Hallmonitor::Outputters::StatsdOutputter
+    def self.add_outputter(outputter)
+      @outputters << outputter if outputter.respond_to?(:process)
+    end
+
+    # Removes all outputters
+    def self.clear_outputters
+      @outputters = []
+    end
+
+    # Outputs an event via each registered outputter.
+    # If {Hallmonitor::Configuration} has the option
+    # `trap_outputter_exceptions` set to `true` then this method
+    # will trap and squash any errors raised by the outputter.
+    # @param event [Event] The event to output
+    # @return nil
+    def self.output(event)
+      @outputters.each do |o|
+        begin
+          o.process(event)
+        rescue
+          raise unless Hallmonitor.config.trap_outputter_exceptions
+        end
+      end
+      nil
+    end
+  end
+end

data/lib/hallmonitor/event.rb

@@ -1,12 +1,15 @@
 require 'hallmonitor/monitored'
 module Hallmonitor
-  ##
-  # The event class is a single-fire event
+  # The event class is a single-fire event, it most often
+  # represents a single, countable metric.
   class Event
     include Hallmonitor::Monitored
-    
+
     attr_accessor :name, :time, :count
-    
+
+    # Builds a new event
+    # @param name [String] the name of this event
+    # @param count [Number] the count of this even, defaults to 1
     def initialize(name, count=1)
       @name = name
       @time = Time.now

data/lib/hallmonitor/gauge_event.rb

@@ -1,15 +1,24 @@
 module Hallmonitor
+  # A Guage event is an event that has a specific value,
+  # think of it like a tachometer or gas guage on a car:
+  # at any given point it reports the current value of a
+  # variable.
   class GaugeEvent < Event
+    # @param name [String] Name of this guage
+    # @param value [Number] The current value of this guage
     def initialize(name, value)
       super(name, value)
     end
 
+    # The value of this guage
     def value
       count
     end
 
+    # Sets the value of this guage
+    # @param new_value [Number]
     def value=(new_value)
-      count = new_value
+      self.count = new_value
     end
 
   end

data/lib/hallmonitor/monitored.rb

@@ -53,12 +53,14 @@ module Hallmonitor
       base.extend(ClassMethods)
     end
 
-    # Emits an event: either self or an event if one is passed in, or constructs
-    # a base event from the passed in param
+    # Emits an event: self if the event param is nil, the passed in event if
+    # it's an {Event}, or constructs a {Event} from the passed in param.
+    #
     # If the parameter is a {Hallmonitor::Event}, it will be emitted as is.
     # Otherwise, a new {Hallmonitor::Event} will be created with the parameter
     # and emitted.
     # @param event [Mixed] The thing to emit, see method description
+    # @yield [to_emit] The thing that's going to be emitted
     # @return nil
     def emit(event = nil)
       to_emit = self
@@ -69,13 +71,14 @@ module Hallmonitor
       # If we were given a block, then we want to execute that
       yield(to_emit) if block_given?
 
-      Outputter.output(to_emit)
+      Dispatcher.output(to_emit)
       nil
     end
 
-    # Executes and times a block of code and emits a Hallmonitor::TimedEvent
-    # Will emit even if the block raises an error
+    # Executes and times a block of code and emits a {TimedEvent}
+    # @note Will emit the timed event even if the block raises an error
     # @param name [String] The name of the event to emit
+    # @yield [event] the event object that will be emitted
     # @return Whatever the block's return value is
     def watch(name)
       event = Hallmonitor::TimedEvent.new(name)

data/lib/hallmonitor/outputter.rb

@@ -1,34 +1,17 @@
 module Hallmonitor
+  # An {Outputter} is an object that can process {Hallmonitor::Event}s
   class Outputter
     attr_reader :name
-    @@outputters = Array.new
 
+    # Initializes a new Outputter
+    # @param name [Object] Probably a string or symbol, the name of this
+    # outputter
     def initialize(name)
       raise(ArgumentError, "Outputter expects a name") if name.nil?
       @name = name
     end
 
-    # Returns the current list of outputters
-    # @return [Object] Outputters
-    def self.outputters
-      @@outputters
-    end
-
-    # Adds an outputter.  Outputters are required to respond to :process
-    # @see Hallmonitor::Outputters::StatsdOutputter
-    def self.add_outputter(outputter)
-      @@outputters << outputter if outputter.respond_to?(:process)
-    end
-
-    # Outputs the event via each configured outputter
-    # @param event [Event] The event to output
-    def self.output(event)
-      @@outputters.each do |o|
-        o.process(event)
-      end
-    end
-
-    # Processes and event.  Child classes should implement this to output events
+    # Processes an event.  Child classes should implement this to output events
     # @param event [Event] the event to process
     def process(event)
       # Nothing

data/lib/hallmonitor/outputters/iooutputter.rb

@@ -2,13 +2,19 @@ require 'json'
 
 module Hallmonitor
   module Outputters
+    # Simple outputter that just prints to an output stream
     class IOOutputter < Outputter
 
+      # Builds a new IOOutputter
+      # @param name [String] Name for this outputter
+      # @param out [IO] Output to write to
       def initialize(name, out)
         super(name)
         @out = out
       end
 
+      # Sends an event to the configured output
+      # on IOError the output will be closed
       def process(event)
         begin
           @out.print "EVENT: #{event.to_json}\n"

data/lib/hallmonitor/outputters/statsd_outputter.rb

@@ -5,13 +5,21 @@ end
 
 module Hallmonitor
   module Outputters
+    # An outputter for StatsD
     class StatsdOutputter < Outputter
+      # Builds a new StatsdOutputter.
+      # @param prefix [String] Prefix for all events output by this outputter,
+      #   the prefix will be applied to all event names before sending to statsd
+      # @param host [String] Statsd Host, defaults to 'localhost'
+      # @param port [Number] Statsd Port, defaults to 8125
+      # @raise if Statsd is undefined (Gem not present)
       def initialize(prefix, host="localhost", port=8125)
         raise "In order to use StatsdOutputter, statsd gem must be installed" unless defined?(Statsd)
         super(prefix)
         @statsd = Statsd.new(host).tap{|sd| sd.namespace = name}
       end
 
+      # Sends events to statsd instance
       def process(event)
         if(event.respond_to?(:duration))
           @statsd.timing(event.name, event.duration)

data/lib/hallmonitor/timed_event.rb

@@ -1,17 +1,30 @@
 module Hallmonitor
+  # An event that represents a span of time
   class TimedEvent < Event
+    # @!attribute start
+    #   @return [DateTime] the start time of this timed event
+    # @!attribute stop
+    #   @return [DateTime] the stop time of this timed event
+
     attr_accessor :start, :stop
 
+    # Builds a new {TimedEvent}
+    # @param name [String] name of this event
+    # @param duration [Number] the timespan of this event
     def initialize(name, duration=nil)
       super(name)
       @duration = duration
     end
 
-    # Duration, should be set in ms, will take precedence over
-    # calculating via start and stop times
+    # @!attribute [w] duration
+    #   Duration, should be set in ms, will take precedence over
+    #   calculating via start and stop times
+    #   @return [Number] the currently value of duration
     attr_writer :duration
 
     # Reports duration of this timed event in ms
+    # @return [Number] duration, in ms if calculated based on
+    #   {#start} and {#stop}
     def duration
       if @duration
         @duration

data/lib/hallmonitor/version.rb

@@ -1,7 +1,7 @@
 module Hallmonitor
   module Version
-    MAJOR = 0
-    MINOR = 4
+    MAJOR = 1
+    MINOR = 0
     PATCH = 0
     BUILD = nil
 

data/lib/hallmonitor.rb

@@ -1,6 +1,30 @@
+require 'hallmonitor/configuration'
+require 'hallmonitor/dispatcher'
 require 'hallmonitor/monitored'
 require 'hallmonitor/event'
 require 'hallmonitor/timed_event'
 require 'hallmonitor/gauge_event'
 require 'hallmonitor/outputter'
 require 'hallmonitor/middleware'
+
+module Hallmonitor
+  class << self
+    attr_accessor :config
+  end
+
+  # Method to configure Hallmonitor, takes a block and passes a
+  # {Hallmonitor::Configuration} object in, which can be used to
+  # set configuration options.
+  def self.configure
+    self.config ||= Hallmonitor::Configuration.new
+    yield(config)
+  end
+
+  # Adds an outputter to Hallmonitor.  Whenever events are emitted
+  # they will be sent to all registered outputters
+  # @param outputter [Outputter] An instance of an outputter
+  # @note This delegates to {Dispatcher.add_outputter}
+  def self.add_outputter(outputter)
+    Dispatcher.add_outputter(outputter)
+  end
+end

data/spec/hallmonitor/dispatcher_spec.rb

@@ -0,0 +1,58 @@
+require 'spec_helper'
+module Hallmonitor
+  RSpec.describe Dispatcher do
+    let(:outputter) { instance_double(Hallmonitor::Outputter) }
+    before do
+      allow(outputter).to receive(:process)
+      Dispatcher.add_outputter(outputter)
+    end
+
+    after do
+      Dispatcher.clear_outputters
+    end
+
+    describe "managing outputters" do
+      it 'tracks outputters' do
+        expect(Dispatcher.outputters).to include(outputter)
+      end
+    end
+
+    describe '#output' do
+      it 'dispatches to outputters' do
+        expect(outputter).to receive(:process).with("thing")
+        Dispatcher.output("thing")
+      end
+
+      describe 'with exception trapping turned off' do
+        before do
+          allow(outputter).to receive(:process).and_raise("FOOOOO")
+          Hallmonitor.configure do |c|
+            c.trap_outputter_exceptions = false
+          end
+        end
+        it 'raises outputter exceptions' do
+          expect{Dispatcher.output("thing")}.to raise_error
+        end
+      end
+
+      describe 'with exception trapping turned on' do
+        let(:another_outputter) { instance_double(Hallmonitor::Outputter) }
+        before do
+          allow(outputter).to receive(:process).and_raise("FOOOOO")
+          Hallmonitor.configure do |c|
+            c.trap_outputter_exceptions = true
+          end
+          allow(another_outputter).to receive(:process)
+          Dispatcher.add_outputter(another_outputter)
+        end
+        it 'traps outputter exceptions' do
+          expect{Dispatcher.output("thing")}.to_not raise_error
+        end
+        it 'calls other outputters' do
+          expect(another_outputter).to receive(:process).with("thing")
+          expect{Dispatcher.output("thing")}.to_not raise_error
+        end
+      end
+    end
+  end
+end

data/spec/{monitored_spec.rb → hallmonitor/monitored_spec.rb}

@@ -27,7 +27,7 @@ RSpec.describe Hallmonitor::Monitored do
 
   describe '#timer_for' do
     it 'emits a timer with an appropriate name' do
-      expect(Hallmonitor::Outputter).to(
+      expect(Hallmonitor::Dispatcher).to(
         receive(:output).with(a_timed_event_with_name('thing.timer_for_test')))
       Thing.new.timer_for_test
     end
@@ -35,7 +35,7 @@ RSpec.describe Hallmonitor::Monitored do
 
   describe '#count_for' do
     it 'emits an event with an appropriate name' do
-      expect(Hallmonitor::Outputter).to(
+      expect(Hallmonitor::Dispatcher).to(
         receive(:output).with(an_event_with_name('thing.count_for_test')))
       Thing.new.count_for_test
     end
@@ -58,7 +58,7 @@ RSpec.describe Hallmonitor::Monitored do
     end
 
     it 'emits a timer event for the block' do
-      expect(Hallmonitor::Outputter).to(
+      expect(Hallmonitor::Dispatcher).to(
         receive(:output).with(a_timed_event_with_name(name)))
       subject.watch(name) do
         'foo'
@@ -67,7 +67,7 @@ RSpec.describe Hallmonitor::Monitored do
 
     describe 'when the block raises an error' do
       it 'emits a timer for the block' do
-        expect(Hallmonitor::Outputter).to(
+        expect(Hallmonitor::Dispatcher).to(
           receive(:output).with(a_timed_event_with_name(name)))
         expect {
           subject.watch(name) do
@@ -83,7 +83,7 @@ RSpec.describe Hallmonitor::Monitored do
       let(:name) { 'foo' }
 
       it 'emits an event with the passed in name' do
-        expect(Hallmonitor::Outputter).to(
+        expect(Hallmonitor::Dispatcher).to(
           receive(:output).with(an_event_with_name(name)))
         subject.emit(name)
       end
@@ -107,7 +107,7 @@ RSpec.describe Hallmonitor::Monitored do
       let(:event) { Hallmonitor::Event.new('bar') }
 
       it 'emits the passed in event' do
-        expect(Hallmonitor::Outputter).to receive(:output).with(event)
+        expect(Hallmonitor::Dispatcher).to receive(:output).with(event)
         subject.emit(event)
       end
     end

data/spec/spec_helper.rb

@@ -1,5 +1,7 @@
 require 'rubygems'
 require 'bundler'
+require 'pry'
+
 begin
   Bundler.setup(:default, :development)
 rescue Bundler::BundlerError => e

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: hallmonitor
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 1.0.0
 platform: ruby
 authors:
 - Chris TenHarmsel
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-03-17 00:00:00.000000000 Z
+date: 2015-03-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: json
@@ -31,7 +31,7 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-  type: :runtime
+  type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
@@ -138,6 +138,8 @@ files:
 - bin/example.rb
 - hallmonitor.gemspec
 - lib/hallmonitor.rb
+- lib/hallmonitor/configuration.rb
+- lib/hallmonitor/dispatcher.rb
 - lib/hallmonitor/event.rb
 - lib/hallmonitor/gauge_event.rb
 - lib/hallmonitor/middleware.rb
@@ -148,7 +150,8 @@ files:
 - lib/hallmonitor/outputters/statsd_outputter.rb
 - lib/hallmonitor/timed_event.rb
 - lib/hallmonitor/version.rb
-- spec/monitored_spec.rb
+- spec/hallmonitor/dispatcher_spec.rb
+- spec/hallmonitor/monitored_spec.rb
 - spec/spec_helper.rb
 homepage: http://github.com/epchris/hallmonitor
 licenses:
@@ -170,11 +173,12 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.2.2
+rubygems_version: 2.4.5
 signing_key: 
 specification_version: 4
 summary: Simple Ruby Event Monitoring
 test_files:
-- spec/monitored_spec.rb
+- spec/hallmonitor/dispatcher_spec.rb
+- spec/hallmonitor/monitored_spec.rb
 - spec/spec_helper.rb
 has_rdoc: