yodeler 0.0.10 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 3e61910148974128f8852d2b671187a588150737
-  data.tar.gz: 7b22137cdea54c279888833b91729b8eb85c7ae4
+  metadata.gz: fa2389240d853b1e917ca4741cd9d8ca0c9bde03
+  data.tar.gz: 43aae361bf5632fea1641a3914f2b5390759cffe
 SHA512:
-  metadata.gz: 7dda2288ceb0a4e29d9f9927faefbb113f124c754a6e77318c29f980aa178ede37f3362b7e8b153b8f91f502fa0d7eb32193aee92665f484f831dc6184094a7a
-  data.tar.gz: 88e3857b1b847f493d2fe8609d0e143d4f29f8cff66885ac68144e078dbbe8fbee8f95d6ae545e0b9eca63b173a1d6f29a2b6948ed8954037bef0b45bb2b2738
+  metadata.gz: a081b0689cd5e2f0f2a3c192a54832459a0935f020aa7392a23ec3e4d9771fdff89280b120e57219e14507c597f38266ce71ae6150f67118ff7459fb42cf33be
+  data.tar.gz: 7eb2cd49a592a382610031303a10a1eeb4313c2893aa1c5d40e48ce0d7446dd04af2cd119aefaf5d2a5860f21f6252e4fa3401f6ef804f57f4b41ce4c6b9f1a7

data/.codeclimate.yml

@@ -0,0 +1,33 @@
+---
+engines:
+  brakeman:
+    enabled: false
+  bundler-audit:
+    enabled: true
+  duplication:
+    enabled: true
+    config:
+      languages:
+      - ruby
+  fixme:
+    enabled: true
+  rubocop:
+    enabled: true
+ratings:
+  paths:
+  - Gemfile.lock
+  - "**.erb"
+  - "**.haml"
+  - "**.rb"
+  - "**.rhtml"
+  - "**.slim"
+  - "**.inc"
+  - "**.js"
+  - "**.jsx"
+  - "**.module"
+  - "**.php"
+  - "**.py"
+exclude_paths:
+- config/**/*
+- db/**/*
+- spec/**/*

data/.gitignore

@@ -0,0 +1,9 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/

data/.rspec

@@ -0,0 +1,2 @@
+--format documentation
+--color

data/.travis.yml

@@ -0,0 +1,6 @@
+language: ruby
+rvm:
+  - 2.1.6
+  - 2.2.3
+  - 2.3.0
+before_install: gem install bundler -v 1.10.6

data/Gemfile

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

data/Guardfile

@@ -0,0 +1,16 @@
+guard :rspec, cmd: "bundle exec rspec" do
+  require "guard/rspec/dsl"
+  dsl = Guard::RSpec::Dsl.new(self)
+
+  # Feel free to open issues for suggestions and improvements
+
+  # RSpec files
+  rspec = dsl.rspec
+  watch(rspec.spec_helper) { rspec.spec_dir }
+  watch(rspec.spec_support) { rspec.spec_dir }
+  watch(rspec.spec_files)
+
+  # Ruby files
+  ruby = dsl.ruby
+  dsl.watch_spec_files_for(ruby.lib_files)
+end

data/README.md

@@ -1,106 +1,197 @@
-Yodeler
-=======
+# Yodeler
 
-Spouting noise to whoever is listening.
+A generic instrumentation library thats supports reporting to multiple endpoints via pluggable backend adapters.
 
-Yodeler is an easy way to notify users of different events that occur in your app.
+Spoutin' off noise to whoever is listening.
 
