pd_metrics 1.0.0

data/.gitignore

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

data/Gemfile

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

data/README.md

@@ -0,0 +1,44 @@
+# PdMetrics
+
+Library to send metrics to Logstash, which then delivers them to PagerDuty's
+metric systems. This is pretty much only useful if you're a PagerDuty employee.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'pd_metrics'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install pd_metrics
+
+## Usage
+
+    # Captures timing metrics for a block of Ruby code.
+    PdMetrics.time('api', 'receive_email', account: 'Netflix') do
+      # process the email
+    end
+
+    # Captures an increase/decrease in a counter.
+    PdMetrics.incr('emails', 'bytes_received', email_bytes.size, account: 'Netflix')
+
+    # Captures the current value for a metric.
+    PdMetrics.gauge('ruby', 'live_objects', ObjectSpace.live_objects)
+
+    # Captures statistical metrics for a set of values within a given timeframe.
+    # This is very similar to the time method, but it's genericized for use in
+    # arbitrary values.
+    PdMetrics.histogram('api', 'payload_size', payload.size, account: 'Netflix')
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Rakefile

@@ -0,0 +1,10 @@
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new do |t|
+  t.libs << "test"
+  t.test_files = FileList['test/*_test.rb']
+  t.verbose = true
+end
+
+task :default => :test

data/lib/pd_metrics.rb

