metricsd 0.1.0 → 0.2.0

data/.gitignore

@@ -2,3 +2,5 @@
 .bundle
 Gemfile.lock
 pkg/*
+.yardoc
+doc

data/CHANGELOG.md

@@ -0,0 +1,16 @@
+## 0.2.0 (July 27, 2011)
+
+Features:
+
+  - Added an option to enable or disable client
+
+## 0.1.0 (July 26, 2011)
+
+Features:
+
+  - Complete MetricsD protocol implementation
+  - Allows to send multiple metrics in a single network packet
+  - Splits metrics to several packets of 250 bytes or less
+  - Allows to specify metrics parts separator (temporary solution until all the metrics will be migrated to "." separator)
+  - Logs network problems to logger and never throws errors like this.
+  - 100% test coverage

data/Rakefile

@@ -1 +1,7 @@
 require 'bundler/gem_tasks'
+
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new(:spec)
+
+task :test => :spec
+task :default => :spec

data/lib/metricsd/client.rb

@@ -25,7 +25,7 @@ module Metricsd
   #     'db.pool.pending'   => db_stats[:pending],
   #   }, :group => 'doc_timestamp')
   #
-  # You can specify message source using :source => 'src' option. In this case
+  # You can specify message source using <tt>:source => 'src'</tt> option. In this case
   # you will be able to see summary graphs and graphs per source:
   #
   #   # Generate graphs for all tables, and each single table.
@@ -39,7 +39,7 @@ module Metricsd
   #   # ... or you can pass an empty string with the same effect.
   #   Metricsd::Client.record_success("hbase.reads", :source => '')
   #
-  # You can group your metrics using :group option. In this case metrics will be
+  # You can group your metrics using <tt>:group</tt> option. In this case metrics will be
   # displayed together on the summary page.
   #
   #   # Group metrics using :group option.
@@ -51,6 +51,19 @@ module Metricsd
     class << self
       # Record complete hit info. Time should be a floating point
       # number of seconds.
+      #
+      # It creates two metrics:
+      # * +your.metric.count+ with counts of failed and succeded events
+      # * +your.metric.time+ with time statistics
+      #
+      # @param [String] metric is the metric name (like app.docs.upload)
+      # @param [Boolean] is_success indicating whether request was successful.
+      # @param [Float] time floating point number of seconds.
+      # @param [Hash] opts options.
+      # @option opts [String] :sep ("_") separator used to add suffixes +count+ and +time+.
+      # @option opts [String] :group metrics group.
+      # @option opts [String] :source metric source.
+      #
       def record_hit(metric, is_success, time, opts = {})
         sep = opts[:sep] || opts[:separator] || '_'
         record_internal({
@@ -60,26 +73,51 @@ module Metricsd
         )
       end
 
-      # Record success hit.
+      # Record succeded boolean event.
+      #
+      # It creates a single metric:
+      # * +your.metric.count+ with numbers of failed and succeded events
+      #
+      # @param [String] metric is the metric name (like app.docs.upload)
+      # @param [Hash] opts options.
+      # @option opts [String] :sep ("_") separator used to add suffixes +count+ and +time+.
+      # @option opts [String] :group metrics group.
+      # @option opts [String] :source metric source.
+      #
       def record_success(metric, opts = {})
         sep = opts[:sep] || opts[:separator] || '_'
-        record_internal({
-            "#{metric}#{sep}count" => 1
-          }, opts
-        )
+        record_internal({"#{metric}#{sep}count" => 1}, opts)
       end
 
-      # Record success failure.
+      # Record failed boolean event.
+      #
+      # It creates a single metric:
+      # * +your.metric.count+ with numbers of failed and succeded events
+      #
+      # @param [String] metric is the metric name (like app.docs.upload)
+      # @param [Hash] opts options.
+      # @option opts [String] :sep ("_") separator used to add suffixes +count+ and +time+.
+      # @option opts [String] :group metrics group.
+      # @option opts [String] :source metric source.
+      #
       def record_failure(metric, opts = {})
         sep = opts[:sep] || opts[:separator] || '_'
-        record_internal({
-            "#{metric}#{sep}count" => -1
-          }, opts
-        )
+        record_internal({"#{metric}#{sep}count" => -1}, opts)
       end
 
       # Record timing info. Time should be a floating point
       # number of seconds.
+      #
+      # It creates a single metric:
+      # * +your.metric.time+ with time statistics
+      #
+      # @param [String] metric is the metric name (like app.docs.upload)
+      # @param [Float] time floating point number of seconds.
+      # @param [Hash] opts options.
+      # @option opts [String] :sep ("_") separator used to add suffixes +count+ and +time+.
+      # @option opts [String] :group metrics group.
+      # @option opts [String] :source metric source.
+      #
       def record_time(metric, time = nil, opts = {}, &block)
         opts, time = time, nil if Hash === time
         sep = opts[:sep] || opts[:separator] || '_'
@@ -87,31 +125,55 @@ module Metricsd
           raise ArgumentError, "You should pass a block if time is not given" unless block_given?
           time = Benchmark.measure(&block).real
         end
-        record_internal({
-            "#{metric}#{sep}time" => (time * 1000).round
-          }, opts
-        )
+        record_internal({"#{metric}#{sep}time" => (time * 1000).round}, opts)
       end
 
       # Record an integer value.
+      #
+      # It creates a single metric:
+      # * +your.metric+ with values statistics
+      #
+      # @param [String] metric is the metric name (like app.docs.upload)
+      # @param [Integer] value metric value.
+      # @param [Hash] opts options.
+      # @option opts [String] :sep ("_") separator used to add suffixes +count+ and +time+.
+      # @option opts [String] :group metrics group.
+      # @option opts [String] :source metric source.
+      #
       def record_value(metric, value, opts = {})
-        record_internal({
-            metric => value.round
-          }, opts
-        )
+        record_internal({metric => value.round}, opts)
       end
 
-      # Record multiple values.
+      # Record multiple integer values.
+      #
+      # It creates a metric for each entry in +metrics+ Hash:
+      # * +your.metric+ with values statistics
+      #
+      # @param [Hash] metrics a +Hash+ that maps metrics names to their values.
+      # @param [Hash] opts options.
+      # @option opts [String] :sep ("_") separator used to add suffixes +count+ and +time+.
+      # @option opts [String] :group metrics group.
+      # @option opts [String] :source metric source.
+      #
+      # @example
+      #   Metricsd::Client.record_values(
+      #     'db.pool.reserved'  => db_stats[:reserved],
+      #     'db.pool.available' => db_stats[:available],
+      #     'db.pool.pending'   => db_stats[:pending],
+      #   )
+      #
       def record_values(metrics, opts = {})
         record_internal(metrics, opts)
       end
 
+      # Reset and re-establish connection.
       def reset_connection!
         @@socket = nil
       end
 
     private
 
+      # Returns a UDP socket used to send metrics to MetricsD.
       def collector_socket
         @@socket ||= begin
           @@socket = UDPSocket.new
@@ -121,6 +183,8 @@ module Metricsd
 
       # Send informating to the RRD collector daemon using UDP protocol.
       def record_internal(metrics, opts = {})
+        return unless Metricsd.enabled?
+
         opts = { :source => Metricsd.default_source }.update(opts)
         opts[:source] = Metricsd.source if opts[:source].empty?
 
@@ -128,6 +192,8 @@ module Metricsd
         send_in_packets Array(metrics).map { |arg| pack(arg[0], arg[1], opts) }.sort
       end
 
+      # Combines string representations of metrics into packets of 250 bytes and
+      # sends them to MetricsD.
       def send_in_packets(strings)
         msg = ''
         strings.each do |s|
@@ -145,6 +211,8 @@ module Metricsd
         safe_send(msg) if msg.size > 0
       end
 
+      # Sends a string to the MetricsD. Should never raise any network-specific
+      # exceptions, but log them instead, and silently return.
       def safe_send(msg)
         collector_socket.send(msg, 0)
         true
@@ -154,6 +222,8 @@ module Metricsd
         false
       end
 
+      # Packs metric into a string representation according to the MetricsD
+      # protocol.
       def pack(key, value, opts)
         key = "#{opts[:group]}$#{key}" unless opts[:group].nil? || opts[:group].empty?
         opts[:source].empty? ? "#{key}:#{value}" : "#{opts[:source]}@#{key}:#{value}"

data/lib/metricsd/version.rb

@@ -1,3 +1,3 @@
 module Metricsd
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

data/lib/metricsd.rb

@@ -2,42 +2,77 @@ require 'socket'
 require 'logger'
 require 'benchmark'
 
+# Pure Ruby client library for MetricsD server.
 module Metricsd
   class << self
+    # Gets the MetricsD server host. Default is "127.0.0.1".
     def server_host
       @@server_host
     end
 
+    # Sets the MetricsD server host.
     def server_host=(host)
       @@server_host = host
       Client.reset_connection!
     end
 
+    # Gets the MetricsD server port. Default is 6311.
     def server_port
       @@server_port
     end
 
+    # Sets the MetricsD server port.
     def server_port=(port)
       @@server_port = Integer(port)
       Client.reset_connection!
     end
 
+    # Get the value indicating whether Metricsd is enabled.
+    def enabled?
+      !!@@enabled
+    end
+    alias :enabled :enabled?
+
+    # Sets the value indicating whether Metricsd is enabled.
+    def enabled=(enabled)
+      @@enabled = !!enabled
+    end
+
+    # Enables Metricsd client.
+    def enable!
+      @@enabled = true
+    end
+
+    # Disables Metricsd client.
+    def disable!
+      @@enabled = false
+    end
+
+    # Gets the source used to record host-specific metrics. Default is the
+    # first part of the hostname (e.g. "test" for "test.host.com").
     def source
       @@source || metricsd.default_source
     end
 
+    # Sets the source for host-specific metrics.
     def source=(source)
       @@source = source
     end
 
+    # Gets the default source for all metrics. If nil or empty string — all
+    # metrics will be host-specific (MetricsD server will generate per-host
+    # graphs in addition to summary graph for all hosts for each metric).
+    # Default is "all".
     def default_source
       @@default_source
     end
 
+    # Sets the default source for all metrics.
     def default_source=(source)
       @@default_source = source
     end
 
+    # Gets the logger used to output errors or warnings.
     def logger
       @@logger ||= if defined?(Rails)
         Rails.logger
@@ -48,13 +83,16 @@ module Metricsd
       end
     end
 
+    # Sets the logger used to output errors or warnings.
     def logger=(logger)
       @@logger = logger
     end
 
+    # Resets all values to their default state (mostly for testing purpose).
     def reset_defaults!
       @@server_host    = '127.0.0.1'
       @@server_port    = 6311
+      @@enabled        = true
       @@source         = Socket.gethostname[/^([^.]+)/, 1]
       @@default_source = 'all'
       @@logger         = nil

data/metricsd.gemspec

@@ -11,6 +11,7 @@ Gem::Specification.new do |s|
   s.summary     = %q{Client library for MetricsD server}
   s.description = %q{}
 
+  s.add_development_dependency 'rake'
   s.add_development_dependency 'rspec'
   s.add_development_dependency 'guard-rspec'
   s.add_development_dependency 'rb-fsevent'

data/spec/client_spec.rb

@@ -5,7 +5,9 @@ describe Metricsd::Client do
   before :each do
     @socket = mock('Socket')
     Metricsd::Client.stub!(:collector_socket => @socket)
-    Metricsd.stub!(:source => 'test')
+    # Global settings
+    Metricsd.reset_defaults!
+    Metricsd.source = 'test'
   end
 
   describe 'connection' do
@@ -15,6 +17,12 @@ describe Metricsd::Client do
       Metricsd.logger.should_receive(:error).at_least(1) # stacktrace
       Metricsd::Client.record_value('custom.metric', 5)
     end
+
+    it 'should not send anything to the socket if disabled' do
+      Metricsd.disable!
+      @socket.should_not_receive(:send)
+      Metricsd::Client.record_value('custom.metric', 5)
+    end
   end
 
   describe '.record_hit' do

data/spec/metricsd_spec.rb

@@ -28,6 +28,11 @@ describe Metricsd do
     it 'should create logger' do
       Metricsd.logger.should be_a(Logger)
     end
+
+    it 'should be enabled' do
+      Metricsd.enabled?.should be_true
+      Metricsd.enabled.should be_true
+    end
   end
 
   context 'setters' do
@@ -47,6 +52,20 @@ describe Metricsd do
       }.to raise_error
     end
 
+    it 'should allow to enabled and disable client' do
+      Metricsd.enabled = false
+      Metricsd.should_not be_enabled
+
+      Metricsd.enable!
+      Metricsd.should be_enabled
+
+      Metricsd.disable!
+      Metricsd.should_not be_enabled
+
+      Metricsd.enabled = true
+      Metricsd.should be_enabled
+    end
+
     it 'should allow to change source' do
       Metricsd.source = 'test-host'
       Metricsd.source.should == 'test-host'

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: metricsd
 version: !ruby/object:Gem::Version 
-  hash: 27
+  hash: 23
   prerelease: 
   segments: 
   - 0
-  - 1
+  - 2
   - 0
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors: 
 - Dmytro Shteflyuk
@@ -19,7 +19,7 @@ date: 2011-07-27 00:00:00 -04:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
-  name: rspec
+  name: rake
   prerelease: false
   requirement: &id001 !ruby/object:Gem::Requirement 
     none: false
@@ -33,7 +33,7 @@ dependencies:
   type: :development
   version_requirements: *id001
 - !ruby/object:Gem::Dependency 
-  name: guard-rspec
+  name: rspec
   prerelease: false
   requirement: &id002 !ruby/object:Gem::Requirement 
     none: false
@@ -47,7 +47,7 @@ dependencies:
   type: :development
   version_requirements: *id002
 - !ruby/object:Gem::Dependency 
-  name: rb-fsevent
+  name: guard-rspec
   prerelease: false
   requirement: &id003 !ruby/object:Gem::Requirement 
     none: false
@@ -61,7 +61,7 @@ dependencies:
   type: :development
   version_requirements: *id003
 - !ruby/object:Gem::Dependency 
-  name: growl
+  name: rb-fsevent
   prerelease: false
   requirement: &id004 !ruby/object:Gem::Requirement 
     none: false
@@ -74,6 +74,20 @@ dependencies:
         version: "0"
   type: :development
   version_requirements: *id004
+- !ruby/object:Gem::Dependency 
+  name: growl
+  prerelease: false
+  requirement: &id005 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id005
 description: ""
 email: 
 - kpumuk@kpumuk.info
@@ -86,6 +100,7 @@ extra_rdoc_files: []
 files: 
 - .gitignore
 - .rvmrc
+- CHANGELOG.md
 - Gemfile
 - Guardfile
 - README.md