-  * Notify your marketing team on the 10,000 sign-up.
-  * Notify user's when their profile has been viewed
-  * Notify your dev team about events that are not quite exception worthy, but you don't want to dig through a bunch of logs to find.
+![Build Status](https://travis-ci.org/coryodaniel/yodeler.svg "Build Status")
+[![Test Coverage](https://codeclimate.com/github/coryodaniel/yodeler/badges/coverage.svg)](https://codeclimate.com/github/coryodaniel/yodeler/coverage)
+[![Code Climate](https://codeclimate.com/github/coryodaniel/yodeler/badges/gpa.svg)](https://codeclimate.com/github/coryodaniel/yodeler)
 
+## Installation
 
-Features
-========
+Add this line to your application's Gemfile:
 
-  * store notifications via ActiveRecord
-  * benchmark event duration
-  * i18n support  
-  * flexible payloads
-
-
-What's wrong with XMPP?
-=======================
+```ruby
+gem 'yodeler', '~>0.1.1'
+```
 
-  Why don't you fly to Walmart on a rocket?
+And then execute:
 
-  Don't even say it's because you don't have a rocket.
+    $ bundle
 
-  Why don't you kill ants with a bazooka?
+Or install it yourself as:
 
-  Nevermind, you get it.
+    $ gem install yodeler
 
+## Usage
 
-Usage
-=====
+### Configuration
 
+#### Single endpoint
+In ```config/initializers/yodeler.rb```
 ```ruby
-# in config/initializers/yodeler.rb
-Yodeler.register :another_thousand_users
-
-Yodeler.register :view_user do
-  # Default states are unread: 0, read: 1
-  config.states = {
-    unread:    0,
-    read:      1,
-    ignored:   2
-  }
+Yodeler.configure do |client|
+  # if no endpoint name is given, it defaults to :default
+  client.adapter(:http) do |http|
+    http.path = '/events'
+    http.host = 'example.com'
+    # http.port = 80
+    # http.use_ssl = false
+    # http.default_params = {}
+  end
 end
 ```
 
+#### Multiple Endpoints
+In ```config/initializers/yodeler.rb```
 ```ruby
-# in a controller or Anywhere you want to hear some noise
-class UserController < ApplicationController
-  around_action :track_user_view, only: :show
-  
-  def show
-    # do your User#show as normal
+
+Yodeler.configure do |client|
+  client.endpoint(:sales_reporting).adapter(:http) do |http|
+    http.path = '/events'
+    http.host = 'sales.example.com'
   end
 
-  private
+  client.endpoint(:devops_reporting).adapter(:http) do |http|
+    http.path = '/events'
+    http.host = 'devops.example.com'
+  end
 
-  def track_user_view
-    # This will also benchmark the action since it is in a block
-    Yodeler.dispatch :view_user, {viewer_id: 3, viewee_id: 23} do |payload|
-      yield #yield the action dispatch, the payload is available
+  # by default, the client dispatches to the first registered endpoint
+  # you can change it to a different one
+  # Alternatively you can dispatch to a set of endpoints when dispatching a metric
+  #   Yodeler.gauge('users.count', 35, to: [:sales_reporting, :devops_reporting])
+  client.default_endpoint_name = :devops_reporting
+end
+```
+
+#### Full Configuration Example
+In ```config/yodeler.yml```
+```yaml
+development:
+  auth_token: SOSECUREZ
+  sales_reporting:
+    host: localhost
+    port: 3030
+  devops_reporting:
+    host: localhost
+    port: 3031    
+```
+
+In ```config/initializers/yodeler.rb```
+```ruby
+config = YAML.load(File.read("./config/yodeler.yml"))[Rails.env]
+
+Yodeler.configure do |client|
+  client.endpoint(:sales_reporting).adapter(:http) do |http|
+    http.path = '/events'
+    http.host = config[:sales_reporting][:host]
+    http.port = config[:sales_reporting][:port]
+    http.default_params = {
+      auth_token: config[:auth_token]
+    }
+  end
+
+  client.endpoint(:devops_reporting).adapter(:http) do |http|
+    http.path = '/events'
+    http.host = config[:devops_reporting][:host]
+    http.port = config[:devops_reporting][:port]
+    http.default_params = {
+      auth_token: config[:auth_token]
+    }
+
+    # Overwrite the default http dispatcher or overwrite an individual metric dispatcher
+    #   http.handle(:gauge){|url, metric, default_params| ... something cool ... }
+    http.handle(:default) do |url, metric, default_params|
+      # This is the default handler definition, but you could change it
+      HTTP.post(url, json: default_params.merge(metric.to_hash))
     end
   end
+
+  client.default_endpoint_name = :devops_reporting
 end
+
 ```
 
+#### [Dashing Example](https://github.com/shopify/dashing)
 ```ruby
-# off in some scorned rails-observer
-class UserObserver
-  observers :user
-
-  def after_create
-    # let the marketing know another thousandth user has registered!
-    if (User.count % 1000).zero?
-      Yodeler.dispatch :another_thousand_users, {give_him_a_prize: @user.id}
-    end
+Yodeler.configure do |client|
+  client.endpoint(:karma_widget).adapter(:http) do |http|
+    http.path = '/widgets/karma'
+    http.host = 'localhost'
+    http.default_params = {
+      auth_token: config[:auth_token]
+    }
+  end
+
+  client.endpoint(:user_count_widget).adapter(:http) do |http|
+    http.path = '/widgets/user_count'
+    http.host = 'localhost'
+    http.default_params = {
+      auth_token: config[:auth_token]
+    }
   end
 end
 ```
 
+### Publishing Metrics and Events
 
-Getting around the objects
-==========================
+#### All instrumentation methods support an options hash
 
+* :prefix - [~String] :prefix your metric/event names
+* :tags   - [Array<String,Symbol>, String, Symbol] :tags ([]) array of tags to apply to metric/event
+* :sample_rate - [Float] :sample_rate (1.0) The sample rate to use
+* :to - [Array<Symbol>, Symbol] :to array of endpoint names to send the metric/event to. If not set will send to Yodeler::Client#default_endpoint_name
+
+#### Gauge
 ```ruby
-@event.subscriptions #=> Array<Yodeler::Subscription> all subscriber subscriptions
-@event.notifications #=> Array<Yodeler::Notifications>
+Yodeler.gauge 'user.count', 35
+Yodeler.gauge 'user.count', 35, prefix: 'test'
+Yodeler.gauge 'user.count', 35, sample_rate: 0.5
+Yodeler.gauge 'user.count', 35, prefix: 'test', tags: ['cool']
+Yodeler.gauge 'user.count', 35, to: [:devops_reporting, :sales_reporting]
+```
 
-@notification.subscriber #=> Your 'subscriber' class, delegated to #subscription
-@notification.subscription.subscriber
-@notification.event #=> The subscriber to event, delegated to #subscription
-@notification.message #=> i18n message interpolated w/ the payload
+#### Increment
+```ruby
+Yodeler.increment 'users.count'
+Yodeler.increment 'users.count', to: [:devops_reporting, :sales_reporting]
+Yodeler.increment 'revenue', 10_000
+Yodeler.increment 'revenue', 10_000, to: [:devops_reporting, :sales_reporting]
+
+```
 
-@subscription.subscriber #=> the 'subscriber' subscribed to this event
-@subscription.notifications #=> all notifications of this event type for this subscriber
-@subscription.event
+#### Timing
+```ruby
+Yodeler.timing('eat.sandwich', {prefix: :test}) do
+  user.eat(sandwich)
+end #=> returns result of block
 
+Yodeler.timing 'eat.sandwich', 250 #in ms
+Yodeler.timing 'eat.sandwich', 250, to: [:devops_reporting, :sales_reporting]
 ```
 
-TODO
-=======
-* Pluggable back-end, redis, obvi
+#### Event
+```ruby
+wizz_bang = {name: 'Wizz Bang 3000', image_url: 'http://example.com/wizzbang.jpg'}
+Yodeler.publish 'product.sold', wizz_bang
+Yodeler.publish 'product.sold', wizz_bang, prefix: 'ecommerce'
+Yodeler.publish 'product.sold', wizz_bang, sample_rate: 0.25
+Yodeler.publish 'product.sold', wizz_bang, to: [:devops_reporting, :sales_reporting]
+```
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/coryodaniel/yodeler.
+
+## TODOs
+  * [ ] Custom adapter documentation
+  * [ ] Client#format_options -> Metric.format_options
+  * [ ] Client#default_endpoint_name accept array of names

data/Rakefile

@@ -1,23 +1,6 @@
-begin
-  require 'bundler/setup'
-rescue LoadError
-  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
-end
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
 
-require 'rdoc/task'
-
-RDoc::Task.new(:rdoc) do |rdoc|
-  rdoc.rdoc_dir = 'rdoc'
-  rdoc.title    = 'Yodeler'
-  rdoc.options << '--line-numbers'
-  rdoc.rdoc_files.include('README.rdoc')
-  rdoc.rdoc_files.include('lib/**/*.rb')
-end
-
-APP_RAKEFILE = File.expand_path("../spec/test_app/Rakefile", __FILE__)
-load 'rails/tasks/engine.rake'
-
-
-
-Bundler::GemHelper.install_tasks
+RSpec::Core::RakeTask.new(:spec)
 
+task :default => :spec

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "yodeler"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start

data/bin/setup

@@ -0,0 +1,7 @@
+#!/bin/bash
+set -euo pipefail
+IFS=$'\n\t'
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/lib/yodeler/adapter_not_registered_error.rb

@@ -0,0 +1,14 @@
+module Yodeler
+  class AdapterNotRegisteredError < StandardError
+    attr_reader :name
+    def initialize(name:)
+      @name = name
+      msg = [
+        "No Yodeler Adapter registed for: ':#{name}'",
+        "Register an adapter with:",
+        "Yodeler.register_adapter(:#{name}, CustomAdapterClass)"
+      ].join("\n")
+      super(msg)
+    end
+  end
+end

data/lib/yodeler/adapters/http_adapter.rb

@@ -0,0 +1,51 @@
+require 'http'
+
+module Yodeler::Adapters
+  class HttpAdapter
+    attr_accessor :host
+    attr_accessor :port
+    attr_accessor :path
+    attr_accessor :use_ssl
+    attr_accessor :default_params
+
+    def initialize(host=nil, port:nil, path:nil, use_ssl:false, params:{})
+      @host = host
+      @port = port
+      @path = path
+      @use_ssl = use_ssl
+      @default_params = params
+      @handlers = {}
+
+      handle(:default) do |url, metric, default_params|
+        HTTP.post(url, json: default_params.merge(metric.to_hash))
+      end
+    end
+
+    def handle(type, &block)
+      @handlers[type] = block
+    end
+
+    def dispatch(metric)
+      (@handlers[metric.type] || @handlers[:default]).call(url, metric, default_params)
+    end
+
+    def url
+      "#{protocol}://#{host_with_port}#{path}"
+    end
+
+    private
+    def host_with_port
+      if port
+        "#{host}:#{port}"
+      else
+        host
+      end
+    end
+
+    def protocol
+      use_ssl ? :https : :http
+    end
+
+    Yodeler.register_adapter(:http, self)
+  end
+end

data/lib/yodeler/adapters/memory_adapter.rb

@@ -0,0 +1,23 @@
+module Yodeler::Adapters
+  class MemoryAdapter
+    attr_reader :queue
+    attr_accessor :max_queue_size
+
+    def initialize
+      @max_queue_size = 1000
+      flush!
+    end
+
+    def flush!
+      @queue = []
+    end
+
+    def dispatch(metric)
+      @queue << metric
+      @queue.shift if @queue.length > @max_queue_size
+      metric
+    end
+
+    Yodeler.register_adapter(:memory, self)
+  end
+end

data/lib/yodeler/adapters/void_adapter.rb

@@ -0,0 +1,10 @@
+module Yodeler::Adapters
+  class VoidAdapter
+
+    def dispatch(*)
+      #noop
+    end
+
+    Yodeler.register_adapter(:void, self)
+  end
+end

data/lib/yodeler/client.rb

@@ -0,0 +1,166 @@
+require 'socket'
+
+module Yodeler
+  class Client
+    attr_accessor :default_endpoint_name
+    attr_accessor :default_prefix
+    attr_accessor :default_sample_rate
+    attr_reader :endpoints
+
+    def initialize
+      @endpoints = {}
+      @default_sample_rate = 1.0
+      @default_prefix = nil
+      @hostname  = Socket.gethostname
+    end
+
+    # Register a new endpoint
+    #
+    # @param [Symbol|String] name of endpoint, must be unique
+    # @return [Yodeler::Endpoint]
+    def endpoint(name=:default, &block)
+      raise DuplicateEndpointNameError.new(name: name) if @endpoints[name]
+      @default_endpoint_name ||= name
+      @endpoints[name] = Endpoint.new(name,&block)
+    end
+
+    # Get the default endpoint
+    #
+    # @return [Yodeler::Endpoint] Get the default endpoint
+    def default_endpoint
+      @endpoints[default_endpoint_name]
+    end
+
+    # Syntax sugar for creating the default endpoint and set the adapter
+    #
+    # Useful if you just have one endpoint and don't care about its name
+    # like during testing or for simple metric reporting scenarios
+    # ... is this useful or is it a big ol' booger?
+    #
+    # @param [Symbol] name registered adapter name
+    # @param [Type] &block configuration for adapter
+    # @return [~Yodeler::Adapters::Base] the adapter
+    def adapter(name ,&block)
+      endpoint() if @endpoints.empty?
+      default_endpoint.use(name, &block)
+    end
+
+    # Set a gauge
+    #
+    # @example
+    #   client.gauge('users.count', 20_000_000)
+    #   client.gauge('users.count', 20_000_000, { tags: %w(something) })
+    #
+    # @param [~String] name of the metric
+    # @param [~Fixnum] value of the metric
+    # @param [Hash] opts={} Examples {#format_options}
+    # @return [Yodeler::Metric, nil] the dispatched metric, nil if not sampled
+    def gauge(name, value, opts={})
+      dispatch(:gauge, name, value, opts)
+    end
+
+    # Increment a counter
+    #
+    # @example
+    #   client.increment 'user.signup'
+    #   client.increment 'user.signup', {}
+    #   client.increment 'user.signup', 1, {}
+    #
+    # @param [~String] name of the metric
+    # @param [~Fixnum] value=1 of the metric
+    # @param [Hash] opts={} Examples {#format_options}
+    # @return [Yodeler::Metric, nil] the dispatched metric, nil if not sampled
+    def increment(name, value=1, opts={})
+      if value.kind_of?(Hash)
+        opts = value
+        value = 1
+      end
+      dispatch(:increment, name, value, opts)
+    end
+
+    # Measure how long something takes
+    #
+    # @example
+    #   client.timing 'eat.sandwich', 250
+    #   client.timing('eat.pizza') do
+    #     user.eat(pizza) #=> THAT WAS QUICK FATSO!
+    #   end
+    #
+    # @param [~String] name of the metric
+    # @param [~Fixnum] value time in ms
+    # @param [Hash] opts={} Examples {#format_options}
+    # @return [Yodeler::Metric, nil, Object]
+    #   the dispatched metric, nil if not sampled
+    #   if a block is given the result of the block is returned
+    def timing(name, value=nil, opts={})
+      if value.kind_of?(Hash)
+        opts = value
+        value = nil
+      end
+
+      _retval = nil
+
+      if block_given?
+        start = Time.now
+        _retval = yield
+        value = Time.now - start
+      end
+
+      metric = dispatch(:timing, name, value, opts)
+      _retval || metric
+    end
+
+    # Publish an event
+    #
+    # @example
+    #   client.publish('item.sold', purchase.to_json)
+    #   client.publish('user.sign_up', {name: user.name, avatar: user.image_url})
+    #
+    # @param [~String] name of the metric
+    # @param [~Hash] value of the metric
+    # @param [Hash] opts={} Examples {#format_options}
+    # @return [Yodeler::Metric, nil] the dispatched metric, nil if not sampled
+    def publish(name, payload, opts={})
+      dispatch(:event, name, payload, opts)
+    end
+
+    # Formats/Defaults metric options
+    #
+    # @param [Hash] opts metric options
+    # @option opts [Array<String,Symbol>, String, Symbol] :tags ([]) array of tags to apply to metric/event
+    # @option opts [Float] :sample_rate (1.0) The sample rate to use
+    # @option opts [Array<Symbol>, Symbol] :to array of endpoint names to send the metric to. If not set will send to {Yodeler::Client#default_endpoint_name}
+    # @return [Hash] formatted, defaulted options
+    def format_options(opts)
+      endpoint_names  = opts.delete(:to) || [default_endpoint_name]
+      tags            = opts.delete(:tags)
+      prefix          = opts.delete(:prefix) || default_prefix
+
+      {
+        prefix:       prefix,
+        to:           [endpoint_names].flatten.compact,
+        sample_rate:  opts.delete(:sample_rate) || default_sample_rate,
+        tags:         [tags].flatten.compact,
+        hostname:     @hostname
+      }
+    end
+
+    private
+
+    def dispatch(type, name, value, opts)
+      opts = format_options(opts)
+      destinations = opts.delete(:to)
+      metric = Metric.new(type, name, value, opts)
+
+      return nil unless metric.sample?
+
+      destinations.each do |endpoint_name|
+        if @endpoints[endpoint_name]
+          @endpoints[endpoint_name].adapter.dispatch(metric)
+        end
+      end
+
+      metric
+    end
+  end
+end