@@ -0,0 +1,236 @@
+require 'socket'
+require 'logger'
+
+require 'active_support/core_ext/class/attribute_accessors'
+
+class PdMetrics
+  cattr_accessor :settings
+  self.settings ||= {host: '127.0.0.1', port: 5959}
+
+  cattr_accessor :logger
+  self.logger ||= Logger.new('/dev/null')
+
+  # Logs an event to metric backend. In general, you can log any key value pairs.
+  #
+  #   PdMetrics.send_event('api', account: 'Netflix', wait_delta: 0.01, run_delta: 0.1)
+  #
+  # This will result in the following line being logged in SumoLogic. No data will be sent to DataDog.
+  #
+  #   api #account=Netflix|#run_delta=0.1|#wait_delta=0.01|
+  #
+  # In order to support aggregated graphs in DataDog, you'll need to mark the
+  # type of any numerical metrics you want aggregated.
+  #
+  #   PdMetrics.send_event('api', wait_delta: (0.01).histogram, run_delta: (0.1).histogram)
+  #
+  # This extra bit of detail is needed to let DataDog know how to aggregate multiple events in a single timeslice.
+  #
+  #   counter - adds together multiple data points. Use this for things like visits, errors, etc.
+  #   gauge - takes the last value. Use this for things like free memory, connections to database, etc.
+  #   histogram - derives count, avg, median, max, min, 95th percentile from a single value. Use this for this like latency, bytes written, etc.
+  #
+  # Note that when Datadog metrics are supplied, any non-metric data is passed
+  # to DataDog as tags. Depending on how many tags you have, this can be
+  # counterproductive in DataDog. To have additional data logged only to
+  # Sumologic, pass it in the additional_data paramter.
+  #
+  #   PdMetrics.send_event('api', {wait_delta: (0.01).histogram, run_delta: (0.1).histogram}, account: 'Netflix')
+  #
+  def self.send_event(namespace, metrics_and_tags = {}, additional_data = {})
+    logger.debug { "send_event #{namespace} #{metrics_and_tags.inspect} #{additional_data.inspect}" }
+    metrics_and_tags ||= {}
+    additional_data ||= {}
+
+    send_datadog_format(namespace, metrics_and_tags)
+    send_sumologic_format(namespace, metrics_and_tags, additional_data)
+  end
+
+  # Captures timing metrics for a block of Ruby code.
+  #
+  #   PdMetrics.time('api', 'receive_email', account: 'Netflix') do
+  #     # process the email
+  #   end
+  #
+  # Assuming the request took 2 seconds to process, the following log message will be written in SumoLogic.
+  #
+  #   api #account=Netflix|#receive_email=2.0|#failed=false|
+  #
+  # Additionally, the following histogram metrics will be captured in DataDog
+  #
+  #   api.receive_email.count
+  #   api.receive_email.avg
+  #   api.receive_email.median
+  #   api.receive_email.max
+  #   api.receive_email.95percentile
+  #
+  # In addition to capturing latency of the request, the success or failure of
+  # the block of code is captured as well. It is considered failed if an
+  # exception is thrown.
+  #
+  def self.time(namespace, key, tags = {}, additional_data = {})
+    failed = false
+    start = Time.now
+    yield
+  rescue
+    failed = true
+    raise
+  ensure
+    timing_data = tags || {}
+    timing_data[key] = (Time.now - start).histogram
+    timing_data['failed'] = failed
+    send_event(namespace, timing_data)
+  end
+
+  # Captures an increase/decrease in a counter.
+  #
+  # You can use this to capture metrics that should be added together when viewed on a graph.
+  #
+  #   PdMetrics.incr('logins', 'success')
+  #   PdMetrics.incr('emails', 'bytes_received', email_bytes.size, account: 'Netflix')
+  #
+  # That will produce the following line in SumoLogic.
+  #
+  #   logins #success=1
+  #   emails #account=Netflix|#bytes_received=1234|
+  #
+  # Additionally, the following metrics will be defined in DataDog
+  #
+  #   logins.success
+  #   emails.bytes_received
+  #
+  def self.incr(namespace, key, increment_by = 1, tags = {}, additional_data = {})
+    incr_data = tags || {}
+    incr_data[key] = increment_by.counter
+    send_event(namespace, incr_data, additional_data)
+  end
+
+  # Captures the current value for a metric.
+  #
+  # Unlike a counter, this value cannot be combined with itself in a meaningful
+  # way, so only the last reported value with a certain sampling frequency
+  # (normally every 10 seconds) is recorded in DataDog.
+  #
+  # You can use this method to capture metrics that change over time, like
+  # amount of memory used. Usually, this sampling occurs at a regular frequency
+  # via a timer.
+  #
+  #   PdMetrics.gauge('ruby', 'live_objects', ObjectSpace.live_objects)
+  #
+  # The following line will be printed in SumoLogic for each call to gauge.
+  #
+  #   ruby #live_objects=30873|
+  #
+  # Additionally, the following metric will be available in DataDog.
+  # 
+  #   ruby.live_objects
+  #
+  def self.gauge(namespace, key, value, tags = {}, additional_data = {})
+    gauge_data = tags || {}
+    gauge_data[key] = value.gauge
+    send_event(namespace, gauge_data, additional_data)
+  end
+
+  # Captures statistical metrics for a set of values within a given timeframe.
+  # This is very similar to the time method, but it's genericized for use in
+  # arbitrary values.
+  #
+  # An example usage would be calculating the size of JSON payloads received by
+  # an API. You could use a counter, but that wouldn't tease out what the
+  # average and median payload sizes are.
+  #
+  #   PdMetrics.histogram('api', 'payload_size', payload.size, account: 'Netflix')
+  #
+  # The following line will be printed in SumoLogic for every payload.
+  #
+  #   api #account=Netflix|#payload_size=1234
+  #   api #account=Netflix|#payload_size=0
+  #
+  # Additionally, DataDog will have the following metrics available. Note,
+  # these metrics are captured every 10 seconds, so they likely represent
+  # multiple requests within that time window.
+  #
+  #   api.payload_size.count
+  #   api.payload_size.avg
+  #   api.payload_size.median
+  #   api.payload_size.max
+  #   api.payload_size.95percentile
+  #
+  def self.histogram(namespace, key, value, tags = {}, additional_data = {})
+    histogram_data = tags || {}
+    histogram_data[key] = value.histogram
+    send_event(namespace, histogram_data, additional_data)
+  end
+
+  class NumericMetric
+    attr_reader :value
+
+    def initialize(value)
+      @value = value
+    end
+
+    def to_s
+      @value.to_s
+    end
+  end
+
+  class Gauge < NumericMetric
+    def statsd_format
+      "#{value}|g"
+    end
+  end
+
+  class Counter < NumericMetric
+    def statsd_format
+      "#{value}|c"
+    end
+  end
+
+  class Histogram < NumericMetric
+    def statsd_format
+      "#{value}|h"
+    end
+  end
+
+  private
+
+  def self.send_datadog_format(namespace, metrics_and_tags)
+    metrics, tag_pairs = metrics_and_tags.partition {|key, value| value.is_a?(NumericMetric) }
+    tags = tag_pairs.map {|d| "#{d[0]}:#{d[1]}" }.join(',')
+    metrics.each do |name, value|
+      msg = "#{namespace}.#{name}:#{value.statsd_format}"
+      msg += "|##{tags}" unless tags.empty?
+      msg += "\n"
+      write_to_socket(msg)
+    end
+  end
+
+  def self.send_sumologic_format(namespace, metrics_and_tags, additional_data)
+    sumologic_data = metrics_and_tags.merge(additional_data).sort {|a,b| a[0].to_s <=> b[0].to_s }
+    msg = "#{namespace} #{sumologic_data.map {|e| "##{e[0]}=#{e[1]}|" }.join}\n"
+    write_to_socket(msg)
+  end
+
+  def self.write_to_socket(msg)
+    @delivery_socket ||= Socket.new(Socket::PF_INET, Socket::SOCK_DGRAM)
+    @destination_addr ||= Socket.pack_sockaddr_in(settings[:port], settings[:host])
+    @delivery_socket.send(msg, 0, @destination_addr)
+  rescue => e
+    logger.warn { "Ignoring PdMetrics exception: #{e.class} #{e.message}" }
+  end
+
+  module NumericExtensions
+    def gauge
+      PdMetrics::Gauge.new(self)
+    end
+
+    def counter
+      PdMetrics::Counter.new(self)
+    end
+
+    def histogram
+      PdMetrics::Histogram.new(self)
+    end
+  end
+
+  Numeric.send(:include, NumericExtensions)
+end

data/lib/pd_metrics/version.rb

@@ -0,0 +1,3 @@
+class PdMetrics
+  VERSION = "1.0.0"
+end

data/pd_metrics.gemspec

@@ -0,0 +1,25 @@
+# -*- encoding: utf-8 -*-
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'pd_metrics/version'
+
+Gem::Specification.new do |gem|
+  gem.name          = "pd_metrics"
+  gem.version       = PdMetrics::VERSION
+  gem.authors       = ["Doug Barth"]
+  gem.email         = ["doug@pagerduty.com"]
+  gem.description   = %q{Library to send metrics to Logstash, which then delivers them to PagerDuty's metric systems}
+  gem.summary       = %q{PagerDuty's metrics integration library}
+  gem.homepage      = ""
+
+  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.require_paths = ["lib"]
+
+  gem.add_dependency 'activesupport', '~> 3.2'
+
+  gem.add_development_dependency 'timecop'
+  gem.add_development_dependency 'mocha'
+  gem.add_development_dependency 'minitest'
+end

data/test/pd_metrics_test.rb

@@ -0,0 +1,102 @@
+require 'test_helper'
+require 'pd_metrics'
+
+class PdMetrics
+  cattr_accessor :writes
+  self.writes = []
+
+  @original_write_to_socket = method(:write_to_socket)
+  def self.write_to_socket(msg)
+    writes << msg
+    @original_write_to_socket.call(msg)
+  end
+end
+
+class PdMetricsTest < ActiveSupport::TestCase
+  def setup
+    PdMetrics.writes = []
+  end
+
+  def teardown
+    Timecop.return
+  end
+
+  test "writes events in the SumoLogic format" do
+    PdMetrics.send_event('api', call: 1.counter, account: 'foo', wait_delta: (0.01).histogram)
+    assert_written_to_socket "api #account=foo|#call=1|#wait_delta=0.01|\n"
+  end
+
+  test "writes events in DataDog format" do
+    PdMetrics.send_event('api', call: 1.counter, account: 'foo', wait_delta: (0.01).histogram)
+    assert_written_to_socket "api.call:1|c|#account:foo\n"
+    assert_written_to_socket "api.wait_delta:0.01|h|#account:foo\n"
+  end
+
+  test "handles events with no DataDog compatible data" do
+    PdMetrics.send_event('api', account: 'foo', class: 'Blah')
+    assert_written_to_socket "api #account=foo|#class=Blah|\n"
+  end
+
+  test "handles multiple non-DataDog event data pairs in DataDog messages" do
+    PdMetrics.send_event('api', call: 1.counter, account: 'foo', class: 'Blah')
+    assert_written_to_socket "api.call:1|c|#account:foo,class:Blah\n"
+  end
+
+  test "ignores exceptions when writing to socket" do
+    Socket.any_instance.expects(:send).at_least_once.raises(RuntimeError, 'KABOOM')
+    PdMetrics.send_event('api', call: 1.counter, account: 'foo', class: 'Blah')
+  end
+
+  test "sends additional_data only to SumoLogic" do
+    PdMetrics.send_event('api', {call: 1.counter, account: 'foo'}, txn_id: 'abc123')
+    assert_written_to_socket "api.call:1|c|#account:foo\n"
+    assert_written_to_socket "api #account=foo|#call=1|#txn_id=abc123|\n"
+  end
+
+  test "time captures latency of a block" do
+    Timecop.freeze do
+      PdMetrics.time('api', 'create_event', account: 'foo') do
+        Timecop.freeze(2)
+      end
+    end
+    assert_written_to_socket "api #account=foo|#create_event=2.0|#failed=false|\n"
+    assert_written_to_socket "api.create_event:2.0|h|#account:foo,failed:false\n"
+  end
+
+  class ExpectedError < RuntimeError; end
+
+  test "time captures failures if exception is thrown" do
+    assert_raise(ExpectedError) do
+      Timecop.freeze do
+        PdMetrics.time('api', 'create_event', account: 'foo') do
+          Timecop.freeze(2)
+          raise ExpectedError
+        end
+      end
+    end
+    assert_written_to_socket "api #account=foo|#create_event=2.0|#failed=true|\n"
+    assert_written_to_socket "api.create_event:2.0|h|#account:foo,failed:true\n"
+  end
+
+  test "incr is a convenience method for counters" do
+    PdMetrics.incr('api', 'requests')
+    assert_written_to_socket "api #requests=1|\n"
+    assert_written_to_socket "api.requests:1|c\n"
+  end
+
+  test "gauge is a convenience method for gauges" do
+    PdMetrics.gauge('ruby', 'live_objects', 30873)
+    assert_written_to_socket "ruby #live_objects=30873|\n"
+    assert_written_to_socket "ruby.live_objects:30873|g\n"
+  end
+
+  test "histogram is a convenience method for statical metrics for a set of data" do
+    PdMetrics.histogram('api', 'payload_size', 1234, account: "Netflix")
+    assert_written_to_socket "api #account=Netflix|#payload_size=1234|\n"
+    assert_written_to_socket "api.payload_size:1234|h|#account:Netflix\n"
+  end
+
+  def assert_written_to_socket(msg)
+    assert_include PdMetrics.writes, msg
+  end
+end

data/test/test_helper.rb

@@ -0,0 +1,11 @@
+require 'rubygems'
+require 'bundler/setup'
+
+require 'minitest/autorun'
+
+require 'mocha/setup'
+Mocha::Deprecation.mode = :disabled
+
+require 'active_support/test_case'
+
+require 'timecop'

metadata

@@ -0,0 +1,122 @@
+--- !ruby/object:Gem::Specification
+name: pd_metrics
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+  prerelease: 
+platform: ruby
+authors:
+- Doug Barth
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-01-11 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '3.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '3.2'
+- !ruby/object:Gem::Dependency
+  name: timecop
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: mocha
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Library to send metrics to Logstash, which then delivers them to PagerDuty's
+  metric systems
+email:
+- doug@pagerduty.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- Gemfile
+- README.md
+- Rakefile
+- lib/pd_metrics.rb
+- lib/pd_metrics/version.rb
+- pd_metrics.gemspec
+- test/pd_metrics_test.rb
+- test/test_helper.rb
+homepage: ''
+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.24
+signing_key: 
+specification_version: 3
+summary: PagerDuty's metrics integration library
+test_files:
+- test/pd_metrics_test.rb
+- test/test_helper.rb
+has_rdoc: